Deep Agents — Architecture & Review

Concern	Section
Architectural decisions, framework choice, subagent/middleware design	Architecture
Reviewing existing Deep Agents code for bugs and anti-patterns	Code Review

Architecture

Deep Agents Architecture Decisions

When to Use Deep Agents

Use Deep Agents When You Need:

Long-horizon tasks - Complex workflows spanning dozens of tool calls
Planning capabilities - Task decomposition before execution
Filesystem operations - Reading, writing, and editing files
Subagent delegation - Isolated task execution with separate context windows
Persistent memory - Long-term storage across conversations
Human-in-the-loop - Approval gates for sensitive operations
Context management - Auto-summarization for long conversations

Consider Alternatives When:

Scenario	Alternative	Why
Single LLM call	Direct API call	Deep Agents overhead not justified
Simple RAG pipeline	LangChain LCEL	Simpler abstraction
Custom graph control flow	LangGraph directly	More flexibility
No file operations needed	`create_react_agent`	Lighter weight
Stateless tool use	Function calling	No middleware needed

Backend Selection

Backend Comparison

Backend	Persistence	Use Case	Requires
`StateBackend`	Ephemeral (per-thread)	Working files, temp data	Nothing (default)
`FilesystemBackend`	Disk	Local development, real files	`root_dir` path
`StoreBackend`	Cross-thread	User preferences, knowledge bases	LangGraph `store`
`CompositeBackend`	Mixed	Hybrid memory patterns	Multiple backends

Backend Decision Tree

Need real disk access?
├─ Yes → FilesystemBackend(root_dir="/path")
└─ No
   └─ Need persistence across conversations?
      ├─ Yes → Need mixed ephemeral + persistent?
      │  ├─ Yes → CompositeBackend
      │  └─ No → StoreBackend
      └─ No → StateBackend (default)

CompositeBackend Routing

Route different paths to different storage backends:

python

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend

agent = create_deep_agent(
    backend=CompositeBackend(
        default=StateBackend(),  # Working files (ephemeral)
        routes={
            "/memories/": StoreBackend(store=store),    # Persistent
            "/preferences/": StoreBackend(store=store), # Persistent
        },
    ),
)

Subagent Architecture

When to Use Subagents

Use subagents when:

Task is complex, multi-step, and can run independently
Task requires heavy context that would bloat the main thread
Multiple independent tasks can run in parallel
You need isolated execution (sandboxing)
You only care about the final result, not intermediate steps

Don't use subagents when:

Task is trivial (few tool calls)
You need to see intermediate reasoning
Splitting adds latency without benefit
Task depends on main thread state mid-execution

Subagent Patterns

Pattern 1: Parallel Research

         ┌─────────────┐
         │  Orchestrator│
         └──────┬──────┘
    ┌──────────┼──────────┐
    ▼          ▼          ▼
┌──────┐  ┌──────┐  ┌──────┐
│Task A│  │Task B│  │Task C│
└──┬───┘  └──┬───┘  └──┬───┘
   └──────────┼──────────┘
              ▼
      ┌─────────────┐
      │  Synthesize │
      └─────────────┘

Best for: Research on multiple topics, parallel analysis, batch processing.

Pattern 2: Specialized Agents

python

research_agent = {
    "name": "researcher",
    "description": "Deep research on complex topics",
    "system_prompt": "You are an expert researcher...",
    "tools": [web_search, document_reader],
}

coder_agent = {
    "name": "coder",
    "description": "Write and review code",
    "system_prompt": "You are an expert programmer...",
    "tools": [code_executor, linter],
}

agent = create_deep_agent(subagents=[research_agent, coder_agent])

Best for: Domain-specific expertise, different tool sets per task type.

Pattern 3: Pre-compiled Subagents

python

from deepagents import CompiledSubAgent, create_deep_agent

# Use existing LangGraph graph as subagent
custom_graph = create_react_agent(model=..., tools=...)

agent = create_deep_agent(
    subagents=[CompiledSubAgent(
        name="custom-workflow",
        description="Runs specialized workflow",
        runnable=custom_graph
    )]
)

Best for: Reusing existing LangGraph graphs, complex custom workflows.

