tools-only Deep Agents Code Review
When reviewing Deep Agents code, check for these categories of issues.
Critical Issues
1. Missing Checkpointer with interrupt_on
# 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
# 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
# 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
# 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
# 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
# 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
# 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
# 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
# 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
# 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
# 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
# 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
# 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
# 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
# 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
# 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
# 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
# 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
# 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
# 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
# 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
# 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
# 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
storeparameter - 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