如何构建多智能体工作流（完整指南）

我用了 12 个月的单智能体完成所有工作，然后切换为多智能体工作流仅 2 天后——这是我发现的一切

概述

2026 年的多智能体系统面临一个核心问题：如何在智能体之间无法共享上下文（否则会相互污染）的情况下进行协调？答案决定了你的系统是能扩展还是会崩溃。本课程从底层原语开始构建你的心智模型，然后将每个概念直接关联到 Claude Code 的动态工作流当前能提供的能力。学完本课程你会了解：每种编排拓扑的适用场景、如何设计不导致污染的智能体间通信、哪些故障模式会杀死生产系统，以及如何利用 Claude 的本地编排栈来连接这一切。

模块 1：多智能体系统到底是什么

单元与运行时

智能体是单元：一个 LLM 实例，拥有自己的系统提示、工具集、记忆窗口，有时还有独立的模型。多智能体系统是运行时：协调两个或多个智能体的机制、任务路由、交接处理以及执行治理层。这个区别很重要，因为大多数多智能体系统的故障是运行时故障，而非智能体故障。单个智能体通常能正确推理。系统失败的地方在于协调、上下文传播和权限边界。

为什么单智能体会失效

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

• 上下文饱和： 每个中间结果都会消耗上下文窗口。规模大时，智能体是在处理自己历史的堆积，而非实际问题。
• 序列瓶颈： 智能体一次只执行一个步骤。一个可以并行处理的 200 个文件的迁移任务只能串行执行数小时。
• 脆弱的恢复： 如果智能体中途崩溃或偏航，整个任务必须重新开始。没有检查点。

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

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

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

决策规则：

• 当需要一个或两个独立的调查任务向单个会话报告时，使用子智能体。
• 当团队成员需要直接相互通信以及与您通信，而不经过中央编排器时，使用智能体团队。
• 当编排本身应该可重复、计划必须超越上下文限制、或者任务需要数小时到数天完成时，使用动态工作流。

模块 3：六种编排拓扑

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

1. 顺序管道（Sequential Pipeline）

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

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

适用场景： 工作严格依赖。每个步骤必须在前一个步骤完成后才能开始。调试容易，因为数据只有一条路径。

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

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

2. 协调器-工作者（中心辐射式）

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

[协调器]
 / | \
[安全] [性能] [认证] [覆盖率]
 \ | /
[协调器: 合成]

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

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

故障模式： 协调器是单点故障。如果协调器的上下文填满或偏航，整个系统会退化。解决方法：让协调器的职责保持狭窄——仅负责分解和路由，不做领域推理。

3. 并行扇出与合并

多个智能体同时处理独立的子任务。一个合并步骤收集并调和它们的输出。

[编排器]
 |     |
[A][B][C][D]  <- 同时执行
 |     |
[合并 + 调和]

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

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

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

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

4. 生成器-验证器

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

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

适用场景： 输出质量至关重要，且评估标准可以明确写出。如：测试编写、安全发现、迁移计划。

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

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

5. 共享状态

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

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

适用场景： 智能体逐步建立彼此的发现。一个智能体发现的上下文对其他处理相同问题的智能体立即有用。

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

故障模式： 上下文污染（在模块 5 中讨论）。一个智能体向共享存储写入不良发现。所有下游智能体将其视为事实。错误在整个系统中传播。

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

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

[Agent: 找出问题] -> 主张
[Agent: 反驳问题] -> 反主张
[裁判: 调和] -> 经过验证的发现

适用场景： 你希望发现能在到达你之前经受住对抗压力。如：安全审计、迁移风险评估、任何误报或漏报代价高昂的工作。

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

模块 4：通信架构

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

直接通信 vs. 底层媒介通信

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

智能体不应直接相互通信。它们应该写入一个共享记忆层并从其中读取。规范知识位于一个位置。每个智能体在隔离状态下运行，拥有明确定义的角色、工具和输出。

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 动态工作流中实现治理

治理层转化为…