Building with deepagents (LangChain Python)

deepagents is a Python agent harness built on LangChain + LangGraph. Calling create_deep_agent(...) returns a compiled LangGraph graph that already knows how to plan, write to a virtual filesystem, spawn sub-agents, and manage its own context window. Your job, when writing code that uses it, is to wire the right capabilities together — not to reinvent them.

This skill is the navigation hub. It contains the mental model, the 80% patterns, the gotchas, and an index into deeper reference files. Load reference files only when needed — they exist to keep the top-level lean while still giving you authoritative depth on demand.

1. When deepagents is (and isn't) the right fit

Reach for deepagents when all of these are true:

• The task is multi-step and long-horizon — the model would otherwise blow through its context window.
• The agent benefits from planning (writing down a todo list and updating it as it goes).
• Intermediate results, drafts, search hits, or large tool outputs need to be stashed somewhere other than the running message history.
• You'd want to delegate sub-tasks into isolated context windows (e.g. "go research X, return a summary").

For simpler agents — single tool, one-shot answer, no planning needed — use langchain.agents.create_agent instead. For maximum control over graph topology, use raw LangGraph. deepagents sits on top of both and is the right pick when you'd otherwise be re-implementing planning + filesystem + sub-agents by hand.

2. Mental model — the four pillars

Every deepagents application is built on these four pieces. Understand all four before writing code; the API only makes sense in this frame.

1. Detailed system prompt — a Claude-Code-inspired base prompt teaches the model how to use the planning, filesystem, and sub-agent tools. Anything you pass as system_prompt= is prepended (not replaced).
2. Planning tool (`write_todos`) — a near-no-op tool whose purpose is to force the model to externalize a plan. The act of writing the plan, not the tool's return value, is what improves long-horizon execution.
3. Virtual filesystem (`ls`/`read_file`/`write_file`/`edit_file`/`glob`/`grep`) — context offloading. Big tool outputs and intermediate artefacts go to files instead of the message stream. Backend is pluggable (state, real disk, store, sandbox).
4. Sub-agents (the `task` tool) — context isolation. The supervisor delegates a focused subtask, only the last message of the subagent comes back, the rest of the subagent's context is discarded.

These map to four context-engineering strategies: offload (filesystem), isolate (subagents), summarize (auto-summarization middleware), quarantine (sandboxes for shell). Keep that vocabulary in your head — it's how the docs talk and how to reason about adding capabilities.

3. Install

pip install deepagents

Plus the model provider package(s) you'll use:

pip install langchain-anthropic    # default model is anthropic:claude-sonnet-4-6
# or langchain-openai, langchain-google-genai, langchain-ollama, "langchain[aws]", etc.

API keys come from environment variables (ANTHROPIC_API_KEY, OPENAI_API_KEY, TAVILY_API_KEY, …). Python 3.10+.

For LangSmith tracing: LANGSMITH_TRACING=true and LANGSMITH_API_KEY.

4. Minimum viable agent

from deepagents import create_deep_agent

def get_weather(city: str) -> str:
    """Get the weather in a city."""
    return f"It's always sunny in {city}!"

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    tools=[get_weather],
    system_prompt="You are a helpful weather assistant.",
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "what is the weather in sf"}]
})
print(result["messages"][-1].content)

The agent already has write_todos, ls, read_file, write_file, edit_file, glob, grep, and task even though we passed only one custom tool. They are merged in by middleware automatically.

A complete, runnable version of this and six more end-to-end examples are in examples/ — see §10.

5. Core API at a glance

from deepagents import create_deep_agent  # or async_create_deep_agent

