CH-07 编排层：多 Agent 三层架构

Q: 什么是CH-07 编排层：多 Agent 三层架构？

图 7-1：多 Agent 三层编排

7.1 为什么需要多个 Agent

单个 Agent 处理复杂任务时面临一个根本矛盾：上下文窗口有限，但复杂任务需要的信息很多。如果一个 Agent 同时负责理解用户意图、规划任务步骤、执行研究、编写代码、生成图片、检查质量，它的系统提示词会变得极其庞大，对话历史会迅速膨胀，模型的注意力被稀释，任务质量下降。

多 Agent 架构的解决方案是分工：把复杂任务拆给多个专门化的 Agent，每个 Agent 有自己的系统提示词、工具集和上下文窗口，只关注自己负责的部分。主 Agent 负责理解意图和协调，子 Agent 负责执行具体任务，结果通过消息传递汇总。

豆包工作实现了一个三层 Agent 架构：MainAgent → OrganizeAgent → SubAgent。这个架构不是可选的高级功能，而是内置在系统提示词和工具系统中的基础能力。

7.2 三层架构

7.2.1 MainAgent：用户界面层

MainAgent 是用户直接对话的 Agent，也就是你在豆包工作聊天窗口中与之交互的"豆包"。它的职责是：

拥有完整的用户对话历史
理解用户意图
判断任务是自己完成还是委派
向用户交付最终结果
管理用户体验（回复风格、进度更新、错误沟通）

MainAgent 有一个关键约束：它默认不应该把复杂任务自己硬扛。系统提示词明确规定，复杂、多步骤、研究密集型任务应该委派给 OrganizeAgent，MainAgent 只负责"面对用户"的部分。

7.2.2 OrganizeAgent：任务编排层

OrganizeAgent 是 MainAgent 通过 create_agent 工具创建的"项目经理"。它的职责是：

接收 MainAgent 委派的完整任务描述
分解任务为子任务
创建 SubAgent 执行各个子任务
收集和整合 SubAgent 的结果
向 MainAgent 返回最终产物

OrganizeAgent 不直接执行具体工作（不写代码、不做研究、不生成图片），它只做规划、委派和整合。这类似于一个项目经理：理解需求、拆分任务、分配给专家、验收成果。

7.2.3 SubAgent：任务执行层

SubAgent 是 OrganizeAgent 创建的"专家工人"。每个 SubAgent 负责一个明确的子任务，例如：

"搜索豆包工作的官方文档并总结"
"分析 App 包中的 Helper 二进制文件"
"生成一张架构图"
"把研究结果写成 Markdown 文档"

SubAgent 有自己独立的上下文窗口，只看到与自己任务相关的信息。它可以使用工具（Bash、Read、Write、搜索等），但不能创建新的 Agent（只有 MainAgent 可以创建 OrganizeAgent，OrganizeAgent 可以创建 SubAgent）。SubAgent 完成任务后，结果返回给 OrganizeAgent，自己的上下文随即释放。

7.3 三个编排工具

多 Agent 架构通过三个工具实现：「实测」

7.3.1 create_agent

create_agent 是 MainAgent 委派任务的唯一入口。参数包括：

agent_type：只能是 "OrganizeAgent"（MainAgent 不能直接创建 SubAgent）
title：任务的简短标题（不超过 16 字）
hint：给 OrganizeAgent 的补充信息

hint 参数是一个精妙的设计。它允许 MainAgent 把多轮对话中确认的偏好、约束、关键事实一次性传给 OrganizeAgent，避免 OrganizeAgent 只看到原始用户消息而做错方向。但 hint 有一个重要限制：它只到达 OrganizeAgent，不会自动透传给 SubAgent。如果某个约束需要 SubAgent 知道，OrganizeAgent 必须在创建 SubAgent 时显式转发。

这个设计防止了上下文污染：MainAgent 的对话历史和偏好不会自动灌入每个 SubAgent，保持了 SubAgent 上下文的干净。但它也要求 OrganizeAgent 主动判断哪些信息需要转发——如果 OrganizeAgent 忘记转发关键约束，SubAgent 可能偏离方向。

7.3.2 send_message

send_message 用于向已存在的 Agent 追加消息。典型场景：

