Deep Agents Code Review
When reviewing Deep Agents code, check for these categories of issues.
Anti-confabulation (gate 0 — runs before every other gate)
Before issuing any finding — flag a bug, anti-pattern, or improvement — you MUST echo the exact artifact you are judging, quoted from a source you read in this turn:
- The code finding: its
file:lineplus the cited code, read freshly now. - The agent code under review: the
create_deep_agent, backend, subagent, or middleware snippet your finding depends on, quoted from the file you just read.
The artifact is the only source of truth. Never infer what you are reviewing from the branch name, the working directory, surrounding files, or recollection. If your mental model differs from the freshly read source, the source wins. A finding issued without a same-turn echo of its target is invalid — emit the echo first, or do not emit the finding.
This gate exists because an LLM under contextual priming will confidently flag code that is not in the file. It runs before the gates below.
Review gates (evidence-bound)
Run these steps in order before and while you write findings. Skipping a step is a failed review.
- Locate — Enumerate call sites in scope (
create_deep_agent,CompiledSubAgent,CompositeBackend, custombackend=,interrupt_on,checkpointer,store). Pass: You list each relevant file path and line number (or a grep/search result that proves where the code lives). - Anchor — For each suspected issue, tie it to quoted or line-referenced code from those files, not to imports or names alone. Pass: Every finding includes evidence (
path:lineplus a short quote or “absent parameter” note showing the gap). - Classify — Map each anchored issue to one category below (Critical → Performance) and a severity. Pass: The category label matches what the cited code actually does or omits.
- Runtime claims — If you say something will error, fail at runtime, or leak data, Pass: The cited snippet shows the exact API combo (e.g.
interrupt_onset with nocheckpointerin the same construction path), or you state uncertain and what would confirm it.
If you cannot satisfy step 1, stop and say what file or search is missing instead of inferring issues from memory.
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
See references/checklist.md for the full per-area checklist (Configuration, Backends, Subagents, Middleware, System Prompt, Performance). Run it after the Review gates and the numbered issue catalogue above.
