多智能体工作流构建完全指南

我用了12个月的单智能体来做所有事情。然后我切换到多智能体工作流，仅用了2天。

以下是我的发现

概览

2026年的多智能体系统有一个决定性的问题：如何协调那些无法在不互相“毒化”的情况下共享上下文的智能体？答案决定了你的系统是扩展还是崩溃。

本课程从基础原语开始构建你的心智模型，然后将每个概念直接关联到 Claude Code 的动态工作流目前提供的能力。

学完之后你将知道：何时使用每种编排拓扑、如何设计不会导致数据损坏的智能体间通信、哪些故障模式会杀死生产系统，以及如何使用 Claude 的原生编排栈来连接所有这些。

模块 1：多智能体系统究竟是什么

单元与运行时

智能体是单元：一个 LLM 实例，拥有自己的系统提示、工具集、记忆窗口，有时还有自己的模型。多智能体系统是运行时：协调两个或更多智能体、在它们之间路由任务、处理交接以及执行治理层的机制。

这个区别很重要，因为多智能体系统中的大多数失败都是运行时失败，而非智能体失败。单个智能体通常能正确推理。系统在协调、上下文传播和权限边界上失败。

为什么单智能体会崩溃

处理大型任务的单个智能体会遇到三个硬性限制：

• 上下文饱和：每个中间结果都会消耗上下文窗口。在大规模情况下，智能体是在堆积如山的自身历史记录上推理，而不是在真正的问题上。
• 顺序瓶颈：智能体一次只执行一步。一个本可以并行化的200文件迁移任务，串行执行需要数小时。
• 脆弱恢复：如果智能体在任务中途崩溃或偏移，整个作业就得重新开始。没有检查点。

多智能体系统通过将工作分布到隔离的智能体、将中间状态存储在智能体上下文之外、以及添加阶段级恢复点来解决这三个问题。

模块 2：Claude 的三种编排原语

在选择拓扑之前，先了解 Claude Code 提供的三种协调原语。为任务选择错误的原语是最常见的架构错误。

原语	它是什么	状态存在于何处	可重复	最大规模
Subagents（子智能体）	由主会话生成的隔离 Claude 实例，仅向编排器报告	主会话的上下文	否	每轮几个
Agent Teams（智能体团队）	由团队负责人协调的多个 Claude Code 会话，可通过邮箱直接相互发送消息	每个会话自身的上下文	否	并行会话
Dynamic Workflows（动态工作流）	Claude 编写的 JavaScript 编排脚本；一个独立的运行时在最多1000个智能体上执行它	脚本变量，位于所有上下文之外	是（保存为斜杠命令）	1000个智能体 / 16个并发

决策规则：

• 当你需要一两个孤立的调查并报告给单个会话时，使用 Subagents。
• 当团队成员需要彼此直接通信并与你通信，而不经过中央编排器时，使用 Agent Teams。
• 当编排本身应该是可重复的、计划必须超越上下文限制、或者任务需要数小时到数天才能完成时，使用 dynamic workflows。

模块 3：六种编排拓扑

你构建的每个多智能体系统都使用六种拓扑之一或它们的组合。将拓扑与问题匹配，而不是与框架匹配。

1. 顺序流水线

智能体按链式排列。智能体 A 产生输出，传递给智能体 B，再传递给智能体 C。

[Agent A: 解析] -> [Agent B: 分析] -> [Agent C: 格式化]

何时使用：工作严格依赖。每一步必须在上一步完成之后才能开始。易于调试，因为数据只有一条路径。

Claude 实现：在单个动态工作流脚本中的提示链。每个阶段运行一个子智能体，等待完成，将结果作为输入传递给下一阶段。

故障模式：延迟累积。如果智能体 B 很慢，整个流水线都会等待。不要用于具有独立并行路径的工作。

2. 协调器-工作者（中心与辐条）

一个协调器智能体接收顶层任务，将其分解为子任务，并将每个子任务路由给一个专业工作者。工作者将结果返回给协调器，协调器进行综合。

[Coordinator（协调器）]
             /      |       \
