name: building-multiagent-systems description: 此技能应用于设计或实现由多个AI智能体协调完成任务的多智能体系统。触发词包括：“多智能体”、“编排器”、“子智能体”、“协调”、“委托”、“并行智能体”、“顺序流水线”、“扇出”、“映射归约”、“生成智能体”、“智能体层级”。
构建多智能体、使用工具的系统
概述
为多智能体系统提供的全面架构模式，其中AI智能体通过协调使用工具来完成复杂任务。语言无关，适用于TypeScript、Python、Go、Rust及其他环境。
发现性问题（必填）
在架构任何系统之前，请回答以下六个强制性问题：
- 起点 - 全新项目、添加到现有系统，还是修复当前实现？
- 主要用例 - 并行工作、顺序流水线、递归委托、对等协作、工作队列，还是其他？
- 规模预期 - 小型（2-5个智能体）、中型（10-50个），还是大型（100+）？
- 状态要求 - 无状态运行、基于会话，还是跨崩溃持久化？
- 工具协调 - 独立智能体、共享只读资源、写入协调，还是受速率限制的API？
- 现有约束 - 语言、框架、性能需求、合规性要求？
基础架构
四层堆栈
每个智能体都遵循四层架构，以确保可测试性、安全性和模块化：
| 层级 | 名称 | 职责 |
|---|---|---|
| 1 | 推理层 (LLM) | 计划、批判、决定调用哪些工具 |
| 2 | 编排层 | 验证、路由、执行策略、生成子智能体 |
| 3 | 工具总线 | 模式验证、工具执行协调 |
| 4 | 确定性适配器 | 文件I/O、API、shell命令、数据库访问 |
关键规则：第1层以下的所有内容必须是确定性的。工具中不得调用LLM。
详细实现及代码示例请参见 references/four-layer-architecture.md。
基础模式
| 模式 | 目的 |
|---|---|
| 事件溯源 | 所有状态变更作为事件，用于审计追踪和重放 |
| 层级化ID | 编码委托层级（例如 session.1.2），用于成本聚合 |
| 智能体状态机 | 显式状态（空闲 → 思考 → 工具执行 → 停止）及无效转换错误 |
| 通信 | 状态变更使用EventEmitter，结果收集使用Promise |
七种协调模式
根据发现性问题答案选择：
| 模式 | 用例 | 权衡 |
|---|---|---|
| 扇出/扇入 | 并行独立工作 | 快速但成本高；注意孤儿任务 |
| 顺序流水线 | 多阶段转换 | 瓶颈在最慢阶段 |
| 递归委托 | 分层任务分解 | 必须添加深度限制 |
| 工作窃取队列 | 1000+任务负载均衡 | 无内置优先级 |
| 映射归约 | 成本优化 | 廉价映射（$0.01），智能归约（$0.15） |
| 对等协作 | LLM委员会减少偏见 | 昂贵（3N+1次调用），缓慢 |
| MAKER | 零错误任务（10万+步骤） | 5倍成本但~0%错误率 |
详细实现请参见 references/coordination-patterns.md。
模式选择指南
| 需求 | 推荐模式 |
|---|---|
| 并行独立任务 | 扇出/扇入 |
| 每个阶段依赖前序阶段 | 顺序流水线 |
| 复杂任务分解 | 递归委托 |
| 大批量处理 | 工作窃取队列 |
| 成本敏感分析 | 映射归约 |
| 需要多样化视角 | 对等协作 |
| 零错误容忍 | MAKER |
MAKER模式（零错误）
适用于需要10万+步骤且零错误容忍的任务（医疗、金融、法律领域）：
- 极端分解 - 递归分解直到每个子任务<100步
- 微智能体 - 单一工具、专注专长、廉价模型
- 多智能体投票 - 每个子任务N次并行尝试，多数共识
- 错误纠正 - 确定性验证 + 带失败上下文的重试
成本对比：与传统方法成本相同，零错误 vs. 10+错误。
完整实现及医疗诊断示例请参见 references/maker-pattern.md。
工具协调
| 机制 | 目的 |
|---|---|
| 权限继承 | 子智能体继承父智能体权限子集（无法升级） |
| 资源锁定 | 共享资源的获取/释放模式 |
| 速率限制 | 跨所有智能体的令牌桶算法 |
| 结果缓存 | 缓存只读、幂等、昂贵的操作 |
子智能体即工具模式：将专用智能体包装为父智能体可调用的工具，提供可组合的抽象和自然的生命周期管理。
实现请参见 references/tool-coordination.md。
关键生命周期：级联停止
“始终在停止自身之前停止所有子智能体。”这可以防止孤儿智能体。
1. 获取所有子智能体
2. 并行停止所有子智能体
3. 停止自身
4. 取消进行中的工作
5. 刷新事件
如果暂停/恢复不可用，则实现手动检查点：保存智能体状态（消息、上下文、工具结果），稍后恢复。
生产环境加固
| 关注点 | 解决方案 |
|---|---|
| 孤儿检测 | 每30秒心跳监控 |
| 成本追踪 | 跨智能体树的层级聚合 |
| 会话持久化 | 项目级任务存储，用于跨会话工作 |
| 检查点 | 在10+工具调用、$1.00成本或5分钟过去后保存 |
| 自修改安全 | 影响范围评估、分支隔离、测试优先 |
详细实现请参见 references/production-hardening.md。
真实世界示例：代码审查系统
使用扇出/扇入的拉取请求编排器：
- 并行生成四个专业审查员（安全、性能、风格、测试）
- 安全和测试使用智能模型（Sonnet）；风格和性能使用快速模型（Haiku）
- 每个审查员有2分钟超时
- 无论部分失败如何，结果都会聚合
- 按审查员追踪成本
- 完成后通过级联停止所有智能体干净地停止
执行清单
指导多智能体系统实现时：
- 询问发现性问题 - 在架构前理解需求
- 评估错误容忍度 - 零错误 → MAKER；可接受一些错误 → 更简单的模式
- 建立四层架构 - 推理、编排、工具总线、适配器
- 设计模式优先的工具 - 在实现前定义类型化契约
- 定义确定性边界 - 第3-4层中无LLM
- 选择编排模型 - YOLO、安全第一或混合
- 选择协调模式 - 扇出、流水线、委托、队列、映射归约、对等或MAKER
- 设计工具协调 - 权限继承、锁定、速率限制
- 实现级联清理 - 始终在父智能体之前停止子智能体
- 添加监控和成本追踪 - 跨智能体树的层级聚合
- 考虑自修改安全 - 如果智能体可以修改代码，则添加安全协议
常见陷阱
| 陷阱 | 影响 |
|---|---|
| 缺少四层架构 | 不可测试、不安全、难以调试 |
| 工具中调用LLM（第3-4层） | 非确定性，无法单元测试 |
| 无模式优先工具设计 | 子智能体无法发现工具 |
| 缺少级联停止 | 孤儿智能体消耗资源 |
| 无权限继承 | 子智能体可以升级权限 |
| 无超时设置 | 无限期挂起等待子智能体 |
| 无限制并发 | 过多智能体导致资源耗尽 |
| 忽略成本追踪 | 预算意外 |
| 无部分失败处理 | 一个失败级联到所有智能体 |
| 未持久化状态 | 崩溃时工作流不可恢复 |
| 工具访问不协调 | 共享资源上的竞态条件 |
| 模型选择错误 | 成本效率低下（简单任务用Sonnet） |
| 无安全措施的自修改 | 子智能体破坏自身 |
| 无心跳监控 | 父智能体崩溃后无法检测孤儿 |
参考文件
带代码示例的详细实现：
| 文件 | 内容 |
|---|---|
references/four-layer-architecture.md |
四层堆栈、确定性边界、模式优先工具 |
references/coordination-patterns.md |
七种协调模式及代码 |
references/maker-pattern.md |
MAKER实现、投票、医疗诊断示例 |
references/tool-coordination.md |
权限继承、锁定、速率限制、缓存 |
references/production-hardening.md |
级联停止、孤儿检测、成本追踪、检查点 |