Middleware Architecture

Built-in Middleware Stack

Deep Agents applies middleware in this order:

TodoListMiddleware - Task planning with
```
write_todos
```
/
```
read_todos
```

FilesystemMiddleware - File ops:

ls

read_file

write_file

edit_file

glob

grep

execute

SubAgentMiddleware - Delegation via
```
task
```
tool
SummarizationMiddleware - Auto-summarizes at ~85% context or 170k tokens
AnthropicPromptCachingMiddleware - Caches system prompts (Anthropic only)
PatchToolCallsMiddleware - Fixes dangling tool calls from interruptions
HumanInTheLoopMiddleware - Pauses for approval (if
```
interrupt_on
```
configured)

Custom Middleware Placement

python

from langchain.agents.middleware import AgentMiddleware

class MyMiddleware(AgentMiddleware):
    tools = [my_custom_tool]

    def transform_request(self, request):
        # Modify system prompt, inject context
        return request

    def transform_response(self, response):
        # Post-process, log, filter
        return response

# Custom middleware added AFTER built-in stack
agent = create_deep_agent(middleware=[MyMiddleware()])

Middleware vs Tools Decision

Need	Use Middleware	Use Tools
Inject system prompt content	✅	❌
Add tools dynamically	✅	❌
Transform requests/responses	✅	❌
Standalone capability	❌	✅
User-invokable action	❌	✅

Subagent Middleware Inheritance

Subagents receive their own middleware stack by default:

TodoListMiddleware
FilesystemMiddleware (shared backend)
SummarizationMiddleware
AnthropicPromptCachingMiddleware
PatchToolCallsMiddleware

Override with

default_middleware=[]

in SubAgentMiddleware or per-subagent

middleware

key.

Architecture Decision Checklist

Before implementing:

Is Deep Agents the right tool? (vs LangGraph directly, vs simpler agent)
Backend strategy chosen?
- Ephemeral only → StateBackend (default)
- Need disk access → FilesystemBackend
- Need cross-thread persistence → StoreBackend or CompositeBackend
Subagent strategy defined?
- Which tasks benefit from isolation?
- Custom subagents with specialized tools/prompts?
- Parallel execution opportunities identified?
Human-in-the-loop points defined?
- Which tools need approval?
- Approval flow (approve/edit/reject)?
Custom middleware needed?
- System prompt injection?
- Request/response transformation?
Context management considered?
- Long conversations → summarization triggers
- Large file handling → use references
Checkpointing strategy? (for persistence/resume)

Code Review

Deep Agents Code Review

When reviewing Deep Agents code, check for these categories of issues.

Critical Issues

1. Missing Checkpointer with interrupt_on

python

# BAD - interrupt_on without checkpointer
agent = create_deep_agent(
    tools=[send_email],
    interrupt_on={"send_email": True},
    # No checkpointer! Interrupts will fail
)

# GOOD - checkpointer required for interrupts
from langgraph.checkpoint.memory import InMemorySaver

agent = create_deep_agent(
    tools=[send_email],
    interrupt_on={"send_email": True},
    checkpointer=InMemorySaver(),
)

2. Missing Store with StoreBackend

python

# BAD - StoreBackend without store
from deepagents.backends import StoreBackend

agent = create_deep_agent(
    backend=lambda rt: StoreBackend(rt),
    # No store! Will raise ValueError at runtime
)

# GOOD - provide store
from langgraph.store.memory import InMemoryStore

store = InMemoryStore()
agent = create_deep_agent(
    backend=lambda rt: StoreBackend(rt),
    store=store,
)

3. Missing thread_id with Checkpointer

python

# BAD - no thread_id when using checkpointer
agent = create_deep_agent(checkpointer=InMemorySaver())
agent.invoke({"messages": [...]})  # Error!

# GOOD - always provide thread_id
config = {"configurable": {"thread_id": "user-123"}}
agent.invoke({"messages": [...]}, config)

4. Relative Paths in Filesystem Tools

python

# BAD - relative paths not supported
read_file(path="src/main.py")
read_file(path="./config.json")

# GOOD - absolute paths required
read_file(path="/workspace/src/main.py")
read_file(path="/config.json")

