AI Application Development Mastery Part 9: Deep Agents & Autonomous Systems

2. Models & Configuration

Deep Agents support any model accessible through LangChain's init_chat_model interface. The SDK uses a convenient provider:model string format that is resolved at runtime to the appropriate chat model class.

2.1 Supported Providers

2.2 Model Configuration

For fine-grained control over model parameters, use init_chat_model directly and pass the resulting instance to create_deep_agent:

# pip install deepagents langchain-anthropic
from langchain.chat_models import init_chat_model
from deepagents import create_deep_agent

# Configure model with specific parameters
model = init_chat_model(
    "anthropic:claude-sonnet-4-6",
    temperature=0.2,
    max_tokens=8192,
)

agent = create_deep_agent(
    model=model,
    system_prompt="You are a precise code reviewer. Flag bugs and suggest fixes.",
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "Review this Python function for bugs."}]
})
print(result["messages"][-1].content)

2.3 Runtime Model Selection

The middleware parameter lets you intercept and modify every model call at runtime. A common pattern is routing simple tasks to a cheaper model and complex tasks to a more capable one:

# pip install deepagents langchain-anthropic langchain-openai
from langchain.agents.middleware.types import AgentMiddleware
from langchain.chat_models import init_chat_model
from deepagents import create_deep_agent

class RouteByComplexity(AgentMiddleware):
    """Middleware that routes simple messages to a cheaper model."""

    def wrap_model_call(self, request, handler):
        last_msg = request.messages[-1].content if request.messages else ""

        if len(last_msg) < 200:
            # Short messages go to the cheapest viable model
            request = request.override(model=init_chat_model("openai:gpt-4.1-mini"))
        else:
            # Complex messages stay on the primary model
            request = request.override(model=init_chat_model("anthropic:claude-sonnet-4-6"))

        return handler(request)

agent = create_deep_agent(
    model="anthropic:claude-haiku-4-5",  # Default model (cheap)
    middleware=[RouteByComplexity()],
    system_prompt="You are a research assistant.",
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "What is the capital of France?"}]
})
print(result["messages"][-1].content)

3. Context Engineering

The most critical challenge for long-running agents is context management. An agent executing a 50-step research task may generate hundreds of tool calls and thousands of tokens of intermediate results. Without active management, the conversation history exceeds the model's context window and the agent fails. Deep Agents solve this with a layered context engineering system.

3.0 The Agent Harness

The agent harness is what distinguishes Deep Agents from a bare tool-calling loop. It wraps the core LLM loop with a layered set of built-in middleware — adding planning (write_todos), virtual filesystem tools (ls, read_file, write_file, edit_file, glob, grep), subagent delegation (task), and automatic context management — all assembled into a complete system prompt before every invocation.

When you call create_deep_agent(), the harness assembles the system prompt from multiple sources in a fixed order. Your system_prompt is always prepended first, so your instructions override built-in guidance at every layer:

3.1 Input Context

Input context is the foundation layer — content loaded into every agent turn. It includes the system prompt, memory files, skill frontmatter, and built-in tool descriptions. The system_prompt you provide is prepended to the harness's built-in prompt, so your instructions take priority:

# pip install deepagents langchain-anthropic
from deepagents import create_deep_agent

# System prompt is prepended to the built-in harness prompt
agent = create_deep_agent(
    model="anthropic:claude-haiku-4-5",  # Cheapest Anthropic model
    system_prompt="""You are a senior data engineer specializing in ETL pipelines.

Rules:
- Always validate data schemas before transformation
- Use incremental loading over full refreshes when possible
- Log all data quality issues to the /quality-reports/ directory""",
    memory=["AGENTS.md"],  # Always loaded into context alongside system prompt
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "Design an ETL pipeline for daily sales data."}]
})
print(result["messages"][-1].content)

3.2 Runtime Context

Runtime context is per-invocation typed configuration that you pass when calling the agent. Unlike the static system_prompt, runtime context changes per-call — carrying user identity, API credentials, roles, feature flags, or any other request-scoped data your tools need.

Runtime context is not automatically visible to the LLM. It is never injected into the conversation history. Tools read it explicitly via ToolRuntime injection, creating a deliberate security boundary: sensitive values like API keys or session tokens never appear in the model's prompt or tool call history.

Define the context shape with a Python dataclass or TypedDict, declare it as context_schema, and pass values via context= at invoke time:

# pip install deepagents langchain-anthropic
from dataclasses import dataclass
from deepagents import create_deep_agent
from langchain.tools import tool, ToolRuntime

# 1. Define runtime context shape — changes per user/session
@dataclass
class UserContext:
    user_id: str
    user_role: str     # "admin" | "viewer"
    api_key: str       # Never visible to the LLM