[Security（安全）]  [Perf（性能）]  [Auth（认证）]  [Coverage（覆盖）]
             \      |       /
              [Coordinator: Synthesize（合成）]

何时使用：工作可分解为不同的专业领域。路由逻辑在规划时是稳定且可知的。

Claude 实现：这是 Claude 动态工作流的默认形状。工作流脚本是协调器；子智能体是工作者。Claude 将分解逻辑写入脚本，而不是写入对话。

故障模式：协调器单点故障。如果协调器的上下文填满或偏移，整个系统都会降级。解决方法：将协调器的工作范围保持狭窄：仅分解和路由，不做领域推理。

3. 并行扇出与合并

多个智能体同时在独立子任务上工作。一个合并步骤收集并协调它们的输出。

[Orchestrator（编排器）]
   |  |  |  |
 [A][B][C][D]   <- 同时进行
   |  |  |  |
[Merge + Reconcile（合并 + 协调）]

何时使用：子任务之间没有依赖关系。经典用例：审计200个文件、查询多个数据源、同时运行五个错误分类调查。

Claude 实现：Claude 的动态工作流默认最多运行16个并发智能体。构建你的工作流阶段，使扇出任务真正独立。结果存储在脚本变量中，而不是编排器的上下文中。

性能提升：对于没有步骤依赖的任务，并行执行可将处理时间减少60-80%。

故障模式：合并逻辑是难点。如果智能体返回不一致的模式或冲突的发现，简单的合并会产生垃圾。在编写扇出之前设计输出合约。

4. 生成器-验证器

一个智能体生成输出。第二个智能体根据明确标准评估它。结果反馈给生成器。循环运行直到输出通过或达到最大迭代次数。

[Generator（生成器）] -> [Verifier（验证器）] -> 通过？ -> 完成
     ^              |
     |-- 反馈 --| 失败？ -> 迭代

何时使用：输出质量至关重要，且评估标准可以明确写下来。用于测试编写、安全发现、迁移计划等。

Claude 实现：两阶段动态工作流。阶段1并行运行生成器智能体。阶段2在每个生成器输出上运行独立的验证器智能体。只有通过验证的输出才会被合并。这是所有 Claude 动态工作流默认内置的对抗性验证。

故障模式：如果验证器的标准含糊不清，它就会变成一个橡皮图章。在工作流提示中将验证标准写成明确、可检查的规则。

5. 共享状态

智能体通过一个持久化存储进行协调，所有智能体都可以直接读写该存储。没有中央编排器来路由消息；共享存储就是协调机制。

[Agent A] ---|
[Agent B] ---|--> [Shared Store: Markdown / JSON / DB（共享存储）]
[Agent C] ---|

何时使用：智能体逐步基于彼此的发现进行构建。一个智能体发现的上下文对于处理同一问题的其他智能体立即有用。

Claude 实现：在实践中，这可以是 git 工作树中的文件系统或结构化的文档文件夹。我的生产级 Claude Code 设置就是这样用的：每个决策、每个计划、每个完成项都以 Markdown 文件形式放入结构化的文档文件夹中。下游智能体自动拾取它们。

故障模式：上下文毒化（见模块5）。一个智能体向共享存储写入了一个错误的发现。每个下游智能体都将其视为事实。错误会传播到整个系统。

6. 辩论（对抗性多智能体）

两个或更多智能体从对立立场攻击同一问题。一个裁判智能体（或编排器）协调辩论输出。

[Agent: 发现问题] -> 主张
[Agent: 反驳问题] -> 反主张
[Judge: 协调] -> 已验证的发现

何时使用：你希望发现在到达你之前经历了对抗性压力。安全审计、迁移风险评估，任何误报或漏报具有实际成本的工作。

Claude 实现：Claude 动态工作流原生包含此模式。“智能体从独立角度处理问题。其他智能体然后尝试反驳他们的发现。运行迭代直到答案收敛。”你无需显式编写辩论逻辑即可获得它；它作为工作流验证阶段的一部分运行。

模块 4：通信架构

