deepagents-architecture

Deep Agents 架构决策

何时使用 Deep Agents

在以下情况下使用 Deep Agents：

• 长周期任务 - 涉及数十次工具调用的复杂工作流
• 规划能力 - 在执行前分解任务
• 文件系统操作 - 读取、写入和编辑文件
• 子 Agent 委派 - 在独立的上下文窗口中隔离执行任务
• 持久化记忆 - 跨对话长期存储
• 人在回路中 - 为敏感操作设置审批关卡
• 上下文管理 - 对长对话自动生成摘要

在以下情况下考虑其他方案：

场景	替代方案	原因
单次大模型调用	直接调用 API	Deep Agents 带来的额外开销不值得
简单的 RAG 流水线	LangChain LCEL	抽象更简单
自定义图控制流	直接使用 LangGraph	灵活性更高
无需文件操作	create_react_agent	更轻量
无状态工具调用	函数调用	无需中间件

后端选择

后端对比

后端	持久性	用例	要求
StateBackend	临时（每个线程）	工作文件、临时数据	无（默认）
FilesystemBackend	磁盘	本地开发、真实文件	root_dir 路径
StoreBackend	跨线程	用户偏好、知识库	LangGraph store
CompositeBackend	混合	混合记忆模式	多个后端

后端决策树

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)

CompositeBackend 路由

将不同路径路由到不同的存储后端：

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

子 Agent 架构

何时使用子 Agent

在以下情况下使用子 Agent：

• 任务复杂、包含多个步骤，且可以独立运行
• 任务需要大量上下文，否则会使主线程臃肿
• 多个独立任务可以并行运行
• 需要隔离执行（沙盒化）
• 只关心最终结果，而不关心中间步骤

在以下情况下不要使用子 Agent：

• 任务很简单（只需少量工具调用）
• 需要查看中间推理过程
• 拆分任务会增加延迟，却没有收益
• 任务在执行过程中依赖主线程状态

子 Agent 模式

模式 1：并行研究

         ┌─────────────┐
         │  Orchestrator│
         └──────┬──────┘
    ┌──────────┼──────────┐
    ▼          ▼          ▼
┌──────┐  ┌──────┐  ┌──────┐
│Task A│  │Task B│  │Task C│
└──┬───┘  └──┬───┘  └──┬───┘
   └──────────┼──────────┘
              ▼
      ┌─────────────┐
      │  Synthesize │
      └─────────────┘

适用于：多个主题的研究、并行分析、批处理。

模式 2：专用 Agent

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

适用于：领域专长，以及为不同类型的任务使用不同的工具集。

模式 3：预编译子 Agent

from deepagents import CompiledSubAgent, create_deep_agent

# Use existing LangGraph graph as subagent
custom_graph = create_react_agent(model=..., tools=...)

agent = create_deep_agent(
    subagents=[CompiledSubAgent(
        name="custom-workflow",
        description="Runs specialized workflow",
        runnable=custom_graph
    )]
)

适用于：复用现有的 LangGraph 图、复杂的自定义工作流。

中间件架构

内置中间件栈

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 个令牌时自动生成摘要
5. AnthropicPromptCachingMiddleware - 缓存系统提示词（仅限 Anthropic）
6. PatchToolCallsMiddleware - 修复因中断而悬空的工具调用
7. HumanInTheLoopMiddleware - 暂停以等待审批（如果配置了 interrupt_on）

自定义中间件的位置

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

# Custom middleware added AFTER built-in stack
agent = create_deep_agent(middleware=[MyMiddleware()])

中间件与工具的选择

需求	使用中间件	使用工具
注入系统提示词内容	✅	❌
动态添加工具	✅	❌
转换请求/响应	✅	❌
独立功能	❌	✅
用户可调用的操作	❌	✅

子 Agent 的中间件继承

默认情况下，子 Agent 会获得自己的中间件栈：

• TodoListMiddleware
• FilesystemMiddleware（共享后端）
• SummarizationMiddleware
• AnthropicPromptCachingMiddleware
• PatchToolCallsMiddleware

在 SubAgentMiddleware 中使用 default_middleware=[]，或在每个子 Agent 的 middleware 键中覆盖。

门槛：实现前的架构决策

按顺序完成。只有当指定产物存在于设计说明、ADR 占位文件或工单中时，该步骤才算通过；仅有内部意图不计入。

1. 适配性——确认 Deep Agents 是否适用，并与其他方案进行比较（参见上方表格）。

   • **通过：**提供简短的书面理由，指出一条匹配的“在以下情况下使用 Deep Agents”条目，或一条“考虑替代方案”条目及所选替代方案。

2. 后端——根据后端决策树确定具体选择。

   • **通过：**写明后端比较表中的后端名称；如果使用 FilesystemBackend 或 CompositeBackend，还需写明 root_dir 和所有路由前缀（路径占位符也可以）。

3. 子 Agent——确定委派边界。

   • **通过：**写明“无子 Agent”并说明一句原因，或列出具名子 Agent，并为每个子 Agent 指明至少一条“何时使用子 Agent”中的原因；并行计划还需说明如何合并输出。

4. 人在回路——审批界面。

   • **通过：**明确列出使用 interrupt_on 的工具/操作，或写明“无 HITL”并用一句话说明风险接受情况。

5. 中间件——仅限自定义或内置。

   • **通过：**写明“无自定义中间件”，或列出每个自定义组件的名称，说明其在内置栈之后的位置，并关联到提示词注入、工具或请求/响应转换。

6. 上下文——长对话和大输入。

   • **通过：**说明默认摘要行为（约 85% 上下文 / 约 170k 个 Token）的计划或替代上限；并在文中说明如何通过引用、分块或等效方式处理大文件。

7. 检查点——恢复与持久性。

   • **通过：**写明图的检查点/检查点管理器方案，或写明“无”，并用一句话说明原因（例如：仅用于临时演示）。