# 2. Tools receive context via ToolRuntime[Context] injection
@tool
def fetch_user_orders(query: str, runtime: ToolRuntime[UserContext]) -> str:
    """Fetch orders for the currently authenticated user.

    Args:
        query: Search filter for orders
    """
    user_id = runtime.context.user_id
    return f"Orders for {user_id} matching '{query}': [order-001, order-002]"

@tool
def update_order_status(order_id: str, status: str, runtime: ToolRuntime[UserContext]) -> str:
    """Update an order's status. Requires admin role.

    Args:
        order_id: The order to update
        status: New status: 'pending', 'shipped', or 'delivered'
    """
    role = runtime.context.user_role
    if role != "admin":
        return f"Permission denied: admin role required (your role: {role})"
    return f"Order {order_id} updated to '{status}'"

# 3. Declare context_schema when creating the agent
agent = create_deep_agent(
    model="anthropic:claude-haiku-4-5",
    tools=[fetch_user_orders, update_order_status],
    context_schema=UserContext,
    system_prompt="You are an order management assistant.",
)

# 4. Pass context per invocation — different per user/session
result = agent.invoke(
    {"messages": [{"role": "user", "content": "Show my recent orders and ship order-001."}]},
    context=UserContext(
        user_id="user-789",
        user_role="admin",
        api_key="sk-real-key-never-in-llm-history",
    ),
)
print(result["messages"][-1].content)

3.3 Context Compression

When tool inputs or outputs exceed 20,000 tokens, the harness automatically offloads them to the virtual filesystem and replaces the content with a reference pointer. This keeps the conversation history lean while preserving all data:

# pip install deepagents langchain-anthropic
from deepagents import create_deep_agent

# Context compression is automatic — no configuration needed
# When a tool returns a 30,000-token result:
#   1. The result is saved to the filesystem at a generated path
#   2. The message history replaces the result with:
#      "Result saved to /tool-outputs/research-2026-04-01-001.md (30,247 tokens)"
#   3. The agent can read_file to retrieve specific sections as needed

agent = create_deep_agent(
    model="anthropic:claude-haiku-4-5",  # Cheap model works for demos
    system_prompt="You are a research agent. Analyze large datasets thoroughly.",
)

# This invocation may trigger context offloading if the research produces
# a large volume of intermediate results
result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": "Research all OWASP Top 10 vulnerabilities with code examples for each."
    }]
})
print(result["messages"][-1].content)

3.4 Context Summarization

When the conversation history reaches 85% of the model's context window, the harness triggers automatic summarization. The agent generates a structured summary of the conversation so far, preserving:

• The complete to-do list with current progress
• Key decisions and findings
• File paths that were created or modified
• Pending tasks and their dependencies

# pip install deepagents langchain-openai
from deepagents import create_deep_agent

# Summarization is automatic — triggered at 85% of context window
# Example: For a 200k-token context window, summarization fires at ~170k tokens

# You can influence summarization by structuring your system prompt:
agent = create_deep_agent(
    model="openai:gpt-4.1-mini",  # Cost-effective for planning tasks
    system_prompt="""You are a project manager agent.

When summarizing progress, always preserve:
1. Current sprint goals and status
2. Blockers and dependencies
3. All file paths you've created
4. Key metrics and measurements""",
)

# Long-running task that may trigger multiple summarizations
result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": "Analyze the performance of our microservices architecture and write a report."
    }]
})
print(result["messages"][-1].content)

stateDiagram-v2
    [*] --> Normal: Agent starts
    Normal --> Offloading: Tool result > 20k tokens
    Offloading --> Normal: Content saved to filesystem
    Normal --> Summarization: Context at 85% capacity
    Summarization --> Compressed: Summary replaces history
    Compressed --> Normal: Agent continues with summary
    Compressed --> Offloading: New large tool result
    Normal --> [*]: Task complete
                            

3.5 Context Isolation

Subagents solve the context bloat problem. When an agent performs heavy multi-step work — web searches, large file reads, database queries — that work fills the main agent's context window rapidly. Context isolation delegates heavy subtasks to a subagent with its own fresh context. The main agent receives only the final summary result, keeping its own context clean throughout:

flowchart LR
    A["Main Agent\n(clean context)"] -->|"task tool"| B["Subagent\n(fresh context)"]
    B --> C["Tool Call 1\n50k tokens"]
    B --> D["Tool Call 2\n30k tokens"]
    B --> E["Tool Call N\n25k tokens"]
    C & D & E --> F["Final Summary\n~300 words"]
    F -->|"single result"| A
                            

# pip install deepagents langchain-anthropic
from deepagents import create_deep_agent

# Define a specialized research subagent that isolates heavy work
research_subagent = {
    "name": "researcher",
    "description": (
        "Conducts deep research on a single focused topic. Use this when a task "
        "requires extensive searching, reading, or multi-step analysis."
    ),
    "system_prompt": """You are a research analyst.
Research the topic thoroughly using all available tools.

CRITICAL OUTPUT RULES:
- Return ONLY the essential summary (300-500 words maximum)
- Do NOT include raw search results or verbose tool outputs
- Format: Brief Summary | Key Findings (3-5 bullets) | Confidence Level""",
}

