Back to Details

deepagents

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Deep Agents — Architecture & Review

Deep Agents — 架构设计与代码审查

ConcernSection
Architectural decisions, framework choice, subagent/middleware designArchitecture
Reviewing existing Deep Agents code for bugs and anti-patternsCode Review
关注点章节
架构决策、框架选择、子Agent/中间件设计架构设计
审查现有Deep Agents代码中的缺陷与反模式代码审查

Architecture

架构设计

Deep Agents Architecture Decisions

Deep Agents架构决策

When to Use Deep Agents

何时使用Deep Agents

Use Deep Agents When You Need:

适合使用Deep Agents的场景：

  • 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
  • 长周期任务 - 涉及数十次工具调用的复杂工作流
  • 规划能力需求 - 执行前的任务分解
  • 文件系统操作 - 文件的读取、写入与编辑
  • 子Agent委托 - 独立任务执行，拥有单独的上下文窗口
  • 持久化内存 - 跨对话的长期存储
  • 人机协作 - 敏感操作的审批环节
  • 上下文管理 - 长对话的自动摘要

Consider Alternatives When:

考虑替代方案的场景：

ScenarioAlternativeWhy
Single LLM callDirect API callDeep Agents overhead not justified
Simple RAG pipelineLangChain LCELSimpler abstraction
Custom graph control flowLangGraph directlyMore flexibility
No file operations needed
create_react_agent
Lighter weight
Stateless tool useFunction callingNo middleware needed
场景替代方案原因
单次LLM调用直接API调用Deep Agents的开销无必要
简单RAG流水线LangChain LCEL更简洁的抽象层
自定义图控制流直接使用LangGraph更高的灵活性
无需文件操作
create_react_agent
更轻量化
无状态工具调用函数调用无需中间件

Backend Selection

后端选择

Backend Comparison

后端对比

BackendPersistenceUse CaseRequires
StateBackend
Ephemeral (per-thread)Working files, temp dataNothing (default)
FilesystemBackend
DiskLocal development, real files
root_dir
path
StoreBackend
Cross-threadUser preferences, knowledge basesLangGraph 
store
CompositeBackend
MixedHybrid memory patternsMultiple backends
后端持久化特性使用场景依赖条件
StateBackend
临时存储（单线程）工作文件、临时数据无（默认选项）
FilesystemBackend
磁盘存储本地开发、真实文件操作
root_dir
路径
StoreBackend
跨线程共享用户偏好、知识库LangGraph 
store
CompositeBackend
混合存储混合内存模式多个后端

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)
需要真实磁盘访问？
├─ 是 → FilesystemBackend(root_dir="/path")
└─ 否
   └─ 需要跨对话持久化？
      ├─ 是 → 需要临时+持久混合存储？
      │  ├─ 是 → CompositeBackend
      │  └─ 否 → StoreBackend
      └─ 否 → StateBackend (默认)

CompositeBackend Routing

CompositeBackend路由配置

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
        },
    ),
)
将不同路径路由至不同存储后端：
python
from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend

agent = create_deep_agent(
    backend=CompositeBackend(
        default=StateBackend(),  # 工作文件（临时存储）
        routes={
            "/memories/": StoreBackend(store=store),    # 持久化存储
            "/preferences/": StoreBackend(store=store), # 持久化存储
        },
    ),
)

Subagent Architecture

子Agent架构

When to Use Subagents

何时使用子Agent

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
适合使用子Agent的场景：
  • 任务复杂、多步骤且可独立执行
  • 任务需要大量上下文，会导致主线程上下文膨胀
  • 多个独立任务可并行执行
  • 需要隔离执行环境（沙箱）
  • 仅关注最终结果，无需中间步骤
不适合使用子Agent的场景：
  • 任务简单（仅需少量工具调用）
  • 需要查看中间推理过程
  • 拆分任务会增加延迟且无收益
  • 任务执行过程中依赖主线程状态

Subagent Patterns

子Agent模式

Pattern 1: Parallel Research

模式1：并行研究

         ┌─────────────┐
         │  Orchestrator│
         └──────┬──────┘
    ┌──────────┼──────────┐
    ▼          ▼          ▼