create_deep_agent(
    model: str | BaseChatModel | None = None,        # "anthropic:claude-sonnet-4-6" by default
    tools: Sequence[BaseTool | Callable | dict] | None = None,
    *,
    system_prompt: str | SystemMessage | None = None,
    middleware: Sequence[AgentMiddleware] = (),
    subagents: list[SubAgent | CompiledSubAgent | AsyncSubAgent] | None = None,
    skills: list[str] | None = None,
    memory: list[str] | None = None,
    response_format: ResponseFormat | None = None,
    context_schema: type[Any] | None = None,
    checkpointer: Checkpointer | None = None,
    store: BaseStore | None = None,
    backend: BackendProtocol | BackendFactory | None = None,
    interrupt_on: dict[str, bool | InterruptOnConfig] | None = None,
    debug: bool = False,
    name: str | None = None,
    cache: BaseCache | None = None,
) -> CompiledStateGraph

The return value is a compiled LangGraph graph, which means you also get agent.invoke, agent.ainvoke, agent.stream, agent.astream, checkpointing, time travel, LangGraph Studio, and LangSmith tracing for free — without any extra adaptation code.

Always set `model=` and `system_prompt=` explicitly. The defaults exist for demos but real applications should pin both for reproducibility and to make intent obvious to readers.

For the full per-parameter reference (types, semantics, edge cases), load references/api-reference.md.

6. Critical version notes — target the 0.4+ API

deepagents had a significant API rename between 0.0.x and the current 0.4.x line. Old code samples on the internet may use parameters that no longer exist. When generating code, always:

• Use system_prompt= (not prompt= / not instructions=).
• For declarative SubAgent dicts, use the key system_prompt and always include `tools` and `model` — these are now required for declarative subagents (the factory raises if they're missing).
• The default model is anthropic:claude-sonnet-4-6. Older docs say claude-sonnet-4-5-20250929 or claude-sonnet-4-20250514 — these are stale.
• glob and grep are filesystem tools (added in 0.4); the execute shell tool is only available when the backend implements SandboxBackendProtocol. Without a sandbox backend, calling it returns an error.

If the user's existing code uses old names, see references/migration-from-0.0.x.md before changing anything.

7. Capability map — when to load each reference

This is the index you should consult when a task involves more than the basics. Don't read all of these up front. Load them as the task demands.

8. The 80/20 architectural patterns

These are the shapes most real deepagents apps take. Pick the closest one and adapt; full runnable code is in examples/.

8.1 Research agent (the canonical pattern)

A supervisor with a research-agent sub-agent. The supervisor plans, the sub-agent does the heavy retrieval, only a summary returns. See examples/02_research_agent.py.

from deepagents import create_deep_agent
from tavily import TavilyClient

tavily = TavilyClient()

def internet_search(query: str, max_results: int = 5, topic: str = "general") -> dict:
    """Search the web."""
    return tavily.search(query=query, max_results=max_results, topic=topic)

research_subagent = {
    "name": "research-agent",
    "description": "Use for in-depth research on a single topic. Provide a clear, focused question.",
    "system_prompt": "You are an expert researcher. Search thoroughly, then summarize.",
    "tools": [internet_search],            # ← required in 0.4.x
    "model": "anthropic:claude-sonnet-4-6", # ← required in 0.4.x
}

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    tools=[internet_search],
    system_prompt="You are a senior research lead. Plan, delegate research, then write a polished report.",
    subagents=[research_subagent],
)

Why this works: the supervisor's context stays small because each sub-agent's search noise is discarded after summary. Use write_file to stash drafts of the report between sub-agent calls.

8.2 Coding agent (sandbox + HITL)

Use a sandbox backend so the execute tool is real, and gate destructive filesystem writes with interrupt_on. See examples/03_coding_agent_with_sandbox.py.

Pick a sandbox by environment:

• Modal / Runloop / Daytona / LangSmith for managed remote VMs (production).
• LocalShellBackend only for fully trusted local development — it's an unrestricted local shell.

8.3 MCP-backed agent

Use MultiServerMCPClient from langchain-mcp-adapters to load tools from any MCP server (filesystem, GitHub, Slack, Postgres, …) and pass them to async_create_deep_agent. MCP tools are async, so use the async factory. See examples/05_mcp_integration.py and references/mcp-integration.md.

8.4 Human-in-the-loop agent

Pair interrupt_on={"tool_name": True} with a checkpointer (mandatory). Resume with Command(resume=...). See examples/04_hitl_with_checkpointer.py and references/human-in-the-loop.md.

8.5 Long-running / async sub-agent (v0.5+)

For sub-agents that run for minutes or hours (deep research, long compilation), wrap a remote LangGraph deployment in an AsyncSubAgent. The supervisor gets start_async_task / check_async_task / cancel_async_task tools and uses fire-and-forget semantics. See examples/07_async_subagents.py and the AsyncSubAgent section in references/subagents.md.

8.6 Structured output

Pass a Pydantic model (or any create_agent-compatible schema) to response_format=. Read the typed result from result["structured_response"]. See examples/06_structured_output.py.

9. Common pitfalls (read this list before debugging)

These are the issues you'll keep hitting. Skim them every time you start a new deepagents project.

1. `SubAgent` dict missing `tools` or `model` — in 0.4.x both are required for declarative sub-agents. The factory raises a validation error. (Older 0.0.x examples on the web omit these.)
2. Using `prompt=` or `instructions=` — renamed to system_prompt= in 0.4.x.
3. `execute` returns "no sandbox" error — the default StateBackend doesn't ship execute. Plug in ModalSandbox / LocalShellBackend / etc.
4. HITL interrupts don't fire — you forgot the checkpointer. interrupt_on without a checkpointer is silently a no-op.
5. Files vanish between invocations — that's StateBackend working as designed (per-thread, ephemeral). Use StoreBackend (with store=) for cross-thread persistence, or FilesystemBackend for real disk.
6. MCP tools timeout / can't `await` — switch from create_deep_agent to async_create_deep_agent and use agent.ainvoke / agent.astream.
7. System prompt seems ignored — your custom prompt is prepended to the harness prompt, not replacing it. The base behaviors (planning, filesystem, sub-agent dispatch) stay in effect. To dramatically alter behavior, write detailed instructions, don't try to "override" the harness.
8. Sub-agent events not streaming — pass subgraphs=True and version="v2" to agent.stream(...). Check chunk["ns"] to identify which subgraph.
9. Mutating `self` in custom middleware — race conditions across parallel sub-agents/tools. Always update graph state instead.
10. Path errors — virtual filesystem paths must start with /. read_file("notes.md") fails; read_file("/notes.md") works.
11. `ChatAnthropic` rate limits in long runs — bump max_retries=10, set a timeout, and add RateLimitMiddleware for production. See references/production.md.
12. General-purpose subagent uses the wrong tools — by default it inherits the main agent's tools. To override, include a sub-agent named exactly "general-purpose" in the subagents list.

10. Examples — runnable starters

The examples/ directory contains seven progressively-more-complex working scripts. Treat these as the fastest path to a working application; copy one and adapt.

11. House style for code generation

When writing deepagents code, follow these defaults so the output is consistent and easy to review:

• Always pass model= and system_prompt= explicitly. Readers should see what model and what role the agent has without grepping for defaults.
• Group the agent setup (tools, subagents, the create_deep_agent call) into a single build_agent() factory function. Tests and notebooks call this; nothing else should construct the agent ad-hoc.
• Wrap network-IO tools in @tool from langchain.tools — gives proper schemas and clear docstrings the model uses for routing.
• Put the user-visible "role" of each sub-agent in its description field, in the imperative ("Use for…", "Use when…"). The supervisor reads only this to choose between sub-agents.
• For HITL, always include the checkpointer in the same expression as interrupt_on. Reviewers should never have to verify it was set somewhere else.
• For production, set name= so traces are readable in LangSmith.

That's the skill. Start with §4, pick a pattern from §8, copy the matching examples/ file, and load reference files from §7 only when the task pushes past the basics.