agent = create_deep_agent(
    model="anthropic:claude-haiku-4-5",
    subagents=[research_subagent],
    system_prompt=(
        "You are a project lead. For any research-heavy task, "
        "delegate to the researcher subagent to keep your context clean."
    ),
)

# The researcher subagent may use thousands of tokens internally.
# The main agent only sees the final concise summary.
result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": "Compare event sourcing vs. traditional CRUD for a financial transactions system."
    }]
})
print(result["messages"][-1].content)

4. Backends & Sandboxes

The agent's virtual filesystem is backed by a pluggable backend that determines where files are stored and how code is executed. The SDK provides four backend types that can be used individually or composed together.

4.1 Virtual Filesystem

Every Deep Agent has access to a set of filesystem tools, regardless of which backend is configured:

4.2 Backend Types

Each backend implements the same filesystem protocol but stores data differently:

# pip install deepagents langchain-anthropic
from deepagents import create_deep_agent
from deepagents.backends import StateBackend, CompositeBackend, StoreBackend

# 1. StateBackend (default) — in-memory, thread-scoped
#    Files exist only for the duration of the conversation
agent_memory = create_deep_agent(
    model="anthropic:claude-haiku-4-5",  # Cheapest Anthropic model
    # backend=StateBackend()  # This is the default, no need to specify
)

# 2. StoreBackend — persists files across threads via LangGraph Store
from langgraph.store.memory import InMemoryStore

store = InMemoryStore()  # Use PostgresStore for production
agent_persistent = create_deep_agent(
    model="anthropic:claude-haiku-4-5",
    backend=StoreBackend(store=store, namespace=["project", "docs"]),
)

# 3. CompositeBackend — routes paths to different backends
#    First arg is the default backend; routes override specific paths
agent_composite = create_deep_agent(
    model="anthropic:claude-haiku-4-5",
    backend=CompositeBackend(
        StateBackend(),  # Default backend for unmatched paths
        routes={
            "/memories/": StoreBackend(store=store, namespace=["user", "memory"]),
        },
    ),
)

# Invoke the composite agent — writes to /memories/ persist across threads
result = agent_composite.invoke({
    "messages": [{"role": "user", "content": "Remember that I prefer Python over JavaScript."}]
})
print(result["messages"][-1].content)

4.3 Sandbox Integration

For agents that need to run generated code, sandboxes provide isolated execution environments. The recommended pattern is "sandbox as tool" — the sandbox is exposed to the agent as a tool, rather than running the entire agent inside the sandbox:

# pip install deepagents langchain-anthropic langsmith
from deepagents import create_deep_agent
from deepagents.backends import LangSmithSandbox
from langsmith.sandbox import Sandbox

# Create a LangSmith sandbox for isolated code execution
# The sandbox runs code in an isolated environment with a timeout
sandbox = Sandbox()  # Requires LANGSMITH_API_KEY environment variable
backend = LangSmithSandbox(sandbox)

# Pass the sandbox as the backend — the agent's filesystem tools
# (ls, read, write, execute) are routed to the sandbox
agent = create_deep_agent(
    model="anthropic:claude-haiku-4-5",  # Cheap model for sandbox demos
    backend=backend,
    system_prompt="""You are a data scientist. When you need to run code:
1. Write the script to the filesystem
2. Use the execute tool to run it
3. Analyze the output""",
)

result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": "Generate a Monte Carlo simulation for option pricing and run it."
    }]
})
print(result["messages"][-1].content)

flowchart LR
    A["Deep Agent"] -->|"write_file()"| B["Virtual Filesystem
(Backend)"]
    A -->|"execute()"| C["Sandbox Backend"]
    C --> D["Isolated Container
(Python, Node, Bash)"]
    D -->|"stdout/stderr"| A
    B -->|"upload files"| C
    C -->|"download results"| B
                            

5. Subagents & Task Delegation

The most powerful feature of Deep Agents is subagent delegation. When the main agent encounters a task that would consume significant context — like researching a topic, generating a large code file, or analyzing a document — it can spawn a subagent that runs with a fresh context window. The subagent completes the task and returns only the final result, keeping the main agent's context clean.

5.1 Subagent Configuration

Subagents are defined as dictionaries with a name, description, tools, and optional model override:

# pip install deepagents langchain-anthropic langchain-openai langchain-community ddgs
from deepagents import create_deep_agent
from langchain_community.tools import DuckDuckGoSearchRun

# Define specialized subagents for different tasks
research_subagent = {
    "name": "research_agent",
    "description": "Researches topics using web search. Delegates here for any information gathering.",
    "tools": [DuckDuckGoSearchRun()],
    "model": "openai:gpt-4.1-mini",  # Cheap and fast for web search tasks
    "system_prompt": "You are a research specialist. Search thoroughly and synthesize findings.",
}

code_subagent = {
    "name": "code_agent",
    "description": "Writes, tests, and debugs code. Delegates here for any programming tasks.",
    "tools": [],  # Uses filesystem tools by default
    "model": "anthropic:claude-sonnet-4-6",  # Use a capable model for code generation
    "system_prompt": "You are a senior Python developer. Write clean, tested code.",
}

# Main agent with two specialized subagents
agent = create_deep_agent(
    model="anthropic:claude-haiku-4-5",  # Cheap model for delegation
    subagents=[research_subagent, code_subagent],
    system_prompt="You are a project lead. Delegate research to the research agent and coding to the code agent.",
)

result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": "Research the best practices for rate limiting in APIs, then write a Python implementation."
    }]
})
print(result["messages"][-1].content)