┌──────┐  ┌──────┐  ┌──────┐
│Task A│  │Task B│  │Task C│
└──┬───┘  └──┬───┘  └──┬───┘
   └──────────┼──────────┘
              ▼
      ┌─────────────┐
      │  Synthesize │
      └─────────────┘
Best for: Research on multiple topics, parallel analysis, batch processing.
         ┌─────────────┐
         │  编排器│
         └──────┬──────┘
    ┌──────────┼──────────┐
    ▼          ▼          ▼
┌──────┐  ┌──────┐  ┌──────┐
│任务A│  │任务B│  │任务C│
└──┬───┘  └──┬───┘  └──┬───┘
   └──────────┼──────────┘
              ▼
      ┌─────────────┐
      │  结果合成 │
      └─────────────┘
最佳适用场景：多主题研究、并行分析、批量处理。

Pattern 2: Specialized Agents

模式2：专业化Agent

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.
python
research_agent = {
    "name": "researcher",
    "description": "复杂主题深度研究",
    "system_prompt": "你是一名专业研究员...",
    "tools": [web_search, document_reader],
}

coder_agent = {
    "name": "coder",
    "description": "编写与审查代码",
    "system_prompt": "你是一名资深程序员...",
    "tools": [code_executor, linter],
}

agent = create_deep_agent(subagents=[research_agent, coder_agent])
最佳适用场景：领域专业技能需求、不同任务类型对应不同工具集。

Pattern 3: Pre-compiled Subagents

模式3：预编译子Agent

python
from deepagents import CompiledSubAgent, create_deep_agent
python
from deepagents import CompiledSubAgent, create_deep_agent

Use existing LangGraph graph as subagent

将现有LangGraph图作为子Agent使用

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.
custom_graph = create_react_agent(model=..., tools=...)
agent = create_deep_agent( subagents=[CompiledSubAgent( name="custom-workflow", description="执行专业化工作流", runnable=custom_graph )] )

最佳适用场景：复用现有LangGraph图、复杂自定义工作流。

Middleware Architecture

中间件架构

Built-in Middleware Stack

内置中间件栈

Deep Agents applies middleware in this order:
  1. TodoListMiddleware - Task planning with 
    write_todos
    /
    read_todos
  2. FilesystemMiddleware - File ops: 
    ls
    , 
    read_file
    , 
    write_file
    , 
    edit_file
    , 
    glob
    , 
    grep
    , 
    execute
  3. SubAgentMiddleware - Delegation via 
    task
    tool
  4. SummarizationMiddleware - Auto-summarizes at ~85% context or 170k tokens
  5. AnthropicPromptCachingMiddleware - Caches system prompts (Anthropic only)
  6. PatchToolCallsMiddleware - Fixes dangling tool calls from interruptions
  7. HumanInTheLoopMiddleware - Pauses for approval (if 
    interrupt_on
    configured)
Deep Agents按以下顺序应用中间件：
  1. TodoListMiddleware - 通过
    write_todos
    /
    read_todos
    实现任务规划
  2. FilesystemMiddleware - 文件操作：
    ls
    , 
    read_file
    , 
    write_file
    , 
    edit_file
    , 
    glob
    , 
    grep
    , 
    execute
  3. SubAgentMiddleware - 通过
    task
    工具实现任务委托
  4. SummarizationMiddleware - 上下文占比约85%或达到170k tokens时自动摘要
  5. AnthropicPromptCachingMiddleware - 缓存系统提示词（仅支持Anthropic）
  6. PatchToolCallsMiddleware - 修复中断导致的未完成工具调用
  7. HumanInTheLoopMiddleware - 触发审批暂停（若配置
    interrupt_on
    ）

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
python
from langchain.agents.middleware import AgentMiddleware

class MyMiddleware(AgentMiddleware):
    tools = [my_custom_tool]

    def transform_request(self, request):
        # 修改系统提示词、注入上下文
        return request

    def transform_response(self, response):
        # 后处理、日志记录、过滤
        return response

Custom middleware added AFTER built-in stack

自定义中间件添加至内置栈之后

agent = create_deep_agent(middleware=[MyMiddleware()])
undefined
agent = create_deep_agent(middleware=[MyMiddleware()])
undefined

Middleware vs Tools Decision

中间件与工具的选择决策