5. Windows Paths in Virtual Filesystem

python

# BAD - Windows paths rejected
read_file(path="C:\\Users\\file.txt")
write_file(path="D:/projects/code.py", content="...")

# GOOD - Unix-style virtual paths
read_file(path="/workspace/file.txt")
write_file(path="/projects/code.py", content="...")

Backend Issues

6. StateBackend Expecting Persistence

python

# BAD - expecting files to persist across threads
agent = create_deep_agent()  # Uses StateBackend by default

# Thread 1
agent.invoke({"messages": [...]}, {"configurable": {"thread_id": "a"}})
# Agent writes to /data/report.txt

# Thread 2 - file won't exist!
agent.invoke({"messages": [...]}, {"configurable": {"thread_id": "b"}})
# Agent tries to read /data/report.txt - NOT FOUND

# GOOD - use StoreBackend or CompositeBackend for cross-thread persistence
agent = create_deep_agent(
    backend=CompositeBackend(
        default=StateBackend(),
        routes={"/data/": StoreBackend(store=store)},
    ),
    store=store,
)

7. FilesystemBackend Without root_dir Restriction

python

# BAD - unrestricted filesystem access
agent = create_deep_agent(
    backend=FilesystemBackend(root_dir="/"),  # Full system access!
)

# GOOD - scope to project directory
agent = create_deep_agent(
    backend=FilesystemBackend(root_dir="/home/user/project"),
)

8. CompositeBackend Route Order Confusion

python

# BAD - shorter prefix shadows longer prefix
agent = create_deep_agent(
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/mem/": backend_a,        # This catches /mem/long-term/ too!
            "/mem/long-term/": backend_b,  # Never reached
        },
    ),
)

# GOOD - CompositeBackend sorts by length automatically
# But be explicit about your intent:
agent = create_deep_agent(
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": persistent_backend,
            "/workspace/": ephemeral_backend,
        },
    ),
)

9. Expecting execute Tool Without SandboxBackend

python

# BAD - execute tool won't work with StateBackend
agent = create_deep_agent()  # Default StateBackend
# Agent calls execute("ls -la") → Error: not supported

# GOOD - use FilesystemBackend for shell execution
agent = create_deep_agent(
    backend=FilesystemBackend(root_dir="/project"),
)
# Agent calls execute("ls -la") → Works

Subagent Issues

10. Subagent Missing Required Fields

python

# BAD - missing required fields
agent = create_deep_agent(
    subagents=[{
        "name": "helper",
        # Missing: description, system_prompt, tools
    }]
)

# GOOD - all required fields present
agent = create_deep_agent(
    subagents=[{
        "name": "helper",
        "description": "General helper for misc tasks",
        "system_prompt": "You are a helpful assistant.",
        "tools": [],  # Can be empty but must be present
    }]
)

11. Subagent Name Collision

python

# BAD - duplicate subagent names
agent = create_deep_agent(
    subagents=[
        {"name": "research", "description": "A", ...},
        {"name": "research", "description": "B", ...},  # Collision!
    ]
)

# GOOD - unique names
agent = create_deep_agent(
    subagents=[
        {"name": "web-research", "description": "Web-based research", ...},
        {"name": "doc-research", "description": "Document research", ...},
    ]
)

12. Overusing Subagents for Simple Tasks

python

# BAD - subagent overhead for trivial task
# In system prompt or agent behavior:
"Use the task tool to check the current time"
"Delegate file reading to a subagent"

# GOOD - use subagents for complex, isolated work
"Use the task tool for multi-step research that requires many searches"
"Delegate the full analysis workflow to a subagent"

13. CompiledSubAgent Without Proper State

python

# BAD - subgraph with incompatible state schema
from langgraph.graph import StateGraph

class CustomState(TypedDict):
    custom_field: str  # No messages field!

sub_builder = StateGraph(CustomState)
# ... build graph
subgraph = sub_builder.compile()

agent = create_deep_agent(
    subagents=[CompiledSubAgent(
        name="custom",
        description="Custom workflow",
        runnable=subgraph,  # State mismatch!
    )]
)

# GOOD - ensure compatible state or use message-based interface
class CompatibleState(TypedDict):
    messages: Annotated[list, add_messages]
    custom_field: str