5.2 General-Purpose Subagent

Every Deep Agent automatically includes a general-purpose subagent that inherits the main agent's tools, system prompt, model, and skills. This is useful for delegating tasks that don't need a specialized configuration — the main agent simply needs context isolation:

# pip install deepagents langchain-anthropic
from deepagents import create_deep_agent

# The general-purpose subagent is always available
# The main agent can use it to delegate any task for context isolation
agent = create_deep_agent(
    model="anthropic:claude-haiku-4-5",  # Cheap model for delegation
    system_prompt="""You are an analyst. For large analysis tasks, delegate to the
general-purpose subagent to keep your own context clean.""",
)

# When invoked, the main agent can call the built-in "task" tool:
# task(agent="general", description="Analyze the 500-row dataset and return top insights")
# The general subagent runs with fresh context, returns only the summary

result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": "Analyze the top 50 tech companies by revenue and identify growth trends."
    }]
})
print(result["messages"][-1].content)

5.3 Subagent Context Management

Runtime context propagates from the main agent to all subagents, enabling shared configuration without shared conversation history. You can also use namespaced keys for per-subagent configuration:

# pip install deepagents langchain-anthropic
from deepagents import create_deep_agent

agent = create_deep_agent(
    model="anthropic:claude-haiku-4-5",  # Cheap for orchestration
    subagents=[
        {
            "name": "writer",
            "description": "Writes technical documentation.",
            "system_prompt": "You are a technical writer.",
        }
    ],
)

# Runtime context is passed via the config dict
# It propagates to all subagents automatically
result = agent.invoke(
    {"messages": [{"role": "user", "content": "Write API docs for the auth module."}]},
    config={
        "configurable": {
            "user_name": "Alice",
            "project": "acme-api",
            # Namespaced keys for subagent-specific config
            "writer:style_guide": "Google developer documentation style",
            "writer:max_length": 5000,
        }
    },
)
print(result["messages"][-1].content)

sequenceDiagram
    participant User
    participant Main as Main Agent
    participant Task as task() tool
    participant Sub as Subagent
    participant FS as Filesystem

    User->>Main: Complex request
    Main->>Main: write_todos (plan steps)
    Main->>Task: Delegate research task
    Task->>Sub: Spawn with fresh context
    Sub->>Sub: Execute tools (search, read, write)
    Sub->>FS: Save intermediate results
    Sub->>Task: Return final summary only
    Task->>Main: 2,000-token summary
    Main->>Main: Continue with next to-do item
    Main->>User: Final answer
                            

6. Human-in-the-Loop & Permissions

Autonomous agents need guardrails. Deep Agents provide two complementary safety mechanisms: interrupt-on for pausing execution before critical tool calls, and filesystem permissions for restricting what the agent can read, write, and execute.

6.1 Interrupt-On Configuration

The interrupt_on parameter is a dictionary mapping tool names to boolean values. When set to True, the agent pauses execution and returns control to the caller for approval before invoking that tool:

# pip install deepagents langchain-anthropic
from deepagents import create_deep_agent

# Require human approval before executing code or writing files
agent = create_deep_agent(
    model="anthropic:claude-haiku-4-5",  # Cheap model for demos
    interrupt_on={
        "execute": True,      # Pause before running any shell command
        "write_file": True,   # Pause before creating/overwriting files
        "edit_file": True,    # Pause before editing existing files
    },
    system_prompt="You are a code assistant. Always explain what you plan to do before doing it.",
)

# First invocation — agent plans its work and hits the interrupt
result = agent.invoke({
    "messages": [{"role": "user", "content": "Fix the bug in main.py"}]
})

# The result contains an 'interrupt' key with the pending tool call details
if "interrupt" in result:
    pending_call = result["interrupt"]
    print(f"Agent wants to call: {pending_call['tool']}")
    print(f"With arguments: {pending_call['args']}")

    # To approve and continue:
    # result = agent.invoke({"messages": [], "approve": True})
    # To reject:
    # result = agent.invoke({"messages": [], "approve": False, "feedback": "Don't edit that file."})

