Deep Agents Code Review
Deep Agents代码审查
When reviewing Deep Agents code, check for these categories of issues.
在审查Deep Agents代码时，需检查以下几类问题。
1. Missing Checkpointer with interrupt_on
1. 使用interrupt_on但未配置Checkpointer
BAD - interrupt_on without checkpointer
BAD - interrupt_on without checkpointer
agent = create_deep_agent(
tools=[send_email],
interrupt_on={"send_email": True},
# No checkpointer! Interrupts will fail
)
agent = create_deep_agent(
tools=[send_email],
interrupt_on={"send_email": True},
# No checkpointer! Interrupts will fail
)
GOOD - checkpointer required for interrupts
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(),
)
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
2. 使用StoreBackend但未配置Store
BAD - StoreBackend without store
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
GOOD - provide store
from langgraph.store.memory import InMemoryStore
store = InMemoryStore()
agent = create_deep_agent(
backend=lambda rt: StoreBackend(rt),
store=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
3. 使用Checkpointer但未提供thread_id
BAD - no thread_id when using checkpointer
BAD - no thread_id when using checkpointer
agent = create_deep_agent(checkpointer=InMemorySaver())
agent.invoke({"messages": [...]}) # Error!
agent = create_deep_agent(checkpointer=InMemorySaver())
agent.invoke({"messages": [...]}) # Error!
GOOD - always provide thread_id
GOOD - always provide thread_id
config = {"configurable": {"thread_id": "user-123"}}
agent.invoke({"messages": [...]}, config)
config = {"configurable": {"thread_id": "user-123"}}
agent.invoke({"messages": [...]}, config)
4. Relative Paths in Filesystem Tools
4. 文件系统工具中使用相对路径
BAD - relative paths not supported
BAD - relative paths not supported
read_file(path="src/main.py")
read_file(path="./config.json")
read_file(path="src/main.py")
read_file(path="./config.json")
GOOD - absolute paths required
GOOD - absolute paths required
read_file(path="/workspace/src/main.py")
read_file(path="/config.json")
read_file(path="/workspace/src/main.py")
read_file(path="/config.json")
5. Windows Paths in Virtual Filesystem
5. 虚拟文件系统中使用Windows路径
BAD - Windows paths rejected
BAD - Windows paths rejected
read_file(path="C:\Users\file.txt")
write_file(path="D:/projects/code.py", content="...")
read_file(path="C:\Users\file.txt")
write_file(path="D:/projects/code.py", content="...")
GOOD - Unix-style virtual paths
GOOD - Unix-style virtual paths
read_file(path="/workspace/file.txt")
write_file(path="/projects/code.py", content="...")
read_file(path="/workspace/file.txt")
write_file(path="/projects/code.py", content="...")
6. StateBackend Expecting Persistence
6. 错误假设StateBackend具备跨线程持久化能力
BAD - expecting files to persist across threads
BAD - expecting files to persist across threads
agent = create_deep_agent() # Uses StateBackend by default
agent = create_deep_agent() # Uses StateBackend by default
agent.invoke({"messages": [...]}, {"configurable": {"thread_id": "a"}})
agent.invoke({"messages": [...]}, {"configurable": {"thread_id": "a"}})
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.invoke({"messages": [...]}, {"configurable": {"thread_id": "b"}})
agent.invoke({"messages": [...]}, {"configurable": {"thread_id": "b"}})
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
agent = create_deep_agent(
backend=CompositeBackend(
default=StateBackend(),
routes={"/data/": StoreBackend(store=store)},
),
store=store,
)
agent = create_deep_agent(
backend=CompositeBackend(
default=StateBackend(),
routes={"/data/": StoreBackend(store=store)},
),
store=store,
)
7. FilesystemBackend Without root_dir Restriction
7. FilesystemBackend未限制root_dir
BAD - unrestricted filesystem access
BAD - unrestricted filesystem access
agent = create_deep_agent(
backend=FilesystemBackend(root_dir="/"), # Full system access!
)
agent = create_deep_agent(
backend=FilesystemBackend(root_dir="/"), # Full system access!
)
GOOD - scope to project directory
GOOD - scope to project directory
agent = create_deep_agent(
backend=FilesystemBackend(root_dir="/home/user/project"),
)
agent = create_deep_agent(
backend=FilesystemBackend(root_dir="/home/user/project"),
)
8. CompositeBackend Route Order Confusion
8. CompositeBackend路由顺序混淆
BAD - shorter prefix shadows longer prefix
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
},
),
)
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
GOOD - CompositeBackend sorts by length automatically
But be explicit about your intent:
But be explicit about your intent:
agent = create_deep_agent(
backend=CompositeBackend(
default=StateBackend(),
routes={
"/memories/": persistent_backend,
"/workspace/": ephemeral_backend,
},
),
)
agent = create_deep_agent(
backend=CompositeBackend(
default=StateBackend(),
routes={
"/memories/": persistent_backend,
"/workspace/": ephemeral_backend,
},
),
)
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 = create_deep_agent() # Default StateBackend
agent = create_deep_agent() # Default 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 = create_deep_agent(
backend=FilesystemBackend(root_dir="/project"),
)
agent = create_deep_agent(
backend=FilesystemBackend(root_dir="/project"),
)
Agent calls execute("ls -la") → Works
Agent calls execute("ls -la") → Works
10. Subagent Missing Required Fields
10. 子代理缺失必填字段
BAD - missing required fields
BAD - missing required fields
agent = create_deep_agent(
subagents=[{
"name": "helper",
# Missing: description, system_prompt, tools
}]
)
agent = create_deep_agent(
subagents=[{
"name": "helper",
# Missing: description, system_prompt, tools
}]
)
GOOD - all required fields present
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
}]
)
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
11. 子代理名称冲突
BAD - duplicate subagent names
BAD - duplicate subagent names
agent = create_deep_agent(
subagents=[
{"name": "research", "description": "A", ...},
{"name": "research", "description": "B", ...}, # Collision!
]
)
agent = create_deep_agent(
subagents=[
{"name": "research", "description": "A", ...},
{"name": "research", "description": "B", ...}, # Collision!
]
)
GOOD - unique names
GOOD - unique names
agent = create_deep_agent(
subagents=[
{"name": "web-research", "description": "Web-based research", ...},
{"name": "doc-research", "description": "Document research", ...},
]
)
agent = create_deep_agent(
subagents=[
{"name": "web-research", "description": "Web-based research", ...},
{"name": "doc-research", "description": "Document research", ...},
]
)
12. Overusing Subagents for Simple Tasks
12. 简单任务过度使用子代理
BAD - subagent overhead for trivial task
BAD - subagent overhead for trivial task
In system prompt or agent behavior:
In system prompt or agent behavior:
"Use the task tool to check the current time"
"Delegate file reading to a subagent"
"Use the task tool to check the current time"
"Delegate file reading to a subagent"
GOOD - use subagents for complex, isolated work
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"
"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
13. CompiledSubAgent状态不兼容
BAD - subgraph with incompatible state schema
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
... 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
GOOD - ensure compatible state or use message-based interface
class CompatibleState(TypedDict):
messages: Annotated[list, add_messages]
custom_field: str
class CompatibleState(TypedDict):
messages: Annotated[list, add_messages]
custom_field: str
14. Middleware Order Misunderstanding
14. 中间件顺序理解错误
BAD - expecting custom middleware to run first
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.
Actually runs AFTER TodoList, Filesystem, SubAgent, etc.
GOOD - understand middleware runs after built-in stack
GOOD - understand middleware runs after built-in stack
Built-in order:
Built-in order:
1. TodoListMiddleware
1. TodoListMiddleware
2. FilesystemMiddleware
2. FilesystemMiddleware
3. SubAgentMiddleware
3. SubAgentMiddleware
4. SummarizationMiddleware
4. SummarizationMiddleware
5. AnthropicPromptCachingMiddleware
5. AnthropicPromptCachingMiddleware
6. PatchToolCallsMiddleware
6. PatchToolCallsMiddleware
7. YOUR MIDDLEWARE HERE
7. YOUR MIDDLEWARE HERE
8. HumanInTheLoopMiddleware (if interrupt_on set)
8. HumanInTheLoopMiddleware (if interrupt_on set)
15. Middleware Mutating Request/Response
15. 中间件修改请求/响应对象
BAD - mutating instead of returning new object
BAD - mutating instead of returning new object
class BadMiddleware(AgentMiddleware):
def transform_request(self, request):
request.messages.append(extra_message) # Mutation!
return request
class BadMiddleware(AgentMiddleware):
def transform_request(self, request):
request.messages.append(extra_message) # Mutation!
return request
GOOD - return modified copy
GOOD - return modified copy
class GoodMiddleware(AgentMiddleware):
def transform_request(self, request):
return ModelRequest(
messages=[*request.messages, extra_message],
**other_fields
)
class GoodMiddleware(AgentMiddleware):
def transform_request(self, request):
return ModelRequest(
messages=[*request.messages, extra_message],
**other_fields
)
16. Middleware Tools Without Descriptions
16. 中间件工具无描述文档
BAD - tool without docstring
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
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)
@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
17. 重复内置工具说明
BAD - re-explaining what middleware already covers
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!
This duplicates what FilesystemMiddleware and TodoListMiddleware inject!
GOOD - focus on domain-specific guidance
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"""
)
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
18. 与内置默认行为冲突
BAD - contradicting default behavior
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."""
)
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!
Fighting against the framework!
GOOD - work with 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."""
)
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
19. 缺失停止条件
BAD - no guidance on when to stop
BAD - no guidance on when to stop
agent = create_deep_agent(
system_prompt="Research everything about the topic thoroughly."
)
agent = create_deep_agent(
system_prompt="Research everything about the topic thoroughly."
)
Agent may run indefinitely!
Agent may run indefinitely!
GOOD - define completion criteria
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"""
)
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"""
)
20. Not Parallelizing Independent Subagents
20. 独立子代理未并行执行
BAD - sequential subagent calls (in agent behavior)
BAD - sequential subagent calls (in agent behavior)
Agent calls: task(research topic A) → wait → task(research topic B) → wait
Agent calls: task(research topic A) → wait → task(research topic B) → wait
GOOD - parallel subagent calls
GOOD - parallel subagent calls
Agent calls in single turn:
Agent calls in single turn:
task(research topic A)
task(research topic A)
task(research topic B)
task(research topic B)
task(research topic C)
task(research topic C)
All run concurrently!
All run concurrently!
Guide via system prompt:
Guide via system prompt:
agent = create_deep_agent(
system_prompt="""When researching multiple topics,
launch all research subagents in parallel in a single response."""
)
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
21. 状态中存储大文件
BAD - writing large files to StateBackend
BAD - writing large files to StateBackend
Agent writes 10MB log file to /output/full_log.txt
Agent writes 10MB log file to /output/full_log.txt
This bloats every checkpoint!
This bloats every checkpoint!
GOOD - use FilesystemBackend for large files or paginate
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"),
},
),
)
agent = create_deep_agent(
backend=CompositeBackend(
default=StateBackend(), # Small files
routes={
"/large_files/": FilesystemBackend(root_dir="/tmp/agent"),
},
),
)
22. InMemorySaver in Production
22. 生产环境使用InMemorySaver
BAD - ephemeral checkpointer in production
BAD - ephemeral checkpointer in production
agent = create_deep_agent(
checkpointer=InMemorySaver(), # Lost on restart!
)
agent = create_deep_agent(
checkpointer=InMemorySaver(), # Lost on restart!
)
GOOD - persistent checkpointer
GOOD - persistent checkpointer
from langgraph.checkpoint.postgres import PostgresSaver
agent = create_deep_agent(
checkpointer=PostgresSaver.from_conn_string(DATABASE_URL),
)
from langgraph.checkpoint.postgres import PostgresSaver
agent = create_deep_agent(
checkpointer=PostgresSaver.from_conn_string(DATABASE_URL),
)
23. Missing Recursion Awareness
23. 未考虑递归限制
BAD - no guard against long-running loops
BAD - no guard against long-running loops
agent = create_deep_agent(
system_prompt="Keep improving the solution until it's perfect."
)
agent = create_deep_agent(
system_prompt="Keep improving the solution until it's perfect."
)
May hit recursion limit (default 1000)
May hit recursion limit (default 1000)
GOOD - explicit iteration limits
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"""
)
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
代码审查清单