deepcrew-ai
Multi-agent AI library for Python. Build parallel workflows, spawn agents dynamically, attach tools via MCP, let agents refine their own answers and remember past runs, and stream events in real time — using any of 100+ LLM providers, with minimal boilerplate.
pip install deepcrew-ai
Full docs: deepcrew-ai.aayushjoshi.dev · Features guide · Examples · Migrating from CrewAI/ADK
Table of contents
- What's new in v0.6.0 — Episodic Memory
- What's new in v0.5.0 — Structured Logging
- What's new in v0.4.0 — Production Readiness & Streaming-First
- What's new in v0.3.0 — Self-Improving Loop
- Features
- Quick Start
- Orchestration Modes
- Feature Guide
- Composing v0.3.0 Features
- MCP Tools
- Provider Examples
- Streaming with FastAPI
- Stream Events
- Installation
- Development & Testing
- Documentation
- License
What's new in v0.6.0 — Episodic Memory
A third memory concept, the specifics-keeping one — a durable log of past runs that is
recalled by relevance before each new run. Also: an optional LLM reflector for
ProceduralMemory, and an opt-in live-test harness (pytest --live, Gemini) with a
content-hash ledger so a verified feature is not re-run until its code changes.
| Feature | Description |
|---|---|
EpisodicMemory |
Ring-buffer log of Episode records (query, response, outcome, score, tools, timestamp). Layers on any MemoryProvider |
| Automatic cycle | Agent(episodic_memory=...) recalls relevant past episodes into context before every run and records the outcome after — one per iteration in a loop |
| Relevance recall | recall() ranks by keyword (Jaccard) overlap + recency; dependency-free, no embeddings. AgentResult.episodes_recalled reports the count |
| Optional reflection | EpisodicMemory(reflect_model=...) and ProceduralMemory(reflect_model=...) distil a lesson per episode / curation with one LLM call. Off by default |
procedural_task_tag |
Agent.procedural_task_tag aligns single-shot playbook reads with a loop's custom LoopConfig.task_tag |
| Live tests + ledger | tests/live/ (pytest --live, GEMINI_API_KEY) with LEDGER.json / LEDGER.md: a feature whose watched source files are unchanged since its last live pass is skipped |
from deepcrew import Agent, EpisodicMemory, run_agent
from deepcrew.memory import FileMemoryProvider
episodic = EpisodicMemory(FileMemoryProvider("episodes.json"), namespace="support-bot")
agent = Agent(name="assistant", model="gemini/gemini-3.5-flash-lite", episodic_memory=episodic)
await run_agent(agent, [{"role": "user", "content": "How do I rotate an API key?"}])
r = await run_agent(agent, [{"role": "user", "content": "Is key rotation zero-downtime?"}])
print(r.episodes_recalled) # >= 1
See the Episodic Memory guide
and tests/live/README.md.
What's new in v0.5.0 — Structured Logging
A general-purpose logging layer, off by default (library NullHandler), separate from
OpenTelemetry (ObservabilityConfig) and from the StreamEvent queue.
| Feature | Description |
|---|---|
configure_logging() |
One call turns logging on. Named profiles dev / prod (JSON) / verbose / quiet, or ad-hoc level / format / color / timestamps knobs |
| Env-var toggles | DEEPCREW_LOG_PROFILE, DEEPCREW_LOG_LEVEL, DEEPCREW_LOG_FORMAT, DEEPCREW_LOG_TIME, DEEPCREW_LOG_COLOR — always win over code; auto-configure on first use |
get_logger() |
Public, first-class API for your own tools/components. Extra kwargs become structured fields; .bind() carries context; namespaced under deepcrew.* so one call styles everything |
| Levels | Stdlib names only (CRITICAL…DEBUG) plus TRACE (5); no invented levels |
| Colour | rich when installed ([log] extra), plain ANSI fallback otherwise; honours NO_COLOR / FORCE_COLOR / TTY |
| Coverage | Structured event=-tagged logs across runner, orchestrator, loop, spawner, APEX, verifier, retry, workflow, and MCP; CLI gains -v / --log-profile / --log-json / -q |
from deepcrew import configure_logging, get_logger
configure_logging("dev") # colour + DEBUG; or "prod" for JSON lines
log = get_logger("myapp.tools.pricing")
log.info("price lookup", sku=sku, region=region) # kwargs → structured fields
See the Logging guide.
What's new in v0.4.0 — Production Readiness & Streaming-First
| Feature | Description |
|---|---|
| Multimodal Input | image(), pdf(), user_message() — attach images and PDFs to any message as standard content blocks |
| StreamPolicy | chat() / standard() / verbose() presets (or a custom set) control exactly which event types a consumer sees |
| FastAPI Integration | create_stream_router() turns an Agent, Orchestrator, or WorkflowBuilder into an SSE endpoint in one call (fastapi extra) |
| Structured Output | Agent(response_model=...) validates the final answer against a pydantic schema; result on AgentResult.parsed |
| Human-in-the-Loop Hooks | AgentHooks.approve_tool can deny an individual tool call before it runs |
| Redis Memory Provider | RedisMemoryProvider — a persistent, shared MemoryProvider backed by Redis (redis extra) |
| Production hardening | py.typed, ruff + mypy in CI, a version-consistency check, and a tagged release workflow that publishes to PyPI with twine and attaches the wheel/sdist to a GitHub Release |
from deepcrew import Agent, run_agent, image, pdf, user_message
agent = Agent(name="analyst", model="anthropic/claude-opus-4-8")
msg = user_message(
"Summarize this chart against the report.", image("chart.png"), pdf("report.pdf")
)
result = await run_agent(agent, [msg])
See the features guide for full examples of every feature above, and the migration guide if you're coming from CrewAI or Google ADK.
What's new in v0.3.0 — Self-Improving Loop
v0.3.0 turns the outer refinement loop (LoopConfig) from a simple "re-run until a
boolean says stop" mechanism into a genuinely self-improving one, and gives agent
spawning bounded recursion. Every addition is opt-in and fully backward compatible.
| Feature | Description |
|---|---|
| APEX Synthesizer | Intelligent synthesis with confidence scoring and source citation |
| Agent Spawning | Claude Code-style — agents can spawn sub-agents mid-loop with intelligent tool allocation |
| Nested Spawning | A spawned sub-agent can itself spawn further sub-agents up to a hard, bounded depth cap |
| Looping | Outer iteration loop for search-refine patterns with convergence control |
| Verifier | Structured, LLM-graded critique (score + issues + suggestion) driving targeted refinement |
| Adaptive Budget | Plateau-detection early exit — stop once refinement stops paying off, bounded by max_iterations |
| Branching | Parallel self-consistency candidates per iteration, scored by Verifier or merged via APEX |
| Skills | Higher-level capability bundles: WebSearchSkill, SummarizeSkill, CodeExecutionSkill, @skill decorator |
| Self-Evolving Skills | A converged, high-confidence loop run is distilled into a reusable, replayable Skill |
| Memory | Pluggable InMemoryProvider and FileMemoryProvider — auto-injected into agent context |
| Procedural Memory | An opt-in, durable evolving playbook of strategies accumulated across runs (ACE-inspired) |
| Episodic Memory | A durable log of past runs (EpisodicMemory / Episode), recalled by similarity + recency before each new run |
| Retry & Fallback | Per-agent RetryPolicy + FallbackChain for model resilience |
| Observability | OpenTelemetry spans for every LLM call, tool execution, and workflow step |
| Logging | Toggleable structured/colour logs (configure_logging), named profiles, JSON output, and a shared get_logger() for your own components |
| CLI | deepcrew run workflow.yaml — declarative workflow execution |
Features
- 100+ LLM providers via LiteLLM — OpenAI, Anthropic, Gemini, Bedrock, Azure, Ollama, and more
- Two orchestration modes — explicit DAG
WorkflowBuilderor automatedOrchestratorrouting - APEX synthesis — confidence-scored, citation-aware multi-agent result merging
- Parallel execution —
asyncio.gatherat every level: tools, agents, workflow nodes - MCP tool integration — stdio (subprocess), SSE (legacy), and streamable-HTTP transports
- Python function tools —
@tooldecorator; JSON Schema auto-generated from type hints - Self-improving loop —
LoopConfig+Verifier: scored refinement, adaptive early-stop, self-consistency branching, skill distillation - Bounded agent spawning — agents spawn sub-agents mid-run, hard-capped by
max_spawn_depth - Skills — reusable capability bundles exposed to the LLM as tools
- Three memory types — semantic (
MemoryProvider), procedural (ProceduralMemory, an evolving playbook) and episodic (EpisodicMemory, a log of past runs recalled before each run) - Multimodal input —
image(),pdf(),user_message(); structured output viaresponse_model; human-in-the-loop tool approval viaAgentHooks - Retry & fallback — per-agent exponential backoff + model fallback chains
- Streaming — true token streaming, selectable visibility (
StreamPolicy), FastAPI SSE integration - OpenTelemetry — optional OTel span emission for every LLM call and tool execution
- Structured logging — opt-in, profile-based (dev/prod/verbose/quiet), JSON or coloured text,
get_logger()for your own components - CLI —
deepcrew run workflow.yamlfor declarative workflow files - Live-verified — opt-in Gemini live tests with a content-hash ledger (see Development & Testing)
Quick Start
import asyncio
from deepcrew import Agent, run_agent, tool
@tool
def get_weather(city: str) -> dict:
"Get current weather for a city."
return {"city": city, "temp": 22, "condition": "sunny"}
async def main():
agent = Agent(
name="assistant",
model="openai/gpt-4o-mini",
system_prompt="You are a helpful assistant.",
tools=[get_weather],
)
result = await run_agent(agent, [{"role": "user", "content": "Weather in Tokyo?"}])
print(result.text)
asyncio.run(main())
Orchestration Modes
Workflow Builder — explicit DAG
Define agents and their dependencies. Independent nodes run in parallel automatically.
from deepcrew import Agent, WorkflowBuilder
researcher = Agent(
"researcher", model="openai/gpt-4o-mini", system_prompt="Research the topic thoroughly."
)
critic = Agent(
"critic",
model="anthropic/claude-haiku-4-5-20251001",
system_prompt="Find gaps and weaknesses in the research.",
)
writer = Agent("writer", model="openai/gpt-4o", system_prompt="Write a polished report.")
workflow = (
WorkflowBuilder()
.add_agent("research", researcher, task="{input}")
.add_agent("critique", critic, task="Critique this research:\n{research}")
.add_agent("report", writer, task="Write a report using:\n{research}\n\nCritique:\n{critique}")
.then("research", "critique")
.then("research", "report")
.then("critique", "report")
)
result = await workflow.run("The future of renewable energy")
print(result.final_output.text)
Orchestrator — automated AI routing with APEX
NIA (Navigator & Intelligence Allocator), the router LLM, decides which agents to run; APEX synthesizes the results.
from deepcrew import Agent, Orchestrator, ApexConfig
agents = [
Agent("researcher", model="openai/gpt-4o-mini", system_prompt="Research specialist."),
Agent("analyst", model="gemini/gemini-2.0-flash", system_prompt="Data analyst."),
Agent("writer", model="anthropic/claude-haiku-4-5-20251001", system_prompt="Content writer."),
]
orch = Orchestrator(
agents=agents,
router_model="openai/gpt-4o-mini",
apex_model="openai/gpt-4o",
apex_config=ApexConfig(cite_sources=True, confidence_threshold=0.8),
)
result = await orch.run("State of quantum computing in 2026")
print(result.final_text)
Feature Guide
APEX Synthesizer
APEX (Assembly & Precision EXecutor) replaces the plain synthesizer with confidence scoring and source citation.
from deepcrew import APEXSynthesizer, ApexConfig, AgentResult
apex = APEXSynthesizer(
model="openai/gpt-4o",
config=ApexConfig(
cite_sources=True, # adds [source: agent_name] markers
confidence_threshold=0.8,
allow_tools=False,
),
)
result = await apex.synthesize("What is quantum computing?", agent_results)
print(result.text) # synthesis with optional citations
print(result.confidence) # float 0.0–1.0
Agent Spawning
Any agent can dynamically spawn sub-agents mid-loop with intelligent tool allocation.
from deepcrew import Agent, Orchestrator, tool
@tool
def search_web(query: str) -> str: ...
@tool
def read_file(path: str) -> str: ...
orch = Orchestrator(
agents=[master_agent],
global_tools=[search_web, read_file], # pool available for sub-agents
enable_spawn=True, # inject spawn_agent tool into every agent
)
# The master_agent can now call spawn_agent(task="...", model="...") mid-loop
Nested spawning (bounded)
A spawned sub-agent can itself spawn further sub-agents — useful when a delegated
sub-task is still too large to handle directly — but this is strictly depth-bounded,
never sibling/fan-out-bounded: each level can still spawn as many sub-agents as it
wants, but nesting depth is capped by max_spawn_depth. Below that hard cap, an
optional spawn_complexity_check (a Verifier) can gate whether decomposing further
is actually warranted, so agents don't nest "just because they can."
from deepcrew import Agent, Orchestrator, Verifier, tool
orch = Orchestrator(
agents=[master_agent],
global_tools=[search_web, read_file],
enable_spawn=True,
max_spawn_depth=3, # up to 3 levels of nested delegation
spawn_complexity_check=Verifier(), # optional: skip nesting for simple sub-tasks
)
When a sub-agent tries to spawn beyond max_spawn_depth, it simply has no
spawn_agent tool to call — there's nothing to invoke, so it completes the task
directly. A defense-in-depth check inside the tool itself also returns "Maximum
nesting depth reached; complete this task directly without further delegation." as a
plain string result for any caller that bypasses the normal attach logic — never an
exception.
Looping
Outer iteration loop for search-refine patterns.
from deepcrew import Agent, LoopConfig
agent = Agent(
name="researcher",
model="openai/gpt-4o-mini",
tools=[search_web],
loop_config=LoopConfig(
max_iterations=4,
convergence_fn=lambda r: len(r.text) > 500,
refine_prompt="Your answer is incomplete. Search more and expand it.",
),
)
result = await run_agent(agent, [{"role": "user", "content": "Explain CRISPR"}])
print(f"Converged in {result.loop_iterations} iterations")
Verifier-driven refinement
A Verifier grades each iteration's answer against the original query and returns
structured feedback — a score, specific issues, and a concrete suggestion — instead
of a boolean. When set, the loop uses this feedback both to decide convergence and to
build a targeted refinement prompt, instead of the static refine_prompt string.
from deepcrew import Agent, LoopConfig, Verifier, VerifierConfig
agent = Agent(
name="researcher",
model="openai/gpt-4o-mini",
tools=[search_web],
loop_config=LoopConfig(
max_iterations=4,
verifier=Verifier(VerifierConfig(threshold=0.85)),
),
)
result = await run_agent(agent, [{"role": "user", "content": "Explain CRISPR"}])
convergence_fn and verifier can be combined — the loop stops as soon as either one
is satisfied. Pass VerifierConfig(evaluate_fn=my_custom_grader) to fully replace the
built-in LLM-graded rubric with your own scoring function.
Adaptive iteration budget
With adaptive=True, the loop tracks the verifier score across iterations and stops
early once improvement plateaus, instead of always running max_iterations. This is
still bounded by max_iterations — adaptive can only shorten the loop, never lengthen
it. Requires verifier to be set (there's no score to track otherwise).
agent = Agent(
name="researcher",
model="openai/gpt-4o-mini",
tools=[search_web],
loop_config=LoopConfig(
max_iterations=8,
verifier=Verifier(VerifierConfig(threshold=0.9)),
adaptive=True,
min_improvement=0.02, # minimum score delta to still count as "improving"
plateau_patience=2, # stop after this many non-improving iterations in a row
),
)
result = await run_agent(agent, [{"role": "user", "content": "Explain CRISPR"}])
Branching (self-consistency)
With branches > 1, each iteration runs that many parallel candidate continuations
instead of one, and picks the best via verifier score (or merges them with
APEXSynthesizer when no verifier is configured). This multiplies LLM call volume by
branches per iteration — use it deliberately, typically with a low max_iterations.
agent = Agent(
name="researcher",
model="openai/gpt-4o-mini",
tools=[search_web],
loop_config=LoopConfig(
max_iterations=3,
verifier=Verifier(VerifierConfig(threshold=0.85)),
branches=3, # 3x the LLM calls per iteration, in exchange for picking the best
),
)
result = await run_agent(agent, [{"role": "user", "content": "Explain CRISPR"}])
See also: Self-evolving skills —
LoopConfig.auto_extract_skill distills a converged loop run into a reusable Skill
for other agents to retrieve later.
Procedural memory (evolving playbook)
ProceduralMemory is an opt-in, durable "the system learns from its own past runs"
store, inspired by ACE (Agentic Context Engineering). It's built on top of any
MemoryProvider and accumulates a structured playbook of "helpful"/"avoid" strategy
bullets across runs — read on every run (looped or single-shot) and curated
(incrementally merged, not rewritten) whenever a loop with a verifier converges.
from deepcrew import (
Agent,
LoopConfig,
Verifier,
VerifierConfig,
FileMemoryProvider,
ProceduralMemory,
)
playbook = ProceduralMemory(FileMemoryProvider("playbook.json"), max_entries=30)
agent = Agent(
name="researcher",
model="openai/gpt-4o-mini",
tools=[search_web],
procedural_memory=playbook, # read on every run, even single-shot
loop_config=LoopConfig(
max_iterations=4,
verifier=Verifier(VerifierConfig(threshold=0.85)),
procedural_memory=playbook, # curated after a converged loop
),
)
result = await run_agent(agent, [{"role": "user", "content": "Explain CRISPR"}])
# Run the same agent again later (even a new process, with FileMemoryProvider) and
# it will already know what worked and what to avoid for this task.
Curation requires a verifier — without one, procedural_memory on LoopConfig is a
no-op (there's no VerifierFeedback to grade the run against).
Skills
Higher-level capability bundles. Built-ins included:
from deepcrew import Agent, run_agent
from deepcrew import WebSearchSkill, SummarizeSkill, CodeExecutionSkill
agent = Agent(
name="assistant",
model="openai/gpt-4o",
skills=[
WebSearchSkill(),
SummarizeSkill(model="openai/gpt-4o-mini"),
CodeExecutionSkill(timeout=10.0),
],
)
result = await run_agent(
agent,
[{"role": "user", "content": "Search for Python async best practices and summarize them."}],
)
Custom skills with the @skill decorator:
from deepcrew import skill
@skill(name="translate", description="Translate text to another language")
async def translate(text: str, target_language: str) -> str:
# your implementation
return translated_text
Self-evolving skills (Voyager-inspired)
With LoopConfig.auto_extract_skill=True, a loop run that genuinely converges (via
convergence_fn or verifier) with a quality signal at or above
skill_confidence_threshold is automatically distilled into a reusable, replayable
Skill and registered in SkillRegistry — so a different agent, later, can retrieve
and reuse the proven approach instead of re-deriving it from scratch. This never
triggers on plain max_iterations exhaustion without real convergence, and is fully
opt-in (off by default, no surprise side effects).
from deepcrew import Agent, run_agent, LoopConfig, Verifier, VerifierConfig, SkillRegistry
researcher = Agent(
name="researcher",
model="openai/gpt-4o-mini",
tools=[search_web],
loop_config=LoopConfig(
max_iterations=4,
verifier=Verifier(VerifierConfig(threshold=0.85)),
auto_extract_skill=True,
skill_confidence_threshold=0.85,
),
)
result = await run_agent(researcher, [{"role": "user", "content": "Explain CRISPR"}])
# Later, a completely different agent can reuse the distilled skill by name.
distilled = [s for s in SkillRegistry.list_all() if s.name.startswith("researcher_")][0]
writer = Agent(name="writer", model="openai/gpt-4o-mini", skills=[distilled])
Memory Providers
Auto-injected context across turns and agent runs.
from deepcrew import Agent, run_agent, InMemoryProvider, FileMemoryProvider
# Short-term (in-process)
agent = Agent(
name="bot",
model="openai/gpt-4o-mini",
memory=InMemoryProvider(),
)
# Persistent (JSON file)
agent = Agent(
name="bot",
model="openai/gpt-4o-mini",
memory=FileMemoryProvider("~/.deepcrew/memory.json"),
)
Episodic Memory
A durable log of past runs — query, answer, outcome, score, tools, timestamp — recalled by
relevance before each new run. Set Agent.episodic_memory and the record/recall cycle is
automatic (one episode per iteration inside a refinement loop).
from deepcrew import Agent, EpisodicMemory, run_agent
from deepcrew.memory import FileMemoryProvider
episodic = EpisodicMemory(
FileMemoryProvider("episodes.json"),
namespace="support-bot",
recall_k=3,
reflect_model=None, # set a model to distil a one-line lesson per episode
)
agent = Agent(name="assistant", model="gemini/gemini-3.5-flash-lite", episodic_memory=episodic)
await run_agent(agent, [{"role": "user", "content": "How do I rotate an API key?"}])
r = await run_agent(agent, [{"role": "user", "content": "Is key rotation zero-downtime?"}])
print(r.episodes_recalled) # >= 1
print([e.outcome for e in await episodic.load()])
Recall ranks by keyword (Jaccard) overlap plus a recency tie-breaker — dependency-free, no
embeddings. It is independent of ProceduralMemory (distilled rules) and OpenTelemetry.
Retry & Fallback
from deepcrew import Agent, RetryPolicy, FallbackChain
agent = Agent(
name="resilient",
model="openai/gpt-4o",
retry_policy=RetryPolicy(max_retries=3, backoff_seconds=1.0, exponential=True),
fallback_chain=FallbackChain(
models=[
"anthropic/claude-haiku-4-5-20251001",
"gemini/gemini-2.0-flash",
]
),
)
Observability (OpenTelemetry)
pip install "deepcrew-ai[otel]"
from deepcrew import Agent, run_agent, ObservabilityConfig
obs = ObservabilityConfig(
otel_endpoint="http://localhost:4317",
service_name="my-ai-app",
)
result = await run_agent(agent, messages, observability=obs)
# Emits spans: agent.run, llm.call, tool.call
Logging
Separate from OpenTelemetry — plain human/JSON logs, off by default. One call turns them on;
get_logger is public so your own tools and components log in the same style.
from deepcrew import configure_logging, get_logger
configure_logging("dev") # colour + DEBUG; also "prod" (JSON), "verbose", "quiet"
# or: DEEPCREW_LOG_PROFILE=prod python app.py
log = get_logger("myapp.tools")
log.info("price lookup", sku=sku, region=region) # kwargs become structured fields
Colour uses rich when installed (pip install "deepcrew-ai[log]"), plain ANSI otherwise.
See the Logging guide.
CLI
# Run a declarative workflow
deepcrew run workflow.yaml --input "The future of AI"
# List agents in a config
deepcrew agents list --config workflow.yaml
# Version
deepcrew --version
# Logging (quiet by default — warnings and errors only)
deepcrew -v run workflow.yaml # verbose profile
deepcrew --log-profile dev run workflow.yaml # coloured DEBUG
deepcrew --log-level DEBUG --log-json run workflow.yaml
deepcrew -q run workflow.yaml # errors only
workflow.yaml example:
agents:
- name: researcher
model: openai/gpt-4o-mini
system_prompt: Research the topic.
tools: [web_search]
- name: writer
model: openai/gpt-4o
system_prompt: Write clearly.
workflow:
- step: research
agent: researcher
task: "{input}"
- step: report
agent: writer
task: "Write about:\n{research}"
depends_on: [research]
Composing v0.3.0 Features
The six self-improving-loop additions aren't just usable in isolation — they compose. A single agent can be configured with a verifier-driven, adaptive, branching, skill-distilling, procedural-memory-backed loop, orchestrated by a coordinator that allows bounded nested delegation:
from deepcrew import (
Agent,
Orchestrator,
LoopConfig,
Verifier,
VerifierConfig,
FileMemoryProvider,
ProceduralMemory,
)
verifier = Verifier(VerifierConfig(threshold=0.85))
playbook = ProceduralMemory(FileMemoryProvider("researcher_playbook.json"))
researcher = Agent(
name="researcher",
model="openai/gpt-4o-mini",
tools=[search_web],
procedural_memory=playbook, # read on every run
loop_config=LoopConfig(
max_iterations=6,
verifier=verifier, # structured critique drives refinement
procedural_memory=playbook, # curated after convergence
adaptive=True, # stop early once improvement plateaus
min_improvement=0.02,
plateau_patience=2,
branches=2, # 2 parallel candidates per iteration
auto_extract_skill=True, # distill a reusable Skill on success
skill_confidence_threshold=0.85,
),
)
orch = Orchestrator(
agents=[researcher],
router_model="openai/gpt-4o-mini",
global_tools=[search_web, read_file],
enable_spawn=True,
max_spawn_depth=2, # bounded recursive delegation
spawn_complexity_check=verifier, # reuse the same verifier as a complexity gate
)
result = await orch.run("Research and summarize the current state of fusion energy")
print(result.final_text)
Every feature here defaults off — this example opts into all six deliberately to show how they fit together, not as a recommended baseline configuration.
MCP Tools
from deepcrew.mcp import StdioMCP, HTTPMCP, SSEMCP, MCPManager
# Stdio (subprocess)
async with StdioMCP("npx", ["-y", "@modelcontextprotocol/server-filesystem", "."]) as mcp:
agent = Agent("file_agent", model="openai/gpt-4o", mcps=[mcp])
# HTTP (modern)
async with HTTPMCP(
"https://my-mcp.example.com/mcp", headers={"Authorization": "Bearer sk-..."}
) as mcp:
agent = Agent("agent", model="openai/gpt-4o", mcps=[mcp])
# Multiple servers
async with MCPManager(
[
StdioMCP("npx", ["-y", "@modelcontextprotocol/server-filesystem", "."]),
HTTPMCP("https://search-mcp.example.com/mcp"),
]
) as manager:
agent = Agent("agent", model="openai/gpt-4o", mcps=[manager])
Provider Examples
# OpenAI
Agent("a", model="openai/gpt-4o")
Agent("a", model="openai/gpt-4o-mini")
# Anthropic
Agent("a", model="anthropic/claude-opus-4-8")
Agent("a", model="anthropic/claude-haiku-4-5-20251001")
# Google
Agent("a", model="gemini/gemini-2.0-flash")
Agent("a", model="gemini/gemini-3.5-flash-lite") # default model of the live tests
Agent("a", model="gemini/gemini-2.5-pro")
# AWS Bedrock
Agent("a", model="bedrock/anthropic.claude-opus-4-8-20250514-v1:0")
# Azure OpenAI
Agent("a", model="azure/gpt-4o", extra_params={"api_base": "https://..."})
# Local via Ollama
Agent("a", model="ollama/llama3.2")
Agent("a", model="ollama/qwen2.5-coder")
Streaming with FastAPI
The fastapi extra (pip install deepcrew-ai[fastapi]) gives you a streaming endpoint in one call:
from fastapi import FastAPI
from deepcrew import Agent, Orchestrator, ApexConfig, StreamPolicy
from deepcrew.integrations.fastapi import create_stream_router
orch = Orchestrator(
agents=[Agent("assistant", model="openai/gpt-4o")],
apex_config=ApexConfig(cite_sources=True),
)
app = FastAPI()
app.include_router(create_stream_router(orch, policy=StreamPolicy.chat()))
# POST /chat streams Server-Sent Events; POST /chat/complete returns the final result as JSON.
Or wire it up manually against any .stream()-producing object:
from fastapi.responses import StreamingResponse
@app.post("/chat-manual")
async def chat(query: str):
async def event_stream():
async for event in orch.stream(query, policy=StreamPolicy.chat()):
yield event.to_sse()
return StreamingResponse(event_stream(), media_type="text/event-stream")
Stream Events
All events have event (EventType), agent_id (str), and data (dict).
| Event | Data keys | Emitted by |
|---|---|---|
agent_start |
model |
Agent loop begins |
text_delta |
chunk |
Each streamed text token |
tool_call |
tool, args |
Before tool execution |
tool_result |
tool, result |
After tool execution |
tool_denied |
tool |
An AgentHooks.approve_tool hook denied the call |
thinking_delta |
chunk |
Each streamed reasoning-content token (if the model exposes one) |
agent_done |
input_tokens, output_tokens |
Agent finished |
apex_start |
agents |
APEX synthesis begins |
apex_done |
confidence |
APEX synthesis complete |
loop_iteration |
iteration, converged |
Each outer loop iteration |
verifier_scored |
iteration, score, issues |
Verifier grades an iteration |
playbook_updated |
task_tag, entry_count |
Procedural memory curated |
branch_selected |
branch_count, winning_index, winning_score |
Best/merged branch chosen |
skill_extracted |
skill_name, score |
A converged run distilled into a Skill |
spawn_agent |
task, requested_tools, depth |
Sub-agent spawned |
memory_retrieve |
count |
Memories injected into context |
memory_store |
key |
Tool result stored to memory |
episode_recalled |
count |
Past episodes injected from episodic memory |
episode_recorded |
outcome, score |
A run recorded to episodic memory |
retry_attempt |
attempt, model, delay |
Before a retry |
fallback_triggered |
from_model, to_model |
Model switch |
step_start |
node |
Workflow node begins |
step_done |
node |
Workflow node finished |
error |
message |
Any exception |
done |
final_text (Orchestrator/WorkflowBuilder only) |
The whole run/pipeline finished |
done |
final_text |
Entire run complete |
Installation
# Core
pip install deepcrew-ai
# With OpenTelemetry
pip install "deepcrew-ai[otel]"
# With the FastAPI streaming integration
pip install "deepcrew-ai[fastapi]"
# With the Redis memory provider
pip install "deepcrew-ai[redis]"
# With coloured logging via rich (plain ANSI fallback without it)
pip install "deepcrew-ai[log]"
# With dev dependencies (pytest, ruff, mypy, rich)
pip install "deepcrew-ai[dev]"
API keys are read by LiteLLM from the standard environment variables (OPENAI_API_KEY,
ANTHROPIC_API_KEY, GEMINI_API_KEY, ...).
Requires Python 3.11+.
Development & Testing
pip install -e ".[dev,otel,fastapi,log]"
ruff check . && ruff format --check . && mypy src/
pytest # fully mocked, offline, no API keys needed
Live tests (opt-in) call a real model and verify features end to end:
export GEMINI_API_KEY=...
pytest --live tests/live # runs only features whose source changed since their last pass
pytest --live --relive tests/live # ignore the ledger; run everything
tests/live/LEDGER.json / LEDGER.md record which features have passed a live
test; a feature whose watched source files are unchanged is skipped, so a verified feature is not
re-billed until its code changes. Default model gemini/gemini-3.5-flash-lite (override with
DEEPCREW_LIVE_MODEL). See tests/live/README.md and
CONTRIBUTING.md.
Documentation
Full documentation at deepcrew-ai.aayushjoshi.dev
- Getting Started
- Features — one page per feature, including Episodic Memory, Procedural Memory and Logging
- Examples Library
- Migration Guide (CrewAI / Google ADK)
- llms.txt — machine-readable docs index
- CHANGELOG · CONTRIBUTING · SECURITY · Release runbook
License
MIT
Metadata
Release files for deepcrew-ai 0.6.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| deepcrew_ai-0.6.0.tar.gz | 425.0 kB | Without provenance | Details for deepcrew_ai-0.6.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| deepcrew_ai-0.6.0-py3-none-any.whl | Python 3 | none | any | Details for deepcrew_ai-0.6.0-py3-none-any.whl |
Total release size: 518.8 kB
Release files / deepcrew_ai-0.6.0.tar.gz
| Download URL | deepcrew_ai-0.6.0.tar.gz |
|---|---|
| Size | 425.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
01c3f0f0f1896b21b4ab75004b9f362bdce6ef59d5a18fa43879d3914e12c1d6
|
|
BLAKE2b-256 checksum How to use checksums |
157db28b3701f9ed2398cd0d6fcd97771ef8beced4aa895089dde8c044fccdfd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.15
|
Release files / deepcrew_ai-0.6.0-py3-none-any.whl
| Download URL | deepcrew_ai-0.6.0-py3-none-any.whl |
|---|---|
| Size | 93.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fc356b8b4ea05e93519751906cb0787ff448a8f1034dbbe78a61cca01eefa798
|
|
BLAKE2b-256 checksum How to use checksums |
a61570fabc428ec138129782c2b650be2091f1999422297b6d793b3ff7bafcd8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.15
|
Security for deepcrew-ai 0.6.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.