6.2 Filesystem Permissions

Permissions are declarative rules that restrict the agent's filesystem access. Rules are evaluated in order with first-match-wins semantics:

# pip install deepagents langchain-anthropic
from deepagents import create_deep_agent
from deepagents.middleware.permissions import FilesystemPermission

agent = create_deep_agent(
    model="anthropic:claude-haiku-4-5",  # Cheap model for demos
    permissions=[
        # Allow reading anything in the /docs/ directory
        FilesystemPermission(paths=["/docs/**"], operations=["read"], mode="allow"),

        # Allow reading and writing to the /output/ directory
        FilesystemPermission(paths=["/output/**"], operations=["read", "write"], mode="allow"),

        # Block all access to sensitive directories
        FilesystemPermission(paths=["/secrets/**", "/.env"], operations=["read", "write"], mode="deny"),

        # Default: read-only access to everything else
        FilesystemPermission(paths=["/**"], operations=["read"], mode="allow"),
    ],
    system_prompt="You are a documentation agent. Read source files and write docs to /output/.",
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "Generate API docs from the source files in /docs/."}]
})
print(result["messages"][-1].content)

6.3 Security Considerations

7. Memory, Skills & Streaming

Deep Agents support three advanced capabilities that transform them from single-session tools into persistent, knowledgeable, real-time systems: long-term memory for cross-conversation persistence, skills for progressive knowledge disclosure, and streaming for real-time execution visibility.

7.1 Long-Term Memory

Long-term memory is implemented using the CompositeBackend pattern. By routing the /memories/ path to a StoreBackend, any files the agent writes to that directory persist across conversation threads:

# pip install deepagents langchain-anthropic
from deepagents import create_deep_agent
from deepagents.backends import StateBackend, CompositeBackend, StoreBackend
from langgraph.store.memory import InMemoryStore

# Create a persistent store (use PostgresStore for production)
store = InMemoryStore()

# CompositeBackend routes /memories/ to persistent storage
# First arg is the default backend; routes override specific paths
agent = create_deep_agent(
    model="anthropic:claude-haiku-4-5",  # Cheap model for demos
    backend=CompositeBackend(
        StateBackend(),  # Default: ephemeral in-memory storage
        routes={
            "/memories/": StoreBackend(store=store, namespace=["user", "preferences"]),
        },
    ),
    system_prompt="""You are a personal assistant with long-term memory.

When you learn something about the user (preferences, context, past decisions),
save it to /memories/user-profile.md using write_file.

At the start of each conversation, check /memories/ for existing knowledge.""",
)

# First conversation — agent learns preferences
result = agent.invoke({
    "messages": [{"role": "user", "content": "I prefer dark mode, Python over JS, and concise answers."}]
})
print(result["messages"][-1].content)

# Next conversation (new thread) — agent retrieves saved preferences
result = agent.invoke({
    "messages": [{"role": "user", "content": "Set up a new project for me."}]
})
# Agent checks /memories/user-profile.md and applies stored preferences
print(result["messages"][-1].content)

7.2 Agent Skills

Skills are knowledge modules defined as SKILL.md files with YAML frontmatter. The SDK implements progressive disclosure — at startup, only the frontmatter (name, description, triggers) is loaded into context. When the agent determines a skill is relevant, it loads the full content on demand:

# pip install deepagents langchain-anthropic
from deepagents import create_deep_agent

# Skills are SKILL.md files with YAML frontmatter
# Example SKILL.md content:
#
# ---
# name: sql-optimization
# description: Advanced SQL query optimization techniques
# triggers:
#   - slow query
#   - performance tuning
#   - query optimization
#   - explain plan
# ---
#
# # SQL Optimization Skill
#
# ## Index Selection
# When optimizing queries, consider...
#
# ## Query Rewriting
# Common patterns for rewriting slow queries...

agent = create_deep_agent(
    model="anthropic:claude-haiku-4-5",  # Cheap model for demos
    skills=[
        "skills/sql-optimization.md",
        "skills/api-design.md",
        "skills/security-review.md",
    ],
    system_prompt="You are a senior engineer. Use your skills when relevant.",
)

# When the user asks about slow queries, the agent:
# 1. Matches "slow query" against skill triggers
# 2. Loads the full sql-optimization.md content
# 3. Uses the knowledge to provide an expert answer
result = agent.invoke({
    "messages": [{"role": "user", "content": "My dashboard query is taking 30 seconds."}]
})
print(result["messages"][-1].content)

7.3 Streaming Deep Agents

Deep Agents support multiple streaming modes for real-time visibility into agent execution. The stream() method accepts a stream_mode parameter and returns events as they occur:

