Deepagents

deepagents

Deep Agents is a batteries-included agent harness built on top of LangGraph. Use it when the problem is "give me a capable agent with planning, files, subagents, and memory" rather than "let me hand-author every graph edge myself."

When to use this skill

• Building a tool-calling agent that needs file access and planning quickly
• Delegating bounded work to specialized subagents with context isolation
• Choosing between StateBackend, FilesystemBackend, StoreBackend, CompositeBackend, or LocalShellBackend
• Adding skills and long-term memory without bloating the core prompt
• Requiring human approval before sensitive tool calls with interrupt_on
• Using deepagents as a specialist inside a larger LangGraph supervisor

Installation

pip install -qU deepagents

Inside an existing uv-managed project:

uv add deepagents

Optional provider and MCP packages:

pip install -qU langchain-anthropic langchain-openai langchain-google-genai
pip install -qU langchain-mcp-adapters

Core API

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="openai:gpt-5.4",
    tools=[],
    system_prompt="You are a careful engineering agent.",
    middleware=[],
    subagents=[],
    skills=[],
    memory=[],
    response_format=None,
    checkpointer=None,
    backend=None,
    interrupt_on=None,
    debug=False,
    name="deep-agent",
)

Deep Agents work with LangChain chat models that support tool calling. The simplest selector is provider:model.

Instructions

Step 1: Start with the default harness

For many workflows, the zero-config harness is enough:

from deepagents import create_deep_agent

agent = create_deep_agent()
result = agent.invoke(
    {"messages": [{"role": "user", "content": "List the Python files in this repo"}]}
)

This gives you:

• planning via the built-in todo capability
• file tools such as ls, read_file, write_file, edit_file, glob, and grep
• LangGraph runtime features such as streaming and resumability when a checkpointer is attached

Step 2: Pick the right backend

Match the backend to the trust boundary:

from deepagents.backends import CompositeBackend, FilesystemBackend, LocalShellBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore

agent = create_deep_agent(
    backend=lambda rt: CompositeBackend(
        default=StateBackend(rt),
        routes={"/memories/": StoreBackend(rt)},
    ),
    store=InMemoryStore(),
)

Guidance:

• StateBackend: default ephemeral workspace in LangGraph state, scoped to a thread
• StoreBackend: durable cross-thread memory and instructions
• FilesystemBackend: real files under a root directory; prefer virtual_mode=True
• LocalShellBackend: host shell access, development-only, high risk
• CompositeBackend: mix scratch space and durable memory under different path prefixes

Step 3: Add subagents only for real context isolation

from deepagents import MemoryMiddleware, SubAgent, SubAgentMiddleware, create_deep_agent

researcher = SubAgent(
    name="researcher",
    description="Finds documentation and summarizes it",
    system_prompt="Search broadly, return concise evidence.",
    tools=[web_search_tool],
)

agent = create_deep_agent(
    middleware=[
        MemoryMiddleware(memory_files=["AGENTS.md"]),
        SubAgentMiddleware(subagents=[researcher]),
    ]
)

Use subagents when:

• the specialist needs a narrower tool set
• you want the supervisor context to stay clean
• a subtask can be delegated without the main agent rereading all prior context

Step 4: Add HITL for risky tools

Human approval requires both interrupt_on and a checkpointer:

from deepagents import create_deep_agent
from langgraph.checkpoint.memory import MemorySaver

agent = create_deep_agent(
    checkpointer=MemorySaver(),
    interrupt_on={
        "write_file": {"allowed_decisions": ["approve", "reject"]},
        "execute": {"allowed_decisions": ["approve", "edit", "reject"]},
    },
)

Resume on the same thread:

from langgraph.types import Command

config = {"configurable": {"thread_id": "job-7"}}
first = agent.invoke({"messages": [...]}, config=config, version="v2")
second = agent.invoke(Command(resume=[{"decision": "approve"}]), config=config, version="v2")

Step 5: Use skills and memory for different jobs

agent = create_deep_agent(
    skills=["./skills/langgraph-workflow"],
    memory=["AGENTS.md", "TEAM_GUIDELINES.md"],
)

Use:

• skills for reusable workflows and domain-specific procedures
• memory for stable project knowledge, preferences, and house rules

Do not collapse both into a giant system prompt. Let the harness load them progressively.

Step 6: Use Deep Agents inside LangGraph when orchestration gets custom

If you need explicit retries, branching, or supervisor-owned state, use LangGraph outside and deepagents inside specialist nodes.

Examples

Example 1: Minimal file-aware agent

from deepagents import create_deep_agent

