Deep Agents：面向复杂多步骤任务的多智能体架构

很多早期 AI Agent 的结构都比较简单：用户输入一句话，模型理解意图，必要时调用一个工具，然后把结果返回给用户。

这种模式适合问答、简单查询、轻量自动化，但一旦任务变复杂，单个 Agent 很快会遇到几个问题：

• 任务步骤太多，模型容易忘记当前做到哪一步；
• 工具调用结果越来越长，上下文窗口被快速占满；
• 不同角色的工作混在同一个对话里，互相干扰；
• 跨会话信息无法保留，每次都像从零开始；
• 长时间运行任务缺少状态管理，失败后难以恢复。

Deep Agents 要解决的正是这类问题。它建立在 LangGraph 之上，把规划、文件系统上下文、子代理和长期记忆组合成一个更适合复杂任务的 Agent 架构。

可以把 Deep Agents 理解成一种“深度工作型 Agent”：它不只回答问题，而是能把一个大目标拆成多个步骤，调度不同工具和子代理，保存中间产物，并在后续会话中继续使用已有记忆。

Deep Agents 适合解决什么问题

普通单 Agent 的工作方式更像一次性响应，而 Deep Agents 更像一个带工作台、任务清单和长期记忆的执行系统。

典型结构如下：

flowchart LR
    U[用户任务] --> A[主 Agent]

    A --> P[任务规划<br/>write_todos]
    A --> F[文件系统上下文<br/>ls / read_file / write_file / edit_file]
    A --> T[外部工具<br/>搜索 / 代码执行 / API 调用]
    A --> S[子代理<br/>task]
    A --> M[(长期记忆<br/>Memory Store)]

    S --> S1[调研代理]
    S --> S2[编码代理]
    S --> S3[校验代理]

    S1 --> A
    S2 --> A
    S3 --> A

    A --> R[最终结果]

这个结构里，主 Agent 不再承担所有细节工作，而是负责统筹：拆任务、决定调用哪个工具、把中间结果写入文件、分配子任务，再把结果汇总起来。

Deep Agents 通常适合这几类任务。

反过来，如果任务只是“查一个字段”“回答一个简单问题”“调用一次接口”，Deep Agents 可能会显得过重。复杂架构的价值在于管理复杂度，简单任务没必要引入额外调度层。

核心机制一：任务规划与 write_todos

复杂任务最怕的是“做到一半失去方向”。模型可能一开始知道目标，但经过几轮工具调用后，上下文里塞满搜索结果、日志、代码片段，原始目标反而变得不清晰。

Deep Agents 内置规划能力，典型工具是 write_todos。它的作用不是简单列清单，而是让 Agent 把任务状态显式写下来：

• 当前任务拆成哪些子步骤；
• 哪些步骤已经完成；
• 哪些步骤正在进行；
• 发现新信息后是否需要调整计划；
• 最终结果还缺哪些证据或产物。

执行过程可以表示成这样：

flowchart TD
    A[接收复杂任务] --> B[拆分任务清单]
    B --> C[执行一个子任务]
    C --> D{是否得到新信息}
    D -- 是 --> E[更新任务清单]
    D -- 否 --> F[标记当前步骤状态]
    E --> G{是否还有未完成步骤}
    F --> G
    G -- 有 --> C
    G -- 无 --> H[汇总结果并输出]

规划机制解决的是 Agent 的“过程控制”问题。没有任务清单时，模型只能靠上下文隐式记住进度；任务清单写出来之后，主 Agent 可以不断对照目标和当前状态，降低遗漏步骤的概率。

一个技术方案生成任务，可以被拆成类似结构：

目标：设计一个企业内部知识库问答 Agent

TODO:
- [x] 明确业务目标和用户范围
- [x] 梳理数据来源：文档、网页、数据库、工单
- [ ] 设计检索增强生成流程
- [ ] 设计权限控制方案
- [ ] 设计评测指标
- [ ] 输出最终架构和实施步骤

