Deep Agents Code Review

Deep Agents代码审查

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

在审查Deep Agents代码时，需检查以下几类问题。

Critical Issues

严重问题

1. Missing Checkpointer with interrupt_on

1. 使用interrupt_on但未配置Checkpointer

python

undefined

python

undefined

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(), )

undefined

from langgraph.checkpoint.memory import InMemorySaver

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

undefined

2. Missing Store with StoreBackend

2. 使用StoreBackend但未配置Store

python

undefined

python

undefined

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 )

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, )

undefined

from langgraph.store.memory import InMemoryStore

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

undefined

3. Missing thread_id with Checkpointer

3. 使用Checkpointer但未提供thread_id

python

undefined

python

undefined

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)

undefined

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

undefined

4. Relative Paths in Filesystem Tools

4. 文件系统工具中使用相对路径

python

undefined

python

undefined

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")

undefined

read_file(path="/workspace/src/main.py") read_file(path="/config.json")

undefined

5. Windows Paths in Virtual Filesystem

5. 虚拟文件系统中使用Windows路径

python

undefined

python

undefined

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="...")

undefined

read_file(path="/workspace/file.txt") write_file(path="/projects/code.py", content="...")

undefined

Backend Issues

后端问题

6. StateBackend Expecting Persistence

6. 错误假设StateBackend具备跨线程持久化能力

python

undefined

python

undefined

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, )

undefined

agent = create_deep_agent( backend=CompositeBackend( default=StateBackend(), routes={"/data/": StoreBackend(store=store)}, ), store=store, )

undefined

7. FilesystemBackend Without root_dir Restriction

7. FilesystemBackend未限制root_dir

python

undefined

python

undefined

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"), )

undefined

agent = create_deep_agent( backend=FilesystemBackend(root_dir="/home/user/project"), )

undefined

8. CompositeBackend Route Order Confusion

8. CompositeBackend路由顺序混淆

python

undefined

python

undefined

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, }, ), )

undefined

agent = create_deep_agent( backend=CompositeBackend( default=StateBackend(), routes={ "/memories/": persistent_backend, "/workspace/": ephemeral_backend, }, ), )

undefined

9. Expecting execute Tool Without SandboxBackend

9. 未使用SandboxBackend却期望execute工具生效

python

undefined

python

undefined

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

undefined

undefined

Subagent Issues

子代理问题

10. Subagent Missing Required Fields

10. 子代理缺失必填字段

python

undefined

python

undefined

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 }] )

undefined

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 }] )

undefined

11. Subagent Name Collision

11. 子代理名称冲突

python

undefined

python

undefined

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", ...}, ] )

undefined

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

undefined

12. Overusing Subagents for Simple Tasks

12. 简单任务过度使用子代理

python

undefined

python

undefined

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"

undefined

"Use the task tool for multi-step research that requires many searches" "Delegate the full analysis workflow to a subagent"

undefined

13. CompiledSubAgent Without Proper State

13. CompiledSubAgent状态不兼容

python

undefined

python

undefined

BAD - subgraph with incompatible state schema

from langgraph.graph import StateGraph

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

sub_builder = StateGraph(CustomState)

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! )] )

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

undefined

class CompatibleState(TypedDict): messages: Annotated[list, add_messages] custom_field: str

undefined

Middleware Issues

中间件问题

14. Middleware Order Misunderstanding

14. 中间件顺序理解错误

python

undefined

python

undefined

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()])

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)

undefined

undefined

15. Middleware Mutating Request/Response

15. 中间件修改请求/响应对象

python

undefined

python

undefined

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 )

undefined

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

undefined

16. Middleware Tools Without Descriptions

16. 中间件工具无描述文档

python

undefined

python

undefined

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!

@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)

undefined

@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)

undefined

System Prompt Issues

系统提示词问题

17. Duplicating Built-in Tool Instructions

17. 重复内置工具说明

python

undefined

python

undefined

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..."""

)

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"""

)

undefined

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"""

)

undefined

18. Contradicting Built-in Instructions

18. 与内置默认行为冲突

python

undefined

python

undefined

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.""" )

undefined

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.""" )

undefined

19. Missing Stopping Criteria

19. 缺失停止条件

python

undefined

python

undefined

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""" )

undefined

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""" )

undefined

Performance Issues

性能问题

20. Not Parallelizing Independent Subagents

20. 独立子代理未并行执行

python

undefined

python

undefined

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.""" )

undefined

agent = create_deep_agent( system_prompt="""When researching multiple topics, launch all research subagents in parallel in a single response.""" )