# pip install deepagents langchain-anthropic
from deepagents import create_deep_agent

agent = create_deep_agent(
    model="anthropic:claude-haiku-4-5",  # Cheapest Anthropic model
    system_prompt="You are a helpful assistant.",
)

# Stream with v2 format — returns StreamPart dicts with type, namespace, and data
for event in agent.stream(
    {"messages": [{"role": "user", "content": "Explain gradient descent in 3 paragraphs."}]},
    stream_mode="messages",
    version="v2",
):
    # Each event is a StreamPart dict:
    # {"type": "messages", "ns": [], "data": (AIMessageChunk, {"langgraph_step": 1})}
    if event["type"] == "messages":
        chunk = event["data"][0]
        if hasattr(chunk, "content") and chunk.content:
            print(chunk.content, end="", flush=True)

print()  # Newline after streaming completes

Available stream modes:

For applications with subagents, enable subgraphs=True to receive events from child agents with namespace prefixes:

# pip install deepagents langchain-anthropic
from deepagents import create_deep_agent

agent = create_deep_agent(
    model="anthropic:claude-haiku-4-5",  # Cheap model for demos
    subagents=[{
        "name": "researcher",
        "description": "Researches topics thoroughly.",
        "system_prompt": "You are a research agent.",
    }],
)

# Stream with subgraph events — namespace identifies the source agent
for event in agent.stream(
    {"messages": [{"role": "user", "content": "Research quantum computing advances in 2026."}]},
    stream_mode="updates",
    subgraphs=True,
    version="v2",
):
    ns = event.get("ns", [])
    source = " > ".join(ns) if ns else "main"
    print(f"[{source}] {event['type']}: {list(event['data'].keys())}")

8. Customization & Advanced Configuration

Beyond the core architecture, the Deep Agents SDK exposes a rich customization surface — custom tools, connection resilience, the built-in middleware stack, tool call interception, and structured output. This section covers the configuration options that let you tailor agents for production environments.

8.1 Custom Tools

In addition to the built-in filesystem and planning tools, you can pass any Python function as a custom tool. Functions are automatically converted using LangChain's tool infrastructure — the docstring becomes the tool description and type hints define the parameter schema:

# pip install deepagents langchain-anthropic
from typing import Literal
from deepagents import create_deep_agent

def get_weather(
    city: str,
    unit: Literal["celsius", "fahrenheit"] = "celsius",
) -> str:
    """Get the current weather for a city."""
    # In production, call a real weather API here
    return f"The weather in {city} is 22°{unit[0].upper()} and sunny."

def calculate_bmi(weight_kg: float, height_m: float) -> str:
    """Calculate Body Mass Index from weight (kg) and height (meters)."""
    bmi = weight_kg / (height_m ** 2)
    return f"BMI: {bmi:.1f}"

# Pass custom tools alongside the built-in filesystem and planning tools
agent = create_deep_agent(
    model="anthropic:claude-haiku-4-5",
    tools=[get_weather, calculate_bmi],
    system_prompt="You are a helpful assistant with access to weather and health tools.",
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "What's the weather like in Tokyo?"}]
})
print(result["messages"][-1].content)

8.2 Connection Resilience

LangChain chat models automatically retry failed API requests with exponential backoff. By default, models retry up to 6 times for network errors, rate limits (429), and server errors (5xx). Client errors like 401 (unauthorized) or 404 are not retried. You can tune this behavior for unreliable networks or long-running tasks:

# pip install deepagents langchain-anthropic
from langchain.chat_models import init_chat_model
from deepagents import create_deep_agent

# Configure resilience for unreliable networks or rate-limited APIs
model = init_chat_model(
    "anthropic:claude-haiku-4-5",
    max_retries=12,   # Increase from default 6 for unreliable networks
    timeout=120,      # Seconds — increase for slow connections or large responses
)

agent = create_deep_agent(
    model=model,
    system_prompt="You are a research assistant. Be thorough and cite sources.",
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "Summarize the latest trends in edge computing."}]
})
print(result["messages"][-1].content)

8.3 Built-in Middleware Stack

Every Deep Agent comes with a default set of middleware that powers its core capabilities. Understanding this stack helps you know what's running under the hood and when additional middleware is automatically added:

Your custom middleware (passed via the middleware parameter) is added alongside the built-in stack, not as a replacement. This means you can intercept model calls, tool calls, or agent steps without losing any built-in functionality.

8.4 Custom Tool Call Middleware

While wrap_model_call intercepts LLM calls (Section 2.3), wrap_tool_call intercepts tool executions. This is useful for cross-cutting concerns like logging, metrics, rate limiting, or auditing every tool the agent invokes:

# pip install deepagents langchain-anthropic
from langchain.tools import tool
from langchain.agents.middleware import wrap_tool_call
from deepagents import create_deep_agent