智能体如何传递信息是大多数系统崩溃的地方。设计决策不是使用哪种消息格式，而是智能体是直接通信还是通过底层媒介通信。

直接通信与底层媒介通信

方法	工作原理	风险
智能体间直接通信	智能体 A 将其输出直接发送到智能体 B 的上下文	智能体 B 继承了智能体 A 的错误、偏见和幻觉
底层媒介中介	智能体写入共享存储（脚本变量、文件系统、数据库）。其他智能体从中读取	上下文受控；错误的写入可被隔离

来自生产系统的实用规则：

智能体不应直接相互交谈。它们应写入一个共享内存层并从中读取。规范性知识存放在一个地方。每个智能体在隔离环境中运行，具有定义的角色、定义的工具和定义的输出。

Claude 的动态工作流默认实现底层媒介中介通信。中间结果存在于脚本变量中，而不是任何智能体的上下文窗口中。这就是为什么编排脚本使用 JavaScript 在架构上很重要：脚本变量就是底层媒介。

输出合约

生产系统中的每个智能体都需要一个明确的输出合约：一个定义它必须返回什么的确切模式。没有它，合并步骤和下游智能体必须猜测接收到了什么。

// 安全审计智能体的输出合约示例
{
  "finding_id": "string",
  "file_path": "string",
  "line_number": "number",
  "severity": "critical | high | medium | low",
  "description": "string",
  "confirmed": "boolean",
  "suggested_fix": "string"
}

在工作流提示中强制执行此合约：

按此精确 JSON 模式返回结果。如果某个字段无法填充，则返回 null。不要添加模式中不存在的字段。

上下文窗口预算

每个智能体都有有限的上下文窗口。在多智能体系统中，你需要同时管理一组上下文窗口。重要的设计决策：

• 保持编排器狭窄。 编排器应分解和路由。领域推理属于专业智能体。狭窄的编排器不会用它们未使用的领域知识填充其上下文。
• 限制智能体接收的内容。 仅传递智能体特定任务所需的内容。不要将完整的文件树传递给只需要三个文件的智能体。
• 对短期记忆使用热路径限制。 在智能体循环中，仅在活动上下文中保留最近3-5次交互。将较旧的上下文丢弃到共享存储中。

模块 5：故障模式

以下是导致生产级多智能体系统死亡的五种故障。每种都是可预测和可预防的。

1. 上下文毒化

一个智能体向共享存储写入错误的输出（幻觉发现、错误模式、损坏状态）。下游智能体将其视为事实并在此基础上构建。错误在流水线中不断累积。

生产中的迹象：看似合理但无法追溯到实际文件内容的发现。在同一个文件上自信地相互矛盾的智能体。

预防：

• 在每个写入点进行模式验证。没有智能体向共享存储写入原始文本；所有内容都通过类型化模式。
• 验证器智能体在输出到达共享存储之前进行检查，而不是之后。
• 在来自一个阶段的结果播种到下一阶段之前设置人工审核关卡。

2. 级联故障

一个智能体失败。编排器没有隔离故障，而是将错误的结果路由到下游。基于失败输出构建的智能体也失败。没有适当编排的多智能体系统，已记录的故障率为41%至86.7%。

预防：

• 断路器：如果智能体返回错误或空输出，则停止该分支，不转发。
• 流水线检查点处的置信度评分：低于阈值的输出不能通过。
• 来自多个智能体的独立发现：如果一个失败，只要其他智能体独立得出了相同或不同的结论，它就不能破坏整个运行。

3. 范围蔓延

编排器的分解过于宽泛。智能体解读自己的任务时过于膨胀。一个被赋予“审计代码库”任务的智能体开始编辑它本不应触碰的文件。

预防：

• 每个智能体在其任务提示中都有一个明确的、有边界的范围：路径、文件类型、允许的操作。
• 编辑策略：只读，除非明确授予特定路径的写权限。
• Anthropic 自身的设计指南：最小足迹，仅请求必要权限，优先选择可逆操作。

4. 静默替换