undefined

21. Large Files in State

21. 状态中存储大文件

python

undefined

python

undefined

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"), }, ), )

undefined

agent = create_deep_agent( backend=CompositeBackend( default=StateBackend(), # Small files routes={ "/large_files/": FilesystemBackend(root_dir="/tmp/agent"), }, ), )

undefined

22. InMemorySaver in Production

22. 生产环境使用InMemorySaver

python

undefined

python

undefined

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), )

undefined

from langgraph.checkpoint.postgres import PostgresSaver

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

undefined

23. Missing Recursion Awareness

23. 未考虑递归限制

python

undefined

python

undefined

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""" )

undefined

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""" )

undefined

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)

使用
```
interrupt_on
```
时已提供Checkpointer
使用
```
StoreBackend
```
时已提供Store
使用checkpointer时已在配置中提供Thread ID
后端类型与用例匹配（临时存储 vs 持久存储）

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

FilesystemBackend已限制安全的
```
root_dir
```
StoreBackend已配置对应的
```
store
```
参数
CompositeBackend路由未意外覆盖彼此
未假设StateBackend具备跨线程持久化能力

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

所有必填字段已填充（名称、描述、系统提示词、工具）
子代理名称唯一
CompiledSubAgent状态模式兼容
子代理仅用于复杂任务，而非简单操作

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

大文件已路由至合适后端
生产环境使用持久化checkpointer
已考虑递归/迭代限制
独立子代理已并行执行

deepagents-code-review

Original

Translation

Deep Agents Code Review

Deep Agents代码审查

Critical Issues

严重问题

1. Missing Checkpointer with interrupt_on

1. 使用interrupt_on但未配置Checkpointer

BAD - interrupt_on without checkpointer

BAD - interrupt_on without checkpointer

GOOD - checkpointer required for interrupts

GOOD - checkpointer required for interrupts

2. Missing Store with StoreBackend

2. 使用StoreBackend但未配置Store

BAD - StoreBackend without store

BAD - StoreBackend without store

GOOD - provide store

GOOD - provide store

3. Missing thread_id with Checkpointer

3. 使用Checkpointer但未提供thread_id

BAD - no thread_id when using checkpointer

BAD - no thread_id when using checkpointer

GOOD - always provide thread_id

GOOD - always provide thread_id

4. Relative Paths in Filesystem Tools

4. 文件系统工具中使用相对路径

BAD - relative paths not supported

BAD - relative paths not supported

GOOD - absolute paths required

GOOD - absolute paths required

5. Windows Paths in Virtual Filesystem

5. 虚拟文件系统中使用Windows路径

BAD - Windows paths rejected

BAD - Windows paths rejected

GOOD - Unix-style virtual paths

GOOD - Unix-style virtual paths

Backend Issues

后端问题

6. StateBackend Expecting Persistence

6. 错误假设StateBackend具备跨线程持久化能力

BAD - expecting files to persist across threads

BAD - expecting files to persist across threads

Thread 1

Thread 1

Agent writes to /data/report.txt

Agent writes to /data/report.txt

Thread 2 - file won't exist!

Thread 2 - file won't exist!

Agent tries to read /data/report.txt - NOT FOUND

Agent tries to read /data/report.txt - NOT FOUND

GOOD - use StoreBackend or CompositeBackend for cross-thread persistence

GOOD - use StoreBackend or CompositeBackend for cross-thread persistence

7. FilesystemBackend Without root_dir Restriction

7. FilesystemBackend未限制root_dir

BAD - unrestricted filesystem access

BAD - unrestricted filesystem access

GOOD - scope to project directory

GOOD - scope to project directory

8. CompositeBackend Route Order Confusion

8. CompositeBackend路由顺序混淆

BAD - shorter prefix shadows longer prefix

BAD - shorter prefix shadows longer prefix

GOOD - CompositeBackend sorts by length automatically

GOOD - CompositeBackend sorts by length automatically

But be explicit about your intent:

But be explicit about your intent:

9. Expecting execute Tool Without SandboxBackend

9. 未使用SandboxBackend却期望execute工具生效

BAD - execute tool won't work with StateBackend

BAD - execute tool won't work with StateBackend

Agent calls execute("ls -la") → Error: not supported

Agent calls execute("ls -la") → Error: not supported

GOOD - use FilesystemBackend for shell execution

GOOD - use FilesystemBackend for shell execution

Agent calls execute("ls -la") → Works

Agent calls execute("ls -la") → Works

Subagent Issues

子代理问题

10. Subagent Missing Required Fields