@tool
def get_weather(city: str) -> str:
    """Get the weather in a city."""
    return f"The weather in {city} is sunny and 22°C."

call_count = [0]  # List to allow modification in nested function

@wrap_tool_call
def log_tool_calls(request, handler):
    """Intercept and log every tool call."""
    call_count[0] += 1
    tool_name = request.name if hasattr(request, "name") else str(request)

    print(f"[Middleware] Tool call #{call_count[0]}: {tool_name}")
    print(f"[Middleware] Arguments: {request.args if hasattr(request, 'args') else 'N/A'}")

    # Execute the actual tool call
    result = handler(request)

    print(f"[Middleware] Tool call #{call_count[0]} completed")
    return result

agent = create_deep_agent(
    model="anthropic:claude-haiku-4-5",
    tools=[get_weather],
    middleware=[log_tool_calls],
    system_prompt="You are a helpful assistant. Use the weather tool when asked about weather.",
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "What's the weather in London?"}]
})
print(result["messages"][-1].content)

8.5 Structured Output

Deep Agents can return validated, typed data instead of free-form text. Pass a Pydantic model as the response_format argument, and the SDK ensures the agent's final response matches the schema. The validated data is returned in the structured_response key:

# pip install deepagents langchain-anthropic pydantic
from pydantic import BaseModel, Field
from deepagents import create_deep_agent

class CompanyAnalysis(BaseModel):
    """A structured analysis of a company."""
    name: str = Field(description="Company name")
    industry: str = Field(description="Primary industry")
    strengths: list[str] = Field(description="Key competitive strengths")
    risks: list[str] = Field(description="Primary risk factors")
    recommendation: str = Field(description="Buy, hold, or sell recommendation")
    confidence: float = Field(description="Confidence score from 0.0 to 1.0")

agent = create_deep_agent(
    model="anthropic:claude-haiku-4-5",
    response_format=CompanyAnalysis,
    system_prompt="You are a financial analyst. Provide concise, data-driven analysis.",
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "Analyze Apple Inc. as an investment."}]
})

# The structured response is a validated Pydantic model instance
analysis = result["structured_response"]
print(f"Company: {analysis.name}")
print(f"Industry: {analysis.industry}")
print(f"Strengths: {', '.join(analysis.strengths)}")
print(f"Risks: {', '.join(analysis.risks)}")
print(f"Recommendation: {analysis.recommendation} (confidence: {analysis.confidence})")