智能体无法完成某一步骤（API 调用失败、文件不可读），并在 try/catch 后面悄悄插入占位数据。它报告成功。流水线将占位数据当作真实结果处理。

预防： 在 CLAUDE.md 或工作流的智能体系统提示中：

错误处理
- 永远不要用模拟数据或占位数据替换真实结果
- 如果某一步骤失败，报告错误并停止该智能体的执行
- 仅当明确记录为回退并附上原因时，才允许使用回退方案

5. 协调死锁

两个智能体互相等待。智能体 A 必须等到智能体 B 完成才能继续。智能体 B 必须等到智能体 A 写入共享存储才能开始。工作流停滞。

预防：

• 在工作流脚本中显式列出依赖图。Claude 的编排脚本将依赖关系编码在代码中，而不是隐含的对话顺序中。
• 每个智能体调用设置超时。如果智能体在 X 秒内未返回，编排器将其标记为失败并绕过它。
• 在扇出之前设计真正独立的阶段。依赖映射是模块8的预检清单。

模块 6：治理层

每个多智能体系统都需要三个结构层才能可靠工作：

层	角色	没有它会出什么问题
编排器	分解任务、路由给专家、综合	无协调；智能体重复或冲突工作
专家智能体	以领域聚焦的提示和工具执行限定范围的操作	单上下文瓶颈；无并行性
治理层	控制每个智能体可以访问什么、何时可以行动、必须记录什么	未检查的工具访问；缺失审计跟踪；未验证的输出到达下游系统

治理层是将演示系统与生产系统区分开来的东西。

治理层做什么

• 权限范围限定：每个智能体都有声明的权限集。安全审计智能体获得只读访问权。迁移智能体仅能写入特定路径。没有智能体获得超出任务所需的更广泛权限。
• 人机协同关卡：定义哪些操作在执行前需要人工批准。不可逆操作（文件删除、生产环境 API 调用、模式迁移）始终经过 HITL 关卡。
• 审计跟踪：每个智能体决策、每个操作、每个工具调用都记录智能体 ID 和导致它的推理。当出现问题时，你需要能够准确回放发生了什么。
• 爆炸半径限制：定义任何单个智能体如果行为异常所能造成的最大损害范围。文件系统写入限定在工作树内，而非仓库根目录。API 调用限制在暂存环境，除非明确授予生产环境访问权。

在 Claude 动态工作流中实施治理

治理层转化为三个具体工件：

## 智能体权限
- 读取访问：整个仓库
- 写入访问：仅限任务提示中列出的路径
- Shell 命令：仅限已批准列表中的命令
- 网络：除非任务提示指定了端点，否则禁止外部调用

## 错误处理
- 不允许静默失败
- 每个错误必须在停止前报告

## 不可逆操作策略
- 数据库写入需要在任务提示中明确批准
- 文件删除需要在任务提示中明确批准
- 没有“production: true”在任务提示中，不得调用生产 API

模块 7：生产中的五种 Claude 原生模式

以下是 Anthropic 从 Claude 生产系统中可靠运行的模式中记录的五种模式。每种模式都直接映射到一个动态工作流结构。

模式 1：提示链

将复杂任务分解为一连串更简单的提示。一个的输出成为下一个的输入。每个步骤足够小，智能体可以可靠地完成。

何时使用：任务具有清晰的连续阶段。文档处理（提取→分析→总结）、数据转换流水线、代码生成→测试→审查。

Claude 工作流形状：

阶段1：解析并提取 -> 阶段2：分析 -> 阶段3：生成报告

每个阶段是一个独立的智能体调用。阶段1的输出通过脚本变量成为阶段2的输入。

模式 2：路由

一个分类器智能体读取输入并将其路由给适当的专家。分类器不处理任务；它只路由。

何时使用：任务以异构流的形式到达。编码任务路由给代码智能体，安全问题路由给安全智能体，文档问题路由给文档智能体。

Claude 工作流形状：

[分类器智能体：读取任务，返回 agent_type]
    |
    -> 动态分发至 [安全 | 代码 | 性能 | 文档]

在工作流脚本的路由逻辑中实现分发。