当 Agent 搜索到新的约束，比如“知识库必须区分部门权限”，任务清单就需要新增或调整权限相关步骤，而不是继续按旧计划执行。

核心机制二：文件系统上下文管理

大模型的上下文窗口再大，也不适合把所有资料都塞进去。复杂任务往往会产生大量中间内容：

• 搜索结果；
• 需求说明；
• 接口文档；
• 代码文件；
• 测试日志；
• 草稿版本；
• 对比表格；
• 最终报告。

如果这些内容全部留在对话历史里，模型很快会遇到两个问题：一是上下文成本变高，二是关键信息被大量无关内容淹没。

Deep Agents 使用文件系统工具来管理上下文，常见工具包括：

这相当于给 Agent 配了一个工作目录。大块信息不必一直放在对话窗口里，而是写入文件；需要使用时，再读取相关文件或片段。

flowchart LR
    A[工具调用结果] --> B{内容是否很长}
    B -- 否 --> C[直接放入当前上下文]
    B -- 是 --> D[写入文件系统]
    D --> E[记录文件路径和摘要]
    E --> F[后续按需读取]
    F --> G[继续推理或生成]

这种方式有几个直接好处：

1. 上下文更干净
   对话里只保留当前推理需要的信息，大量背景资料放到文件中。

2. 中间产物可复用
   调研结果、代码草稿、测试报告可以被后续步骤继续读取和修改。

3. 更适合长任务
   一个任务运行几十轮时，文件系统比纯对话历史更适合承载状态。

4. 工具结果长度更灵活
   搜索、日志、代码生成这类工具经常返回大量文本，直接写文件比塞进上下文更稳定。

例如，一个调研型 Agent 可以这样组织工作区：

workspace/
├── brief.md                 # 用户目标和约束
├── sources/
│   ├── langgraph-notes.md   # LangGraph 资料摘要
│   ├── memory-store.md      # 长期记忆资料摘要
│   └── cli-usage.md         # CLI 用法摘要
├── drafts/
│   └── architecture.md      # 架构设计草稿
└── final-report.md          # 最终报告

主 Agent 不需要每次都记住所有内容，只要知道“资料在哪个文件里、什么时候读回来”。

核心机制三：子代理协作

单个 Agent 可以调用很多工具，但这不等于它适合承担所有角色。复杂任务里，不同子任务往往需要不同的提示词、工具集合和工作上下文。

例如生成一个项目方案时，至少可能有四种角色：

Deep Agents 通过 task 工具调用子代理。子代理拥有自己的上下文，完成任务后只把结果返回给主 Agent。这样可以避免所有细节都堆在主 Agent 的上下文里。

sequenceDiagram
    participant U as 用户
    participant M as 主 Agent
    participant R as 调研子代理
    participant C as 编码子代理
    participant V as 校验子代理
    participant FS as 文件系统

    U->>M: 提交复杂任务
    M->>FS: 写入任务说明和计划
    M->>R: 分配资料调研任务
    R-->>M: 返回资料摘要和出处
    M->>C: 分配代码生成任务
    C->>FS: 写入代码文件
    C-->>M: 返回实现说明
    M->>V: 分配检查任务
    V->>FS: 读取代码和方案
    V-->>M: 返回问题清单
    M->>FS: 修改最终结果
    M-->>U: 输出完整交付物

子代理的关键价值是上下文隔离。调研代理看到的是资料搜索任务，编码代理看到的是实现任务，校验代理看到的是检查标准。它们不需要共享所有对话细节，只需要把经过整理的结果交回主 Agent。

这种模式尤其适合企业级 Agent，因为企业任务常常不是单一能力问题，而是多种能力组合问题。

核心机制四：长期记忆

短期上下文解决的是“当前任务怎么做”，长期记忆解决的是“跨会话还记得什么”。

如果 Agent 每次对话都从零开始，用户就要反复说明偏好、项目背景和约束条件。例如：