NeedUse MiddlewareUse Tools
Inject system prompt content✅❌
Add tools dynamically✅❌
Transform requests/responses✅❌
Standalone capability❌✅
User-invokable action❌✅
需求使用中间件使用工具
注入系统提示词内容✅❌
动态添加工具✅❌
转换请求/响应✅❌
独立功能❌✅
用户可调用操作❌✅

Subagent Middleware Inheritance

子Agent中间件继承

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.
子Agent默认拥有独立的中间件栈：
  • TodoListMiddleware
  • FilesystemMiddleware（共享后端）
  • SummarizationMiddleware
  • AnthropicPromptCachingMiddleware
  • PatchToolCallsMiddleware
可通过SubAgentMiddleware的
default_middleware=[]
或子Agent的
middleware
字段覆盖默认配置。

Architecture Decision Checklist

架构决策检查清单

Before implementing:
  1. Is Deep Agents the right tool? (vs LangGraph directly, vs simpler agent)
  2. Backend strategy chosen?
    • Ephemeral only → StateBackend (default)
    • Need disk access → FilesystemBackend
    • Need cross-thread persistence → StoreBackend or CompositeBackend
  3. Subagent strategy defined?
    • Which tasks benefit from isolation?
    • Custom subagents with specialized tools/prompts?
    • Parallel execution opportunities identified?
  4. Human-in-the-loop points defined?
    • Which tools need approval?
    • Approval flow (approve/edit/reject)?
  5. Custom middleware needed?
    • System prompt injection?
    • Request/response transformation?
  6. Context management considered?
    • Long conversations → summarization triggers
    • Large file handling → use references
  7. Checkpointing strategy? (for persistence/resume)
实现前需确认：
  1. Deep Agents是否为合适工具？（对比直接使用LangGraph或更简单的Agent）
  2. 是否已选择后端策略？
    • 仅临时存储 → StateBackend（默认）
    • 需要磁盘访问 → FilesystemBackend
    • 需要跨线程持久化 → StoreBackend或CompositeBackend
  3. 是否已定义子Agent策略？
    • 哪些任务可通过隔离执行获益？
    • 是否需要带专用工具/提示词的自定义子Agent？
    • 是否已识别并行执行的机会？
  4. 是否已定义人机协作节点？
    • 哪些工具需要审批？
    • 审批流程（批准/编辑/拒绝）？
  5. 是否需要自定义中间件？
    • 是否需要注入系统提示词？
    • 是否需要转换请求/响应？
  6. 是否已考虑上下文管理？
    • 长对话 → 摘要触发机制
    • 大文件处理 → 使用引用方式
  7. 是否已制定检查点策略？（用于持久化/恢复）

Code Review

代码审查

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

错误示例 - 使用interrupt_on但未配置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}, # 无checkpointer！中断将失败 )

GOOD - checkpointer required for interrupts

正确示例 - 中断功能需要checkpointer

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

错误示例 - StoreBackend未配置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), # 无store！运行时将抛出ValueError )

GOOD - provide store

正确示例 - 提供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

错误示例 - 使用checkpointer但未提供thread_id

agent = create_deep_agent(checkpointer=InMemorySaver()) agent.invoke({"messages": [...]}) # Error!
agent = create_deep_agent(checkpointer=InMemorySaver()) agent.invoke({"messages": [...]}) # 报错！

GOOD - always provide thread_id

正确示例 - 必须提供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")
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

错误示例 - Windows路径将被拒绝

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

正确示例 - 使用类Unix虚拟路径

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
agent = create_deep_agent() # 默认使用StateBackend

Thread 1

线程1

agent.invoke({"messages": [...]}, {"configurable": {"thread_id": "a"}})
agent.invoke({"messages": [...]}, {"configurable": {"thread_id": "a"}})

Agent writes to /data/report.txt

Agent写入/data/report.txt

Thread 2 - file won't exist!

线程2 - 文件不存在！

agent.invoke({"messages": [...]}, {"configurable": {"thread_id": "b"}})
agent.invoke({"messages": [...]}, {"configurable": {"thread_id": "b"}})

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

Agent尝试读取/data/report.txt - 未找到

GOOD - use StoreBackend or CompositeBackend for cross-thread persistence

