多 Agent 协作指南：让 AI 团队不再各做各的

整理自实际运行多 Agent 系统数个月的经验。每个 pattern 都是因为「少了它就出事」才被加进来的。

有了一个 AI Agent，它很好用。于是加了第二个、第三个，事情开始失控：

• Agent A 和 Agent B 同时改了同一个文件
• 一个 API 挂了，三个 Agent 同时疯狂重试，帐单爆炸
• Sub-agent 做完事，静静消失，没人知道它到底成功还是失败

问题核心多半在协作这一层，不在 AI 本身。

下面这 5 个 pattern 都是在生产环境中反覆验证过的，能让 AI 团队真正一起工作。

---

先看全局：多 Agent 系统长什么样？

一个典型的多 Agent 系统长这样：

        🎯 指挥者 Orchestrator
                │
        ┌───────┼───────┬─────────┐
        ▼       ▼       ▼         ▼
   🔧 执行者 A  🔧 执行者 B  🔍 审查者   📁 共享文件系统
        │       │           │
        └───────┴───────────┴──→ 📁 共享文件系统

关键架构特性：

为什么是这个形状？目前大多数 AI 工具给的 sub-agent 是无状态的。它们没有持久记忆，也没有跟其他 agent 对话的能力。文件系统是唯一可靠的协作机制。

---

Pattern 1：文件白板（File Blackboard）

所有 Agent 通过文件沟通，不通过消息。文件系统就是消息汇流排。

问题

三个 Agent 需要协作，但它们：

• 没有记忆：每次被唤起都是全新的
• 彼此隔离：没有内置的通讯管道
• 随时可能消失：session 说断就断

解法：把文件系统当白板

workspace/
  status.md          ← 项目状态（只有指挥者能改）
  tasks/
    task-001.md      ← 任务信封（给执行者的指示）
    task-002.md
  artifacts/
    task-001-out.md  ← 执行者的产出
    task-002-out.md
  checkpoints/
    checkpoint.json  ← 当机复原用

存取规则

核心规则就一条：只有指挥者能写全域状态。 执行者只能写自己被指定的输出位置。

为什么是文件？

文件的好处：可检视（直接打开看）、耐久（不怕 session 断掉）、可版控（放 git 就有完整历史）。

---

Pattern 2：任务信封（Task Envelope）

不要只跟 sub-agent 说「做 X」。给它结构化的任务包。

问题

spawn 一个 sub-agent 然后说「帮忙分析这个数据」，它可能会：

• 分析错误的字段
• 跑了 50 次工具呼叫（实际上只需要 5 次）
• 做完后只回一句「分析完了」，没有要求的格式

解法：每个任务都包成信封

## 任务：analyze-q1-data
- **目标**：摘要 Q1 营收趋势
- **验收标准**：产出包含趋势方向、前 3 大驱动因素、信心等级
- **输入**：data/q1-revenue.csv（按产品线的季度营收）
- **输出位置**：artifacts/analyze-q1-data.md
- **预算**：最多 5 次工具呼叫
- **停止条件**：如果数据文件不存在或格式错误，停下并回报

信封里该有什么？

轻量版 vs 完整版

不是每个任务都需要完整信封。简单规则：

• 3 步以内就能做完 → 口头交代就好
• 有外部 API 或多文件 → 用轻量信封（目标 + 输入 + 输出）
• 高风险或高成本 → 完整信封（含预算和停止条件）

---

Pattern 3：熔断机制（Circuit Breaker）

关注每个 API 的连续失败次数。三次就断电，等一等，再试一次。

问题

Agent 打 API 碰到 429（速率限制）。它重试，再重试。同时第二个 Agent 也在重试，现在两个都在疯狂打同一个 API，让速率限制更严重。第三个 Agent 切换到备用供应商，结果备用也被打爆了。

这就是重试风暴（Retry Storm），多 Agent 系统中最快烧光预算的方式。

解法：三态熔断器

什么错误该触发熔断？

不是所有错误都一样：

实际踩过的坑

沉默的 Proxy 当机： API proxy 挂了，每个请求都回一样的 generic error。Agent 不停重试，因为错误看起来像暂时性的。

教训： 连续多次以上收到一模一样的错误，不管错误码是什么，直接触发熔断。一模一样的连续错误等于系统性故障。

---

Pattern 4：人机升级（HITL Escalation）

知道什么时候该问人，是 AI 系统最重要的能力之一。

三层升级制度

关键指标：升级率

理想的升级率是 10-15%：

• 太低（< 5%）→ AI 在做高风险的事情却没有通知，危险。
• 太高（> 30%）→ 人变成瓶颈，自动化失去意义。
• 10-15% → 大部分事情自动化，重要的事情有人把关。

升级时的信息格式

当 Agent 升级到人类时，不要只说「不确定」，给决策所需的完整信息：

## 需要决策

**情境**：正在部署新版本到生产环境
**问题**：测试全过，但有一个 warning 跟内存使用有关
**选项**：
  A. 照常部署（warning 历史上没有造成问题）
  B. 先修 warning 再部署（预估延迟 2 小时）
  C. 部署到 staging 先观察一天

**建议**：选 A，因为 [原因]
**等待回复中……**

---

Pattern 5：模型选择（Model Selection）

贵的模型用来思考，便宜的模型用来执行，反过来就是浪费钱。

二分法则

多 Agent 成本控制最核心的一条规则：

• 需要判断力（策略 / 分析 / 审查）→ 贵的模型
• 不需要判断力（写 code / 格式化 / 抓数据）→ 便宜的模型

常见配置

省钱的 80/20 法则

四个改动就能省下大部分多 Agent 成本：

1. 模型分级（贵的思考，便宜的执行）→ 影响最大
2. 传路径不传内容（让 agent 自己读文件）→ 省 token
3. 压缩已完成的阶段（只留一句话摘要）→ 省 token
4. 任务信封里设预算上限 → 避免异常值

---

总结：5 个 Pattern 的关系

这些 pattern 不是各自独立的，它们组成一个完整的运作体系：

---

开始动手

最小可行的顺序：

1. 建一个共享目录（workspace/status.md + tasks/ + artifacts/）
2. 第一个任务用信封包（不需要完整版，目标 + 输入 + 输出就够）
3. 加熔断机制（用 JSON 文件关注 API 失败次数）
4. 决定哪些操作需要人批准（先从「会影响外部系统」的开始）

这四步做完，就有一个可运作的多 Agent 协作系统了。

想要完整的 pattern 文档、代码模板和更多实战案例，整理成了开源 repo：

👉 Orchestration Playbook on GitHub

MIT 授权，欢迎取用。

延伸阅读

• 多 Agent 开发流程
• 用 AI 团队开发算法
• Claude Code + Codex 协作 playbook
• OpenClaw 多 Agent 架构
• AI Agent 自我修复

小企鹅的经验

OpenClaw 跑的 Opus / Sonnet / ChatGPT 三 agent 系统，这 5 个 pattern 是踩坑后一条一条长出来的。最初几版两个 agent 同时改同一个文件，状态就花了；API 失败时三个 agent 一起重试，帐单马上跳。后来把共享状态收敛到文件系统、任务都包成信封、API 加熔断、重要操作走人工 gate，整个系统才稳下来。模型分级（指挥用贵的，执行用便宜的）是后期才放上去，省下来的 token 比想像中多。

常见问题

Q: 什么是 AI Agent 的 Orchestration？

Orchestration 是指一个主要的 Agent（指挥者）负责分配任务、收集结果、处理失败，而其他 Agent 专心执行各自被分配的工作。就像乐团指挥一样，确保每个乐手在对的时间演奏对的乐曲。

Q: 为什么 AI Agent 不能直接互相对话？

目前大多数 AI 工具（Claude Code、Codex 等）的 Sub-agent 是无状态的。它们被生出来、执行任务、回报结果后就消失了。没有持久的记忆，也没有内置的通讯机制。所以需要通过文件系统来间接沟通。

Q: Circuit Breaker 在 AI 系统中的作用是什么？

Circuit Breaker（熔断机制）会关注 API 呼叫的连续失败次数。当连续失败达到阈值时，自动停止呼叫一段时间，避免所有 Agent 同时重试造成的『重试风暴』，这是多 Agent 系统中最烧钱的故障模式。

---

整理：Penna｜小企鹅 Penchan