用户对前序产物提出修改要求（"这个 PPT 改成横版"）
需要补充信息（"基于刚才的 Excel 再加一个 Sheet"）
继续之前的任务（"接着做"）
模糊指代（"刚才那个"）

send_message 的关键价值是复用 Agent 上下文。每个 Agent 绑定独立的会话上下文，包括之前读取的文件、执行的命令、生成的中间产物。新建 Agent 会丢失这些上下文，而 send_message 让任务在原有上下文中继续。

7.3.3 terminate_organizer

terminate_organizer 用于终止一个正在运行的 OrganizeAgent。典型场景：

Agent 偏离了用户需求
用户改变了方向，原任务不再需要
用户要求重做
继续运行没有价值

终止后，MainAgent 可以创建新的 OrganizeAgent 处理新需求。这个工具提供了"急刹车"能力——当多 Agent 任务跑偏时，不需要等待它自然结束。

7.4 任务委派流程

图 7-2：多 Agent 任务委派序列

一个典型的多 Agent 任务执行流程如下：

用户："帮我研究豆包工作的 Harness 设计，写成蓝皮书"
    ↓
MainAgent：理解任务，判断为复杂研究任务
    ↓
MainAgent → create_agent(OrganizeAgent, hint="用五层框架...")
    ↓
OrganizeAgent：接收任务，分解为：
  1. 本地文件探索
  2. 联网调研
  3. 证据整理
  4. 正文写作
  5. 审查验证
    ↓
OrganizeAgent → create SubAgent("本地文件探索")
    ↓
SubAgent 1：执行文件分析，返回发现
    ↓
OrganizeAgent → create SubAgent("联网调研")
    ↓
SubAgent 2：执行网络搜索，返回资料
    ↓
OrganizeAgent：整合两份结果
    ↓
OrganizeAgent → create SubAgent("正文写作")
    ↓
SubAgent 3：基于整合结果写正文，返回文档
    ↓
OrganizeAgent：审查文档，返回给 MainAgent
    ↓
MainAgent：向用户交付最终产物

「推断」

在这个流程中，每个 SubAgent 只看到自己需要的信息：文件探索 SubAgent 不需要知道联网调研的结果，写作 SubAgent 只看到整合后的材料。这种信息隔离提高了每个 SubAgent 的注意力集中度。

7.5 上下文隔离与信息边界

多 Agent 架构中最微妙的设计是上下文边界：

7.5.1 MainAgent 的上下文

MainAgent 拥有完整的用户对话历史，包括所有之前的消息、工具调用和结果。这是它理解模糊指代（"刚才那个""继续"）的基础。

7.5.2 OrganizeAgent 的上下文

OrganizeAgent 的初始上下文包括：

用户的原始消息（自动透传）
MainAgent 的 hint（一次性补充信息）
自己的系统提示词（编排规则）

它不自动看到 MainAgent 的完整对话历史。如果用户在多轮对话中逐步明确了需求，MainAgent 需要通过 hint 把关键信息传递给 OrganizeAgent。

7.5.3 SubAgent 的上下文

SubAgent 的初始上下文由 OrganizeAgent 在创建时提供（subtask 描述）。它不自动看到：

MainAgent 的对话历史
MainAgent 给 OrganizeAgent 的 hint
其他 SubAgent 的结果

OrganizeAgent 负责在 subtask 中显式提供 SubAgent 需要的所有信息。这是"信息最小化"原则：每个 Agent 只知道完成自己任务所需的最少信息。

7.5.4 VM 会话共享

虽然上下文隔离，但所有 Agent 共享同一个虚拟机（VM）会话和工作目录。这意味着：

SubAgent 写入的文件，OrganizeAgent 和其他 SubAgent 可以读取
SubAgent 安装的依赖，后续 SubAgent 可以使用
工作目录中的文件是跨 Agent 的共享状态

文件系统成为 Agent 之间的"共享黑板"：SubAgent 不通过消息传递大量数据，而是把结果写入文件，其他 Agent 通过读取文件获取。这比在消息中传递大块数据更高效，也避免了上下文窗口的浪费。

7.6 与 DeerFlow sub-agent 的对照

字节开源的 DeerFlow 2.0 也实现了多 Agent 架构，其设计可以与豆包工作对照。「社区」

DeerFlow 的 sub-agent 设计特点：

按需生成：sub-agent 不是预定义的，而是根据任务需要动态生成，每个 sub-agent 有特定的角色和任务描述。
自动拾取 Skill：sub-agent 自动发现和加载相关 Skill（通过 frontmatter description），与豆包工作的 Skill 机制一致。
沙箱隔离：sub-agent 在 Docker/K8s/local 三种沙箱模式中运行，与豆包工作的 Seatbelt 沙箱理念一致但实现不同。
MCP 内置：sub-agent 可以连接 MCP 服务器获取工具能力。
IM 集成：DeerFlow 支持 Lark/Slack/Discord 作为交互界面。

豆包工作与 DeerFlow 的关键差异：

维度	豆包工作	DeerFlow 2.0
Agent 层级	固定三层（Main/Organize/Sub）	动态生成，层级灵活
沙箱	macOS Seatbelt（本地）	Docker/K8s/local（云端优先）
运行环境	用户桌面	云端容器或本地
交互界面	桌面客户端	IM 机器人 + Web
开源	否	是（74K stars）
目标用户	大众/企业	开发者/企业

两者的相似性——sub-agent 按需生成、Skill 自动拾取、沙箱隔离、MCP 内置——反映了字节内部对 Agent 架构的共识设计模式。豆包工作可以看作这些模式在桌面端的产品化实现。

7.7 多 Agent 的实际价值

多 Agent 架构不是银弹，它在以下场景中价值最大：

长链条任务：研究 → 分析 → 写作 → 审查，每个阶段需要不同的能力和上下文。单 Agent 容易在后期遗忘早期的约束，多 Agent 通过上下文重置保持专注。

并行任务：OrganizeAgent 可以同时创建多个 SubAgent 并行执行独立子任务（如同时搜索多个来源），缩短总时间。

上下文管理：复杂任务的对话历史可能超过单个上下文窗口。多 Agent 把信息分散到多个上下文中，每个 Agent 只处理相关片段。

质量控制：OrganizeAgent 作为"项目经理"审查 SubAgent 的结果，可以在整合前发现问题。写作 SubAgent 和审查 SubAgent 的分离，避免了"自己检查自己"的盲区。

但在简单任务中（"帮我改个文件名""今天天气怎么样"），多 Agent 反而增加开销。MainAgent 的系统提示词明确规定：只有复杂任务才委派，简单任务直接完成。这种"按需委派"的策略平衡了能力和效率。

7.8 错误处理与恢复

多 Agent 架构中的错误处理比单 Agent 更复杂，因为错误可能发生在任何一层。

7.8.1 SubAgent 失败

当 SubAgent 执行失败时（工具调用错误、权限不足、超时、模型返回异常），OrganizeAgent 有几种处理方式：

重试：如果错误是暂时性的（网络超时、服务不可用），OrganizeAgent 可以重新创建 SubAgent 或通过 send_message 让它重试。
降级：如果某个工具不可用，OrganizeAgent 可以让 SubAgent 换一种方式完成任务（比如搜索失败时改用网页抓取）。
上报：如果错误无法恢复，OrganizeAgent 把错误信息返回给 MainAgent，由 MainAgent 决定是否告知用户或请求更多信息。
终止：如果 SubAgent 严重偏离任务，OrganizeAgent 可以终止它并创建新的 SubAgent。

7.8.2 OrganizeAgent 失败

如果 OrganizeAgent 本身出现问题（任务分解不合理、陷入循环、上下文溢出），MainAgent 可以通过 terminate_organizer 终止它，然后创建新的 OrganizeAgent 重新开始。这是"急刹车"机制在编排层的应用。

7.8.3 部分成功

复杂任务可能部分成功——研究 SubAgent 返回了结果，但写作 SubAgent 失败了。OrganizeAgent 可以保留已完成的结果（写入文件系统），只重新执行失败的部分。这是文件系统作为"共享黑板"的另一个优势：中间结果持久化在磁盘上，不会因为某个 SubAgent 失败而丢失。

7.8.4 幂等性与重复执行

定时任务和重试机制要求任务尽可能幂等——重复执行不会产生副作用。系统提示词中对定时任务的 query 格式要求（写入"本次请求是由定时任务触发的"）有助于 SubAgent 判断当前是否为定时触发，避免重复操作。但完全的幂等性需要任务设计时保证，框架只提供机制，不强制语义。

7.9 多 Agent 的成本考量

多 Agent 不是免费的。每个 SubAgent 都有独立的系统提示词、工具定义和上下文窗口，每次工具调用都消耗 token。一个有 5 个 SubAgent 的任务，token 消耗可能是单 Agent 的 3-5 倍。

豆包含系统提示词通过以下方式控制成本：

简单任务不委派：MainAgent 直接处理简单任务，避免不必要的 Agent 创建。
上下文最小化：SubAgent 只看到自己需要的信息，不继承 MainAgent 的完整对话历史。
延迟加载工具：tool_search 机制避免所有 SubAgent 都加载完整工具 schema。
Skill 按需加载：只有匹配的 Skill 才读取完整正文。

这些设计在能力和成本之间取得平衡。对于用户来说，多 Agent 任务可能消耗更多的模型额度，但换来了更好的任务质量和更可靠的结果。

7.10 多 Agent 的典型使用模式

基于系统提示词中的编排规则和实际使用体验，可以总结出多 Agent 的几种典型模式：

7.10.1 研究-写作模式

这是最常见的模式：一个 SubAgent 负责搜索和收集资料，另一个 SubAgent 负责基于资料写作。研究 SubAgent 可以并行搜索多个来源，写作 SubAgent 只看到整合后的材料，不被搜索过程干扰。

适用场景：写报告、做调研、竞品分析、文献综述。

7.10.2 生成-审查模式

一个 SubAgent 生成内容（代码、文档、设计），另一个 SubAgent 独立审查。审查 SubAgent 没有参与生成过程，没有"自己检查自己"的盲区，可以更客观地发现问题。

适用场景：代码审查、合同审查、事实核查、质量保证。

7.10.3 管道模式

任务被拆成线性的多个阶段，每个 SubAgent 负责一个阶段，前一个的输出是后一个的输入。例如：数据收集 → 数据清洗 → 数据分析 → 可视化 → 报告生成。

适用场景：数据处理流水线、内容生产流水线、ETL 任务。

7.10.4 并行-合并模式

多个 SubAgent 并行执行独立的子任务，OrganizeAgent 收集所有结果后合并。例如同时分析多个竞争对手、同时测试多个方案、同时从多个数据源检索。

适用场景：多维度分析、批量处理、A/B 测试。

7.10.5 专家会诊模式

对于需要多领域知识的复杂问题，OrganizeAgent 创建多个不同领域的专家 SubAgent，各自从自己的专业角度分析，OrganizeAgent 综合各方观点给出结论。

适用场景：跨学科问题、复杂决策、风险评估。

7.11 编排层的架构判断

判断一：三层架构是"项目经理"模式的工程化。 MainAgent 面对用户、OrganizeAgent 规划协调、SubAgent 执行任务——这不是技术驱动的设计，而是对人类工作方式的模拟。它的优势是可解释性强（用户能理解"谁在做什么"），劣势是固定层级可能不够灵活（某些任务可能需要四层或两层）。「推断」

判断二：hint 不透传是关键的信息卫生设计。 自动透传 hint 会让每个 SubAgent 都背负 MainAgent 的全部上下文，违背分工的初衷。强制 OrganizeAgent 显式转发，虽然增加了遗漏风险，但保持了 SubAgent 上下文的干净。这是"显式优于隐式"的工程原则在 Agent 设计中的体现。「推断」

判断三：文件系统是 Agent 间的主要数据通道。 Agent 之间不通过消息传递大块数据，而是通过共享文件系统交换结果。这解释了为什么豆包工作强调文件操作工具（Read/Write/Edit/Glob/Grep）和产物交付工具（present_files）——文件系统是多 Agent 协作的"总线"。「推断」

判断四：与 DeerFlow 的一致性暗示了内部框架。 豆包工作和 DeerFlow 在 sub-agent、Skill、沙箱、MCP 四个维度上的设计高度一致，不太可能是巧合。更可能的情况是字节内部有一个共享的 Agent 框架或设计规范，豆包工作（桌面端）、DeerFlow（开源）、AgentKit（云端）都是这个框架的不同产品形态。CH-09 将详细分析这个体系内关系。「推断」

下一章将进入迭代层，分析豆包工作如何支持长时间运行的任务——任务模式、定时任务、多端同步和后台执行。

CHAPTER 08 · ZJBB-004