Middleware Issues

14. Middleware Order Misunderstanding

python

# BAD - expecting custom middleware to run first
class PreProcessMiddleware(AgentMiddleware):
    def transform_request(self, request):
        # Expecting this runs before built-in middleware
        return request

agent = create_deep_agent(middleware=[PreProcessMiddleware()])
# Actually runs AFTER TodoList, Filesystem, SubAgent, etc.

# GOOD - understand middleware runs after built-in stack
# Built-in order:
# 1. TodoListMiddleware
# 2. FilesystemMiddleware
# 3. SubAgentMiddleware
# 4. SummarizationMiddleware
# 5. AnthropicPromptCachingMiddleware
# 6. PatchToolCallsMiddleware
# 7. YOUR MIDDLEWARE HERE
# 8. HumanInTheLoopMiddleware (if interrupt_on set)

15. Middleware Mutating Request/Response

python

# BAD - mutating instead of returning new object
class BadMiddleware(AgentMiddleware):
    def transform_request(self, request):
        request.messages.append(extra_message)  # Mutation!
        return request

# GOOD - return modified copy
class GoodMiddleware(AgentMiddleware):
    def transform_request(self, request):
        return ModelRequest(
            messages=[*request.messages, extra_message],
            **other_fields
        )

16. Middleware Tools Without Descriptions

python

# BAD - tool without docstring
@tool
def my_tool(arg: str) -> str:
    return process(arg)

class MyMiddleware(AgentMiddleware):
    tools = [my_tool]  # LLM won't know how to use it!

# GOOD - descriptive docstring
@tool
def my_tool(arg: str) -> str:
    """Process the input string and return formatted result.

    Args:
        arg: The string to process

    Returns:
        Formatted result string
    """
    return process(arg)

System Prompt Issues

17. Duplicating Built-in Tool Instructions

python

# BAD - re-explaining what middleware already covers
agent = create_deep_agent(
    system_prompt="""You have access to these tools:
    - write_todos: Create task lists
    - read_file: Read files from the filesystem
    - task: Delegate to subagents

    When using files, always use absolute paths..."""
)
# This duplicates what FilesystemMiddleware and TodoListMiddleware inject!

# GOOD - focus on domain-specific guidance
agent = create_deep_agent(
    system_prompt="""You are a code review assistant.

    Workflow:
    1. Read the files to review
    2. Create a todo list of issues found
    3. Delegate deep analysis to subagents if needed
    4. Compile findings into a report"""
)

18. Contradicting Built-in Instructions

python

# BAD - contradicting default behavior
agent = create_deep_agent(
    system_prompt="""Never use the task tool.
    Always process everything in the main thread.
    Don't use todos, just remember everything."""
)
# Fighting against the framework!

# GOOD - work with the framework
agent = create_deep_agent(
    system_prompt="""For simple tasks, handle directly.
    For complex multi-step research, use subagents.
    Track progress with todos for tasks with 3+ steps."""
)

19. Missing Stopping Criteria

python

# BAD - no guidance on when to stop
agent = create_deep_agent(
    system_prompt="Research everything about the topic thoroughly."
)
# Agent may run indefinitely!

# GOOD - define completion criteria
agent = create_deep_agent(
    system_prompt="""Research the topic with these constraints:
    - Maximum 5 web searches
    - Stop when you have 3 reliable sources
    - Limit subagent delegations to 2 parallel tasks
    - Summarize findings within 500 words"""
)

Performance Issues

20. Not Parallelizing Independent Subagents

python

# BAD - sequential subagent calls (in agent behavior)
# Agent calls: task(research topic A) → wait → task(research topic B) → wait

# GOOD - parallel subagent calls
# Agent calls in single turn:
#   task(research topic A)
#   task(research topic B)
#   task(research topic C)
# All run concurrently!

# Guide via system prompt:
agent = create_deep_agent(
    system_prompt="""When researching multiple topics,
    launch all research subagents in parallel in a single response."""
)

21. Large Files in State

python

# BAD - writing large files to StateBackend
# Agent writes 10MB log file to /output/full_log.txt
# This bloats every checkpoint!

