# Multi Agent Design

设计或评审多 Agent 系统、判断该用单 Agent 还是多 Agent 时使用, , 选择对等/管理者/去中心化协作拓扑、决定上下文是否共享、设计 Agent...

- Repository: https://github.com/bojieli/ai-agent-book (56844 stars)
- Category: AI and agents
- License: Apache-2.0
- Last updated: 2026-10-08
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add bojieli/ai-agent-book --skill multi-agent-design -g -a claude-code -y`
Codex: `npx skills add bojieli/ai-agent-book --skill multi-agent-design -g -a codex -y`
Cursor: `npx skills add bojieli/ai-agent-book --skill multi-agent-design -g -a cursor -y`
Gemini CLI: `npx skills add bojieli/ai-agent-book --skill multi-agent-design -g -a gemini-cli -y`

## Description

设计或评审多 Agent 系统、判断该用单 Agent 还是多 Agent 时使用, , 选择对等/管理者/去中心化协作拓扑、决定上下文是否共享、设计 Agent 间通信与共享文件系统、诊断多 Agent 失败模式（并发冲突、错误级联、同质趋同、互相扯皮、循环失控）。覆盖协作架构选择依据、多 Agent 优于单 Agent 的新信息判据、控制平面四原语与虚拟文件系统四类区域的设计检查表。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 多 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. 拓扑选择决策树
| 任务特征 | 选择 |
|---|---|
| 2-3 个角色，需要互相反馈、多轮迭代提质 | 对等协作（起草者/评论者、提议者/审核者） |
| 子任务多、需要动态调度、子任务间有复杂依赖 | 管理者模式（Manager 规划 + 子 Agent 执行） |
| 需职责对等的角色自主决定与谁沟通，或管理者不能成为单点故障 | 去中心化模式（handoff / 消息池订阅） |
| 开放搜索空间，需要广覆盖与多样化发现路径 | 多 Agent 并行（用更高 token 预算换覆盖） |

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

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

The rest: https://github.com/bojieli/ai-agent-book/blob/HEAD/skills/multi-agent-design/SKILL.md