• 用户喜欢输出 Markdown 表格；
• 某个项目固定使用 FastAPI；
• 某个团队代码规范要求函数必须带类型标注；
• 某个客户不能使用外部云服务；
• 上次方案里已经否定过某个技术选型。

Deep Agents 可以结合 LangGraph 的 Memory Store 保存和检索持久信息。长期记忆通常不应该简单保存完整聊天记录，而是保存结构化、可复用的信息。

flowchart TD
    A[一次对话产生信息] --> B{是否值得长期保存}
    B -- 否 --> C[只保留在当前上下文]
    B -- 是 --> D[抽取为记忆条目]
    D --> E[(Memory Store)]
    E --> F[后续会话检索]
    F --> G[影响计划、工具调用和输出格式]

更合理的记忆条目通常长这样：

{
  "user_id": "u_123",
  "namespace": "project-preferences",
  "memory": {
    "project": "internal-knowledge-agent",
    "backend_framework": "FastAPI",
    "database": "PostgreSQL",
    "output_style": "prefer tables and diagrams",
    "security_constraint": "do not send private documents to external services"
  }
}

长期记忆不是越多越好。保存太多无关信息会增加检索噪声，还可能带来隐私和权限问题。更好的做法是只保存稳定、可复用、对未来任务有帮助的信息。

Deep Agents SDK 与 CLI

Deep Agents 主要有两种使用方式：SDK 和 CLI。

SDK 更适合构建自己的 Agent 系统，比如企业知识库助手、研发自动化平台、代码生成服务。CLI 更适合在本地或沙盒环境中让 Agent 直接操作项目文件、执行命令、记住个人偏好。

CLI 的价值不只是“一次性执行命令”。如果它接入记忆能力，就可以逐渐学习你的工作习惯，例如常用目录结构、代码风格、测试命令和项目约束。

用 SDK 搭一个简化版 Deep Agent

安装方式以实际版本为准，常见 Python 项目可以按这种思路准备环境：

pip install -U deepagents langchain langgraph

一个最小化 Agent 通常包含三部分：

1. 给主 Agent 的说明；
2. 主 Agent 可以调用的工具；
3. 可选的子代理配置。

示例代码如下：

from deepagents import create_deep_agent


def search_docs(query: str) -> str:
    """搜索内部文档或外部资料。"""
    # 真实项目里可以接搜索引擎、向量数据库或内部知识库
    return f"Search results for: {query}"


def run_tests(command: str) -> str:
    """执行测试命令。"""
    # 真实项目里需要放到沙盒环境执行，避免危险命令
    return f"Test command executed: {command}"


instructions = """
你是一个软件研发助手，负责把复杂研发任务拆成步骤完成。

工作规则：
- 先制定任务清单，再执行具体步骤。
- 调研资料要整理成摘要，不要直接堆长文本。
- 生成代码后要调用测试工具进行检查。
- 遇到不确定信息时，标记假设和风险。
"""

agent = create_deep_agent(
    tools=[search_docs, run_tests],
    instructions=instructions,
)

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "设计一个支持权限控制的企业知识库问答系统，并给出后端模块划分。",
            }
        ]
    }
)

print(result["messages"][-1].content)

加入子代理后，可以把不同任务交给专门角色：

from deepagents import create_deep_agent


def search_docs(query: str) -> str:
    return f"Search results for: {query}"


def run_tests(command: str) -> str:
    return f"Test command executed: {command}"


subagents = [
    {
        "name": "researcher",
        "description": "负责资料调研、方案比较和证据整理。",
        "prompt": """
你是调研子代理。
只负责收集资料、整理关键结论和列出依据。
不要生成最终方案。
""",
        "tools": [search_docs],
    },
    {
        "name": "reviewer",
        "description": "负责检查方案中的风险、遗漏和不一致。",
        "prompt": """
你是校验子代理。
检查输出是否存在安全、权限、成本、可维护性方面的问题。
返回问题清单和修改建议。
""",
        "tools": [run_tests],
    },
]