flowchart TD
    A["create_deep_agent()"] --> B["model"]
    A --> C["tools"]
    A --> D["system_prompt"]
    A --> E["middleware"]
    A --> F["subagents"]
    A --> G["backend"]
    A --> H["interrupt_on"]
    A --> I["skills"]
    A --> J["memory"]
    A --> K["response_format"]
    B --> B1["provider:model string
or init_chat_model()"]
    C --> C1["Custom functions
@tool decorators
BaseTool subclasses"]
    E --> E1["wrap_model_call
wrap_tool_call
AgentMiddleware"]
    G --> G1["StateBackend
StoreBackend
CompositeBackend
Sandbox"]
    K --> K1["Pydantic BaseModel
→ structured_response"]
                            

Deep Agents v0.6 Update (May 2026)

9.1 Code Interpreter & Programmatic Tool Calling

The code interpreter gives agents a lightweight JavaScript runtime (QuickJS) where they can compose tool calls, manage intermediate state, and filter what returns to the model context. This enables Programmatic Tool Calling (PTC) — instead of the model making one tool call per turn and waiting for the result, it writes code that orchestrates multiple tool calls, processes results, and returns only what matters. This reduces token consumption and avoidable model round trips.

# pip install deepagents[quickjs]
from deepagents import create_deep_agent
from langchain_quickjs import REPLMiddleware

# Add the code interpreter as middleware
agent = create_deep_agent(
    model="openai:gpt-5.4",
    middleware=[REPLMiddleware()],
    system_prompt="Use the interpreter to compose tool calls efficiently."
)

# The agent can now write code like this inside the interpreter:
# const topics = ["retrieval", "memory", "evaluation"];
# const reports = await Promise.all(
#   topics.map(topic =>
#     tools.task({
#       description: `Research ${topic} and return 3 findings.`,
#       subagent_type: "general-purpose"
#     })
#   )
# );
# reports.join("\n\n");

9.2 Harness Profiles for Open-Weight Models

Open-weight models like Kimi K2.6, GLM 5.1, and DeepSeek V4 are now viable for production agent work at 20×+ lower cost than closed frontier models. The challenge is that each model is post-trained on different tool-calling formats and prompt conventions. A harness profile captures per-model overrides for the system prompt, tool descriptions, and middleware as a named, versionable unit:

# pip install deepagents langchain-google-genai
from deepagents import create_deep_agent

# Built-in profiles ship for major models — strong performance is the default
agent = create_deep_agent(
    model="baseten:zai-org/GLM-5",  # Open-weight model at fraction of frontier cost
    middleware=[REPLMiddleware()],
)

# In LangChain's own benchmarks, harness-layer changes alone moved:
# - gpt-5.2-codex: 52.8% → 66.5% on Terminal-Bench 2.0 (Top 30 → Top 5)
# - gpt-5.3-codex: +20% on tau2-bench
# - opus-4.7: +10% on tau2-bench
# Across tau2-bench, prompts and middleware can move scores 10-20 points
# without changing the model.

9.3 DeltaChannel — Efficient Checkpoint Storage

As agents run longer (dozens to hundreds of steps), the default full-snapshot checkpointing model causes storage to grow at O(N²) because each checkpoint contains everything from all previous steps. DeltaChannel is a new LangGraph 1.2 primitive that stores only the diff at each step, with periodic full snapshots every K steps. For Deep Agents, both messages and files are delta-backed by default in v0.6:

# DeltaChannel is ON by default in deepagents v0.6
# No configuration required — just upgrade:
# pip install -U deepagents

# Benchmark results (simulated 200-turn multi-file coding session):
# Without DeltaChannel: 5.27 GB checkpoint storage
# With DeltaChannel:    129 MB (41× reduction)

# For custom LangGraph state, you can use DeltaChannel directly:
from typing_extensions import Annotated
from langgraph.channels.delta import DeltaChannel

def append(state: list[str], writes: list[list[str]]) -> list[str]:
    return state + [item for batch in writes for item in batch]

from typing import TypedDict

class MyAgentState(TypedDict):
    items: Annotated[
        list[str],
        DeltaChannel(reducer=append, snapshot_frequency=50)
    ]

9.4 ContextHub Backend

Context Hub is a LangSmith-backed versioned filesystem for Deep Agents. It stores the AGENTS.md files, skills, policies, and memories that shape agent behavior — so improvements from one run carry forward to the next. Writes land as commits with history, review, and environment tagging (dev/staging/prod):

# pip install deepagents langsmith
from deepagents import create_deep_agent
from deepagents.backends import ContextHubBackend, CompositeBackend, StateBackend

# Option 1: Use Context Hub as the entire filesystem backend
agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    backend=ContextHubBackend("my-agent"),
)

# Option 2: Scope just /memories/ to Hub, keep rest thread-scoped
agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": ContextHubBackend("my-agent"),
        },
    ),
)

# Reads are served from cache; writes are committed back to the Hub repo.
# If the repo doesn't exist yet, the first write creates it.
# Requires LANGSMITH_API_KEY environment variable.

9.5 Streaming v3 — Typed Event Projections

The new streaming v3 protocol replaces raw event parsing with typed, subscribable projections for messages, tool calls, subagents, reasoning blocks, and custom channels. Frontend integrations ship for React, Vue, Svelte, and Angular:

# pip install deepagents
from deepagents import create_deep_agent

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-20250514",
    tools=[get_weather],
)

# Streaming v3 — typed projections instead of raw events
stream = agent.stream_events(
    {"messages": [{"role": "user", "content": "Research LangChain streaming"}]},
    version="v3",
)

# Subscribe to message text deltas
for message in stream.messages:
    for delta in message.text:
        print(delta, end="", flush=True)

# Subscribe to subagent progress
for subagent in stream.subagents:
    print(f"\n[{subagent.name}] {subagent.status}")
    for message in subagent.messages:
        for delta in message.text:
            print(delta, end="", flush=True)

9.6 Managed Deep Agents

Managed Deep Agents provides an API-first hosted runtime for creating, running, and operating deep agents in LangSmith. No need to stand up your own agent server — define agents using the familiar Deep Agents project structure, manage them through the /v1/deepagents API, and inspect every run in LangSmith:

# Managed Deep Agents — create and run agents via LangSmith API
# Key features:
# - Durable threads, streaming runs, checkpointing
# - Human-in-the-loop workflows for long-running tasks
# - Agent context/files: AGENTS.md, skills/, subagents/, tools.json
# - Context Hub for memory, operating notes, user preferences
# - Sandbox-backed execution for code, shell, file I/O

# Deploy via LangSmith CLI:
# langsmith agents create my-agent --project-dir ./my-agent/
# langsmith agents run my-agent --message "Analyze this dataset"

Exercises & Challenges

Apply your understanding of the Deep Agents SDK with these hands-on exercises. Each builds on a different aspect of the harness architecture.

Deep Agent Design Generator

Use this interactive tool to design and document a Deep Agent architecture. Fill in the fields below and download your design document as Word, Excel, PDF, or PowerPoint.

Conclusion & Next Steps

In this article, we explored the LangChain Deep Agents SDK — a batteries-included library that assembles autonomous agents from a single create_deep_agent() call. Here are the key takeaways: