bojieli/ai-agent-book/multi-agent-design

多 Agent 协作设计

何时使用

• 要搭建多 Agent 系统，或评审一个已有架构（"该用几个 Agent？谁指挥谁？"）
• 纠结"这个任务拆成多个 Agent 是否真的更好"，需要可判定的依据
• 决定 Agent 之间是共享上下文、还是各自独立上下文
• 设计 Agent 间通信机制（工具参数 / 共享文件系统 / 消息总线）与文件系统布局
• 决定角色切换应替换 system prompt，还是加载 Skill
• 多 Agent 系统出问题：文件互相覆盖、结论越传越歪、多个 Agent 不约而同做同一件事、互相扯皮、子 Agent 数量爆炸

核心原则

• 新信息判据（唯一实质判据）。 多 Agent 优于单 Agent，当且仅当协作过程引入了单个 Agent 在生成时无法获得的新信息。同一模型重新读自己的输出、多个 Agent 辩论同一段文本，都不引入新信息——等计算量下单 Agent 持平甚至更好；而用测试执行结果、渲染截图、外部工具输出来审查，则显著提升。学术研究说"多 Agent 无效"与工程实践"多 Agent 更好"并不矛盾：前者比较的是"看着同一段上下文讨论"，后者包含外部反馈环路。
• 两个维度先定，再谈实现。 维度一：上下文是否共享（继承式 vs 进程隔离式）；维度二：协作拓扑（对等 / 管理者 / 去中心化）。二者共同决定架构。
• 成本必须被收益覆盖。 并行探索与反复迭代要烧数倍乃至一个数量级的 token。收益不够大时，一个调校得当的单 Agent 更划算。
• 步骤预算不是越多越好。 单纯给 Agent 更多步骤/工具调用次数不保证性能提升——Agent 缺乏预算意识会很快"饱和"。Manager 应按子任务复杂度动态分配预算，并引导子 Agent"先规划、再实现、再测试、再改进"。
• 最强的模型给 Manager。 Plan-and-Act 的实证结论：弱规划者是系统最关键的瓶颈；规划错了，后续所有执行都建立在错误前提上。不要把资源平均分给所有 Agent。
• Agent 的故障是拜占庭式的。 它很少径直停止，而是继续给出看似可信的错误结论，且错误不会声明自己是错误。因此交叉验证与多数表决是必需手段，而非可选优化。
• 上下文隔离优先。 Manager 上下文中只放任务描述、计划、调用记录与文件索引；完整产物写入文件系统，Agent 间传递轻量路径字符串而非把内容载入上下文。
• handoff 不暴露私有轨迹。 对等移交只应传递明确的任务包和产物引用。

实践模式

1. 拓扑选择决策树

对等协作实现复杂度最低：定义好两个 Agent 的角色、通信机制和迭代终止条件即可跑起来。

2. 共享上下文 vs 不共享上下文

• 共享上下文：每阶段是独立 Agent（自己的 system prompt 与工具集），但继承前序完整轨迹。优势是信息不丢失；挑战是上下文快速膨胀，当前 Agent 容易被历史干扰。
• 不共享上下文：每个 Agent 有独立上下文与轨迹，彼此看不到对方的"思考过程"。模块化、隔离性、可扩展性更好，可真正并发；代价是信息同步与调试困难，接口规范与数据格式变得至关重要。
• 通信机制就三种，且都落在经典 IPC 范式内：工具调用参数（同步消息传递）、共享文件系统（共享内存）、消息总线（异步消息传递）。Agent 数量少且拓扑固定用点对点；数量多且需异步并行改消息总线——点对点连接数随 Agent 数平方增长且要求双方同时在线。

3. 角色切换：替换 system prompt 还是加载 Skill？

判据：角色差异主要来自知识、流程、写作风格 → 用 Skill；涉及权限、工具隔离、合规边界、需运行时强制禁止某类动作 → 用独立 Agent 或 transfer_to_agent，并在 Harness 层用代码限制。

4. 虚拟文件系统：四类区域（布局设计的检查表）

要点：隔离 scratchpad 既避免临时文件互相覆盖，也保持主上下文精简（子 Agent 只把最终产物提交到共享空间）；外部挂载需显式处理权限约束、弱一致性与"按需只读"；相当一部分并发冲突与信息泄露源于把本应隔离的区域混置。

5. 控制平面四原语

• 消息传递：无论点对点还是经总线，消息都带结构化信封（发送者 ID、目标、消息类型 task_assigned/status_update/result/terminate、JSON 负载）。统一信封使链路可追溯——这是多 Agent 调试的关键。
• 状态查询：不要用拉取式 get_status。更自然的是消息传递（问一句"进展如何"）或共享文件系统（约定 progress.md，子 Agent 每完成一项更新一次）。用 progress.md 最后修改时间超过 N 分钟无变化来判定卡住并触发超时兜底。轨迹持久化（JSONL）适合读全貌，但不宜作为主要传递方式——数万 token 还得自己提炼。
• 执行终止：优雅终止（terminate 信号，子 Agent 在安全点清理资源后 ack）为首选，强制终止为兜底。终止沿创建关系向下级联，杜绝孤儿 Agent；确需长期后台 Agent 则从新的生命周期树起步。
• 资源与调度：启动时设定步数/token 预算，超限即止；困难任务给强模型，机械任务给低成本模型；设并发上限避免耗尽 API 配额；高优先级任务到来时可抢占。

6. 管理者模式的两种协调形态

• 顺序：Manager 依次调用专门 Agent，线性控制流，适合子任务有清晰先后依赖。
• 并行：多个 Agent 同时工作，需消息总线做实时监控；Manager 在 Agent 成功/失败时做全局决策。
• 结算点定义：并行管理器要定义"第一个已验证成功"而非"第一个声称成功"——结果到达后先跑隐藏校验，通过后再用幂等的锁/事务认领胜者并广播取消其余 worker；两个几乎同时到达的成功事件不能触发两次汇总。
• 进阶做法：Manager 先把 Agent 工作流写成代码交给确定性运行时执行，自己不必每步都待在循环里。

7. 去中心化 handoff 最小协议

handoff = {task_id, sender, recipient, goal, constraints,
           accepted_facts, artifact_refs, remaining_budget, visited_agents}

接收方读任务包和引用、按需取证；预算、访问链与环检测由运行时保留，任何 Agent 不能自行删除。recipient 已在 visited_agents 中则拒绝（防 A→B→A 空转），预算耗尽则停止并上报。

8. 对等协作如何获得真正的多样性

"多个实例"不等于"多种思路"。模型、上下文、脚手架高度相似时，不同 Agent 会做出相同选择。要获得多样性需主动区分模型、上下文、工具、可见证据或职责，并让各 Agent 先独立判断、再汇总结果。

常见陷阱

• 共享文件系统并发冲突：简单冲突是同一文件后写覆盖前写（用乐观锁：读时记录版本号，写入时校验，失败则重读重做）；跨文件语义冲突更隐蔽——Agent A 重编图片编号、Agent B 引用旧编号，文件层毫无冲突但逻辑全错。并发改同一代码库时主流做法是工作副本隔离（每人独立 Git 分支/worktree），把冲突推迟到合并点。
• 错误的级联放大：Agent 间传递的是语义，每转述一次都是有损重新编码。打断手段是交叉验证——某个 Agent 以独立视角只看原始证据与最终结论是否一致，不看前序思考过程。
• 同质趋同：共因失效。同一模型、相似上下文生成的多个审核意见不能自动视为相互独立证据。需引入模型/上下文/数据来源差异，并用命名空间、资源配额和速率限制防止相同决策同时冲击共享资源。
• 互相扯皮：目标互斥时 Agent 会把对方操作理解为蓄意阻挠。运行时必须预先定义目标优先级、资源所有权和权限边界；冲突无法按可验证规则解决时暂停执行、交人工裁决。
• 循环失控：与"过早终止"相反的一极——失控 Agent 生成数千个子 Agent 浪费大量 token。对自主性强的 Agent 用独立 API key。
• 理解债与认知投降：Agent 交付越快，工程师对系统实际实现的理解落后越远；习惯了代劳就放弃独立审查。可以外包思考，不能外包理解。

配套代码

• chapter10/multi-role-transfer/ — 同一共享轨迹下"替换 system prompt"与"加载 Skill"两种角色切换的受控对比
• chapter10/staged-system-prompt/ — 分阶段切换 system prompt + 工具集的归档实验（需求→实现→评审回环）
• chapter10/book-translation/ — 管理者模式四 Agent（Glossary/Translation/Proofreading/Manager），验证 Manager 上下文不随书厚增长
• chapter10/parallel-web-research/ — Manager 动态启动 N 个同构 worker、消息总线、第一个已验证命中的级联终止与资源清理
• chapter10/autonomous-phone-registration/ — 电话 + 电脑双 Agent 点对点协作，模型自主决定是否派生 Phone Agent
• chapter10/talkact-reproduction/ — 固定拓扑快慢双 Agent 与单模型基线的对照
• chapter10/voice-werewolf/ — 多 Agent 语音狼人杀：私有/公共记忆隔离与代码驱动的只读 Judge
• chapter10/generative-agents/ — 25 角色斯坦福 AI 小镇复现，反思机制与信息扩散的对照实验

深度阅读

• book/chapter10.md「多 Agent 协作的分类框架」
• book/chapter10.md「多 Agent 何时真正优于单 Agent」
• book/chapter10.md「共享上下文的多 Agent 协作」
• book/chapter10.md「不共享上下文的多 Agent 协作」
• book/chapter10.md「多 Agent 协作的失败模式」