正确示例 - 使用StoreBackend或CompositeBackend实现跨线程持久化

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! )
agent = create_deep_agent( backend=FilesystemBackend(root_dir="/"), # 全系统访问权限！ )

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 }, ), )
agent = create_deep_agent( backend=CompositeBackend( default=StateBackend(), routes={ "/mem/": backend_a, # 会匹配/mem/long-term/路径！ "/mem/long-term/": backend_b, # 永远不会被命中 }, ), )

GOOD - CompositeBackend sorts by length automatically

正确示例 - CompositeBackend会自动按长度排序

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

错误示例 - StateBackend不支持execute工具

agent = create_deep_agent() # Default StateBackend
agent = create_deep_agent() # 默认StateBackend

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

Agent调用execute("ls -la") → 错误：不支持

GOOD - use FilesystemBackend for shell execution

正确示例 - 使用FilesystemBackend执行shell命令

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调用execute("ls -la") → 正常工作

undefined
undefined

Subagent Issues

子Agent相关问题

10. Subagent Missing Required Fields

10. 子Agent缺少必填字段

python
undefined
python
undefined

BAD - missing required fields

错误示例 - 缺少必填字段

agent = create_deep_agent( subagents=[{ "name": "helper", # Missing: description, system_prompt, tools }] )
agent = create_deep_agent( subagents=[{ "name": "helper", # 缺失：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": "通用辅助工具，处理各类杂项任务", "system_prompt": "你是一名乐于助人的助手。", "tools": [], # 可以为空但必须存在 }] )
undefined

11. Subagent Name Collision

11. 子Agent名称冲突

python
undefined
python
undefined

BAD - duplicate subagent names

错误示例 - 子Agent名称重复

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", ...}, # 名称冲突！ ] )

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": "基于网页的研究", ...}, {"name": "doc-research", "description": "文档研究", ...}, ] )
undefined

12. Overusing Subagents for Simple Tasks

12. 简单任务过度使用子Agent

python
undefined
python
undefined

BAD - subagent overhead for trivial task

错误示例 - 简单任务使用子Agent造成开销

In system prompt or agent behavior:

在系统提示词或Agent行为中：

"Use the task tool to check the current time" "Delegate file reading to a subagent"
"使用task工具查看当前时间" "将文件读取任务委托给子Agent"

GOOD - use subagents for complex, isolated work

正确示例 - 子Agent用于复杂、隔离的工作

"Use the task tool for multi-step research that requires many searches" "Delegate the full analysis workflow to a subagent"
undefined
"针对需要多次搜索的多步骤研究，使用task工具" "将完整分析工作流委托给子Agent"
undefined

13. CompiledSubAgent Without Proper State

13. CompiledSubAgent状态不兼容

python
undefined
python
undefined

BAD - subgraph with incompatible state schema

错误示例 - 子图状态 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 # 缺少messages字段！
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="自定义工作流", runnable=subgraph, # 状态不匹配！ )] )

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): # 期望在所有内置中间件之前执行 return request
agent = create_deep_agent(middleware=[PreProcessMiddleware()])

Actually runs AFTER TodoList, Filesystem, SubAgent, etc.

实际在TodoList、Filesystem、SubAgent等内置中间件之后执行

GOOD - understand middleware runs after built-in stack

正确示例 - 明确自定义中间件在内置栈之后执行

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. 你的自定义中间件

8. HumanInTheLoopMiddleware (if interrupt_on set)

8. HumanInTheLoopMiddleware（若配置interrupt_on）

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
class BadMiddleware(AgentMiddleware): def transform_request(self, request): request.messages.append(extra_message) # 直接修改！ 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无法知晓如何使用！

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: """处理输入字符串并返回格式化结果。
参数:
    arg: 待处理的字符串

返回:
    格式化后的结果字符串
"""
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="""你可使用以下工具: - write_todos: 创建任务列表 - read_file: 从文件系统读取文件 - task: 委托给子Agent
使用文件时，请始终使用绝对路径..."""
)

This duplicates what FilesystemMiddleware and TodoListMiddleware inject!

这与FilesystemMiddleware和TodoListMiddleware注入的内容重复！

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="""你是一名代码审查助手。
工作流:
1. 读取待审查文件
2. 创建问题清单
3. 必要时将深度分析委托给子Agent
4. 将发现的问题整理成报告"""
)
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.""" )
agent = create_deep_agent( system_prompt="""永远不要使用task工具。 所有任务都在主线程中处理。 不要使用todos，自行记住所有内容。""" )

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="""简单任务直接处理。 复杂多步骤研究使用子Agent。 步骤≥3的任务使用todos跟踪进度。""" )
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 = create_deep_agent( system_prompt="全面研究该主题的所有内容。" )

Agent may run indefinitely!

Agent可能无限运行！

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="""按以下约束研究主题: - 最多执行5次网页搜索 - 获取3个可靠来源后停止 - 子Agent并行任务不超过2个 - 研究结果摘要不超过500字""" )
undefined

Performance Issues

性能相关问题

20. Not Parallelizing Independent Subagents

20. 独立子Agent未并行执行

python
undefined
python
undefined

BAD - sequential subagent calls (in agent behavior)

错误示例 - 子Agent串行调用（Agent行为中）

Agent calls: task(research topic A) → wait → task(research topic B) → wait

Agent调用: task(研究主题A) → 等待 → task(研究主题B) → 等待

GOOD - parallel subagent calls

正确示例 - 子Agent并行调用

Agent calls in single turn:

Agent在单轮对话中调用:

task(research topic A)

task(研究主题A)

task(research topic B)

task(研究主题B)

task(research topic C)

task(研究主题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="""研究多个主题时， 在单轮响应中并行启动所有研究子Agent。""" )
undefined

21. Large Files in State

21. 大文件存储在StateBackend

python
undefined
python
undefined

BAD - writing large files to StateBackend

错误示例 - 将大文件写入StateBackend

Agent writes 10MB log file to /output/full_log.txt

Agent将10MB日志文件写入/output/full_log.txt

This bloats every checkpoint!

这会导致每个检查点体积膨胀！

GOOD - use FilesystemBackend for large files or paginate

正确示例 - 使用FilesystemBackend存储大文件或分页处理

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(), # 小文件存储 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! )
agent = create_deep_agent( checkpointer=InMemorySaver(), # 重启后数据丢失！ )

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." )
agent = create_deep_agent( system_prompt="不断优化方案直至完美。" )

May hit recursion limit (default 1000)

可能触发递归限制（默认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="""迭代优化方案: - 最多3次修订循环 - 质量评分>90%时停止 - 连续2次迭代无改进时停止""" )
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

子Agent

  • 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
  • 所有必填字段完整（name、description、system_prompt、tools）
  • 子Agent名称唯一
  • CompiledSubAgent状态schema兼容
  • 子Agent用于复杂任务而非简单操作

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
<!-- cross-ref:start -->
  • 大文件已路由至合适后端
  • 生产环境使用持久化检查点
  • 已考虑递归/迭代限制
  • 独立子Agent已并行执行
<!-- cross-ref:start -->

See also (related skills — Code review family)

相关技能（代码审查系列）

If your issue relates to:
  • CodeRabbit-powered review (default) — check 
    code-review
    if appropriate.
  • auto-apply CodeRabbit review comments — check 
    autofix
    if appropriate.
  • Python + pytest review (type safety, async, fixtures) — check 
    python-code-review
    if appropriate.
  • Rust source review — check 
    rust-code-review
    if appropriate.
  • Rust test review — check 
    rust-testing-code-review
    if appropriate.
  • tokio async review — check 
    tokio-async-code-review
    if appropriate.
  • Rust FFI review — check 
    ffi-code-review
    if appropriate.
  • SQLAlchemy 2.0 review — check 
    sqlalchemy-code-review
    if appropriate.
<!-- cross-ref:end -->
若你的问题涉及：
  • CodeRabbit驱动的审查（默认） — 适用
    code-review
    技能。
  • 自动应用CodeRabbit审查意见 — 适用
    autofix
    技能。
  • Python + pytest审查（类型安全、异步、fixtures） — 适用
    python-code-review
    技能。
  • Rust源码审查 — 适用
    rust-code-review
    技能。
  • Rust测试用例审查 — 适用
    rust-testing-code-review
    技能。
  • tokio异步代码审查 — 适用
    tokio-async-code-review
    技能。
  • Rust FFI审查 — 适用
    ffi-code-review
    技能。
  • SQLAlchemy 2.0审查 — 适用
    sqlalchemy-code-review
    技能。
<!-- cross-ref:end -->