模式 3：并行化

将独立的子任务扇出给多个智能体同时处理。在最后合并结果。

何时使用：子任务之间没有依赖关系。审计多个文件、搜索多个数据源、同时运行多种分析类别。

Claude 工作流形状：

// 工作流脚本结构
const files = getFilesInScope();
const results = await Promise.all(
  files.map(file => runAgent({ task: 'audit', scope: file }))
);
const merged = mergeAndDeduplicate(results);

动态工作流最多运行16个并发智能体。与顺序链式相比，Token 使用量降低60-90%，因为中间结果保留在脚本变量中。

模式 4：编排器-子智能体

编排器接收高级目标，将其分解为子任务，分发给专业子智能体，然后综合它们的输出。

何时使用：工作需要多个专业领域。一个代码库审计需要同时运行安全专家、性能专家和覆盖专家。

Claude 工作流形状：

[编排器：将目标分解为子任务]
    |
    [安全智能体] [性能智能体] [覆盖智能体]
    |                |             |
    [编排器：综合发现]

编排器的唯一工作是分解和综合。领域推理属于专家。

模式 5：评估器-优化器

生成器智能体产生输出。评估器智能体根据明确标准对其进行评分。评分加反馈返回给生成器。循环直到输出通过或达到最大迭代次数。

何时使用：输出质量至关重要，且评估标准可以写成明确规则。不得有误报的安全发现。必须经受住对抗性审查的迁移计划。必须覆盖指定边缘情况的测试用例。

Claude 工作流形状：

阶段1：生成器智能体产生初始输出
阶段2：评估器智能体根据标准模式进行评分
  - 评分 >= 阈值：转发到输出
  - 评分 < 阈值：反馈 -> 阶段1（迭代计数 + 1）
阶段3：达到最大迭代次数：标记为需要人工审核

设置硬性最大迭代次数（3-5）。没有它，循环可能会在模糊的评估标准上无限运行。

模块 8：从零开始的系统设计

在编写单个工作流提示之前，一个可重复的多智能体系统设计流程。

步骤 1：任务分解

用一句话写下顶层任务。然后列出完成它所需的所有不同操作。对于每个操作，回答两个问题：

• 该操作是否依赖于另一个操作的输出？（顺序依赖）
• 该操作能否与其他操作同时运行？（并行候选）

将顺序依赖的操作分组到阶段中。在每个阶段内，将并行候选分组到扇出中。

输出：一个带有显式依赖箭头的阶段图。

步骤 2：专家识别

对于阶段图中的每个操作，识别它所需的专家智能体。定义：

• 智能体的角色（一句话，无歧义）
• 智能体的工具访问权限（只读？写入哪些路径？哪些 shell 命令？）
• 智能体的输出合约（精确 JSON 模式）
• 智能体的故障行为（无法完成任务时做什么）

避免通用智能体。一个做所有事的“代码智能体”只是一个拥有臃肿上下文的单智能体，而不是专家。

步骤 3：通信设计

决定：底层媒介中介还是直接？对于大多数系统，答案是通过工作流的脚本变量（对于动态工作流）或共享文件系统（对于智能体团队）实现的底层媒介中介。

绘制数据流：哪个智能体写入什么、写入到哪个位置、何时写入。绘制读写图。如果任何智能体从某个位置读取，而该位置有多个其他智能体写入，则存在潜在的上下文毒化向量。在该读取之前添加一个验证步骤。

步骤 4：治理合约

在编写任何工作流提示之前，先编写 CLAUDE.md 智能体规则。这迫使你将权限、错误处理和 HITL 关卡作为明确的决策来指定，而不是事后才想到。模块6中的工件就是你的模板。

步骤 5：预检清单

在真实仓库上运行任何多智能体工作流之前：

• 在 git 工作树或功能分支中工作，而非主分支
• 每个智能体的权限范围在任务提示中明确限定
• 为每个写入共享存储的智能体定义输出合约
• 在关键路径上为每个生成器智能体设置验证器/评估器智能体
• 为所有不可逆操作定义 HITL 关卡
• 在所有评估器-优化器循环上设置最大迭代次数
• 为每个智能体定义故障行为（失败时大声报告，绝不允许静默替换）
• 在运行前检查 /usage 以了解 Token 预算