# GOOD - use FilesystemBackend for large files or paginate
agent = create_deep_agent(
    backend=CompositeBackend(
        default=StateBackend(),  # Small files
        routes={
            "/large_files/": FilesystemBackend(root_dir="/tmp/agent"),
        },
    ),
)

22. InMemorySaver in Production

python

# BAD - ephemeral checkpointer in production
agent = create_deep_agent(
    checkpointer=InMemorySaver(),  # Lost on restart!
)

# GOOD - persistent checkpointer
from langgraph.checkpoint.postgres import PostgresSaver

agent = create_deep_agent(
    checkpointer=PostgresSaver.from_conn_string(DATABASE_URL),
)

23. Missing Recursion Awareness

python

# BAD - no guard against long-running loops
agent = create_deep_agent(
    system_prompt="Keep improving the solution until it's perfect."
)
# May hit recursion limit (default 1000)

# GOOD - explicit iteration limits
agent = create_deep_agent(
    system_prompt="""Improve the solution iteratively:
    - Maximum 3 revision cycles
    - Stop if quality score > 90%
    - Stop if no improvement after 2 iterations"""
)

Code Review Checklist

Configuration

Checkpointer provided if using
```
interrupt_on
```
Store provided if using
```
StoreBackend
```
Thread ID provided in config when using checkpointer
Backend appropriate for use case (ephemeral vs persistent)

Backends

FilesystemBackend scoped to safe
```
root_dir
```
StoreBackend has corresponding
```
store
```
parameter
CompositeBackend routes don't shadow each other unintentionally
Not expecting persistence from StateBackend across threads

Subagents

All required fields present (name, description, system_prompt, tools)
Unique subagent names
CompiledSubAgent has compatible state schema
Subagents used for complex tasks, not trivial operations

Middleware

Custom middleware added after built-in stack (expected behavior)
Tools have descriptive docstrings
Not mutating request/response objects

System Prompt

Not duplicating built-in tool instructions
Not contradicting framework defaults
Stopping criteria defined for open-ended tasks
Parallelization guidance for independent tasks

Performance

Large files routed to appropriate backend
Production uses persistent checkpointer
Recursion/iteration limits considered
Independent subagents parallelized

deepagents

NPX Install

Tags

SKILL.md Content

Deep Agents — Architecture & Review

Architecture

Deep Agents Architecture Decisions

When to Use Deep Agents

Use Deep Agents When You Need:

Consider Alternatives When:

Backend Selection

Backend Comparison

Backend Decision Tree

CompositeBackend Routing

Subagent Architecture

When to Use Subagents

Subagent Patterns

Pattern 1: Parallel Research

Pattern 2: Specialized Agents

Pattern 3: Pre-compiled Subagents

Middleware Architecture

Built-in Middleware Stack

Custom Middleware Placement

Middleware vs Tools Decision

Subagent Middleware Inheritance

Architecture Decision Checklist

Code Review

Deep Agents Code Review

Critical Issues

1. Missing Checkpointer with interrupt_on

2. Missing Store with StoreBackend

3. Missing thread_id with Checkpointer

4. Relative Paths in Filesystem Tools

5. Windows Paths in Virtual Filesystem

Backend Issues

6. StateBackend Expecting Persistence

7. FilesystemBackend Without root_dir Restriction

8. CompositeBackend Route Order Confusion

9. Expecting execute Tool Without SandboxBackend

Subagent Issues

10. Subagent Missing Required Fields

11. Subagent Name Collision

12. Overusing Subagents for Simple Tasks

13. CompiledSubAgent Without Proper State

Middleware Issues

14. Middleware Order Misunderstanding

15. Middleware Mutating Request/Response

16. Middleware Tools Without Descriptions

System Prompt Issues

17. Duplicating Built-in Tool Instructions

18. Contradicting Built-in Instructions

19. Missing Stopping Criteria

Performance Issues

20. Not Parallelizing Independent Subagents

21. Large Files in State

22. InMemorySaver in Production

23. Missing Recursion Awareness

Code Review Checklist

Configuration

Backends

Subagents

Middleware

System Prompt

Performance

See also (related skills — Code review family)