agent = create_deep_agent(model="openai:gpt-5.4")
result = agent.invoke(
    {"messages": [{"role": "user", "content": "Summarize the README and note any missing setup steps"}]}
)

Example 2: Composite backend with durable memory route

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore

agent = create_deep_agent(
    backend=lambda rt: CompositeBackend(
        default=StateBackend(rt),
        routes={"/memories/": StoreBackend(rt)},
    ),
    store=InMemoryStore(),
)

Example 3: Research specialist subagent

from deepagents import SubAgent, SubAgentMiddleware, create_deep_agent

researcher = SubAgent(
    name="researcher",
    description="Searches docs and summarizes findings",
    system_prompt="Return concise, source-backed notes.",
    tools=[search_docs],
)

agent = create_deep_agent(
    middleware=[SubAgentMiddleware(subagents=[researcher])]
)

Example 4: HITL for shell execution

from deepagents import create_deep_agent
from langgraph.checkpoint.memory import MemorySaver

agent = create_deep_agent(
    checkpointer=MemorySaver(),
    interrupt_on={"execute": True},
)

Best practices

1. Start with the default harness before customizing middleware. 2. Use StateBackend for scratch space and CompositeBackend when long-term memory is needed. 3. Treat LocalShellBackend as development-only and pair it with human approval. 4. Prefer FilesystemBackend(root_dir=..., virtual_mode=True) over unconstrained local file access. 5. Use skills for reusable capabilities and memory for persistent project context. 6. Add subagents for context isolation, not because multi-agent sounds impressive. 7. If routing becomes graph-shaped, move orchestration to LangGraph and keep deepagents as a specialist.

Framework selection guide

References

• Deep Agents Overview
• Deep Agents Backends
• Deep Agents Human-in-the-loop
• Deep Agents Skills
• See references/deepagents-api.md for backend, memory, and HITL notes

Deep Agents Notes

What the harness gives you

Deep Agents is a LangGraph-backed harness for:

• planning and task decomposition
• file tools such as ls, read_file, write_file, edit_file, glob, and grep
• subagent delegation through a built-in task capability
• persistence and HITL when compiled with a checkpointer

The harness is best used when you want a capable tool-using agent quickly. Use raw LangGraph when the workflow itself is the product.

Core entry point

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="openai:gpt-5.4",
    tools=[],
    middleware=[],
    subagents=[],
    skills=[],
    memory=[],
    response_format=None,
    checkpointer=None,
    backend=None,
    interrupt_on=None,
    debug=False,
    name="deep-agent",
)

Backend selection

StateBackend

• Default backend when you call create_deep_agent() with no override
• Ephemeral scratch filesystem stored in LangGraph state
• Persists within a thread when checkpoints are enabled
• Shared between supervisor and subagents

StoreBackend

• Durable storage backed by LangGraph store infrastructure
• Good for cross-thread memory or reusable instructions
• Often paired with CompositeBackend

FilesystemBackend

• Real filesystem access under a configured root
• Prefer virtual_mode=True
• Keep secrets outside the allowed root

LocalShellBackend

• Real filesystem plus host shell execution
• High risk and development-only
• Pair with interrupt_on approval for any serious usage

CompositeBackend

Use when you want both scratch space and durable memory:

from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore

agent = create_deep_agent(
    backend=lambda rt: CompositeBackend(
        default=StateBackend(rt),
        routes={"/memories/": StoreBackend(rt)},
    ),
    store=InMemoryStore(),
)

HITL pattern

from deepagents import create_deep_agent
from langgraph.checkpoint.memory import MemorySaver

agent = create_deep_agent(
    checkpointer=MemorySaver(),
    interrupt_on={
        "write_file": {"allowed_decisions": ["approve", "reject"]},
        "execute": {"allowed_decisions": ["approve", "edit", "reject"]},
    },
)

Important points:

• HITL needs a checkpointer
• resume on the same thread_id
• use narrower allowed_decisions for lower-risk tools if editing should not be allowed

Skills vs memory

Use skills= when you want progressive-disclosure capabilities that activate on matching user intent.

Use memory= when you want always-available project knowledge, norms, or instructions.

They solve different problems and should not be collapsed into one monolithic prompt.

Hybrid architecture

Use raw LangGraph to own:

• workflow state
• retry loops
• branching and approval routing
• checkpoint lifecycle

Use Deep Agents to own:

• tool-heavy specialist execution
• file-aware research or coding subtasks
• narrowly scoped delegated work

Links

• https://docs.langchain.com/oss/python/deepagents/overview
• https://docs.langchain.com/oss/python/deepagents/backends
• https://docs.langchain.com/oss/python/deepagents/human-in-the-loop
• https://docs.langchain.com/oss/python/deepagents/skills