agent = create_deep_agent(
    tools=[search_docs, run_tests],
    instructions="""
你是主 Agent，负责规划任务、分配子任务、汇总结果并输出最终方案。
需要调研时调用 researcher，需要检查时调用 reviewer。
""",
    subagents=subagents,
)

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "为一个企业知识库问答系统设计 Deep Agents 架构。",
            }
        ]
    }
)

print(result["messages"][-1].content)

真实系统里，工具函数一般不会这么简单。常见工具包括：

• 搜索内部知识库；
• 读写项目文件；
• 执行单元测试；
• 调用工单系统；
• 查询数据库；
• 访问 API；
• 生成和修改配置文件。

工具越多，越需要清晰的权限边界和调用约束，否则 Agent 可能会在错误时机调用错误工具。

CLI 更适合哪些任务

Deep Agents CLI 适合把 Agent 当成本地工作助手使用，尤其是代码和项目文件相关任务。

可以用类似方式启动或检查命令：

deepagents --help

适合 CLI 的任务包括：

但 CLI 也要特别注意安全边界。让 Agent 操作本地文件和执行命令时，最好放在受控目录或沙盒环境中，避免误删文件、泄露密钥或执行高风险命令。

什么时候不该用 Deep Agents

Deep Agents 能处理复杂任务，但不是所有 Agent 都需要做成多智能体架构。

一个实用判断标准是：如果任务可以在一次模型调用或少量固定步骤内完成，就不必上 Deep Agents；如果任务需要计划、迭代、保存中间状态、跨角色协作，Deep Agents 才开始体现价值。

落地时容易踩的坑

1. 把长期记忆当成聊天记录仓库

长期记忆应该保存稳定事实和用户偏好，而不是把所有对话原样塞进去。聊天记录太多会让检索结果变乱，还可能保存敏感信息。

更好的方式是先抽取，再保存：

原始对话：
“这个项目还是用 FastAPI 吧，数据库继续 PostgreSQL，之前说过不要用外部 SaaS。”

适合保存的记忆：
- 项目 backend_framework = FastAPI
- 项目 database = PostgreSQL
- 安全约束：禁止使用外部 SaaS

2. 子代理太多，主 Agent 反而难调度

子代理不是越多越好。角色划分应该围绕任务边界，而不是为了“多智能体”而拆分。

比较合理的拆分方式是：

• 调研；
• 编码；
• 校验；
• 总结。

如果每个小步骤都拆一个子代理，主 Agent 会花大量精力在调度上，整体链路变慢，也更难排查问题。

3. 文件系统缺少目录规范

Agent 可以写文件，不代表它会自然写得有条理。需要提前规定工作区结构，例如：

workspace/
├── input/       # 用户输入和原始资料
├── notes/       # 调研摘要和中间笔记
├── drafts/      # 草稿
├── src/         # 生成的代码
├── tests/       # 测试文件
└── output/      # 最终交付物

目录规则越清晰，Agent 越容易在长任务中找到正确文件。

4. 工具权限没有分级

有些工具是安全的，例如读取文档、搜索资料；有些工具风险更高，例如写文件、删文件、执行 shell 命令、访问生产数据库。

建议按风险分级：

5. 没有评测闭环

复杂 Agent 不能只靠肉眼观察效果。至少要准备一组固定任务，评估它是否真的能稳定完成多步骤工作。

可以从这些指标开始：

Deep Agents 的架构价值

Deep Agents 的核心价值不在于“多了几个工具”，而在于把复杂 Agent 需要的几个关键能力组合成统一架构：

• 用任务规划管理多步骤执行；
• 用文件系统承载长上下文和中间产物；
• 用子代理隔离不同角色的工作；
• 用长期记忆保存跨会话知识；
• 用 LangGraph 提供状态化、可编排的执行基础。

当 AI Agent 从简单问答走向长期任务、企业流程和研发自动化时，单 Agent 对话模式很容易被上下文、状态和协作复杂度拖垮。Deep Agents 把这些问题前置到架构层解决，让 Agent 更接近一个能持续工作的执行系统，而不是一次性响应工具。