模块 9：使用 Claude 的编排栈进行构建

实用架构：动态工作流 + 智能体团队

对于大多数生产工程任务，架构结合了两个 Claude 原语：

外层：动态工作流 Claude 编写编排脚本。脚本处理分解、扇出、结果收集和阶段排序。中间状态存在于脚本变量中。工作流是可重新运行的：将其保存为斜杠命令，整个编排就变成了团队命令。

内层：专业子智能体 工作流中的每个阶段都分发专业子智能体。每个子智能体都有范围限定的系统提示（通过工作流中的任务）、特定的文件路径、定义的输出模式和故障策略。

对于需要智能体间通信的任务：智能体团队 当专家需要彼此直接发送消息（而不仅仅是向编排器报告）时，使用 Claude Code 的 Agent Teams。每个团队成员是一个完整的 Claude Code 会话，拥有自己的上下文。他们通过邮箱通信。团队负责人进行协调，但不进行微观管理。

Claude Code 的内置可观测性

/workflows 命令为你提供每个正在运行的动态工作流的实时可观测性：

• 阶段级状态（运行中、已完成、失败）
• 智能体级下钻：任务提示、当前状态、到目前为止的输出
• 能够暂停、重新启动单个智能体或停止整个工作流
• 在会话内从检查点恢复

对于智能体团队，每个团队成员会话都可以独立检查。你可以直接与团队成员交互，无需通过负责人。

模块 10：扩展与成本控制

多智能体系统的成本曲线不是线性的。成本会随智能体数量复合增长。

Token 成本架构

多智能体系统中的 Token 使用来自三个来源：

1. 编排规划：编写工作流脚本或分解任务需要前期 Token。这是每个作业固定的，而非每个智能体。
2. 智能体执行：每个智能体读取其任务、读取其输入文件、调用工具并产生输出。成本随智能体数量缩放。
3. 综合：编排器读取所有智能体输出并进行综合。成本随总输出量缩放。

动态工作流通过将中间结果保留在脚本变量中，而不是将它们全部导入编排器的上下文，从而降低了综合成本。

3-7 智能体规则

保持团队小型化。每个工作流阶段3-7个智能体。超过这个数量，创建分层结构：每组一个团队负责人，团队负责人向全局编排器报告。在单一协调层中拥有20+智能体的扁平架构具有二次通信开销和协调死锁的风险。

模块 11：决策指南：何时构建多智能体系统

最昂贵的错误是为一个智能体（或一个函数）就能处理的任务构建多智能体系统。

当以下情况时构建多智能体

• 任务具有真正独立的并行路径（并且你可以枚举它们）
• 工作超出了单个智能体的上下文窗口，并且无法在不丢失信息的情况下进行总结
• 你需要对抗性验证（经受住反驳的发现比单次通过的发现更有价值）
• 作业运行数小时到数天，需要检查点恢复
• 过程是可重复的（审计、迁移、测试生成），且编排本身应成为可复用的工件
• 不同阶段需要真正不同的专家知识或工具集

当以下情况时保持单智能体

• 任务是顺序的，没有并行性
• 工作可以轻松放入一个上下文窗口
• 协调开销将超过执行时间
• 你仍在快速构建和更改系统（多智能体架构重构成本高）

最大的单一架构错误

将所有智能体结果都路由回编排器的上下文。一旦你这样做，你就用额外的网络跳数重建了单智能体上下文瓶颈。中间状态应属于底层媒介（脚本变量、文件系统、结构化文档），而不是编排器的对话历史。

编排器的上下文应容纳计划和最终综合。其他什么都不放。

声明

本文由作者根据他的笔记、研究和个人经验撰写，并由 AI 模型（Sonnet 4.6）编辑。

缩略图来自 Pinterest，并使用 AI 修改。

• 原文链接： x.com/av1dlive/status/20...
• 登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～