多 Agent 协作
多 Agent 编排模式、协调策略与实际开发场景
参考资料:
- Building Effective Agents
- Sub-agents
- Agent Teams
- GitHub Copilot Coding Agent
- Multi-Agent Research System
更新:2026-05-11
一、为什么需要多 Agent
公开研究数据(Multi-Agent Research System):
多 Agent 系统比单 Agent 方式在研究任务上性能提升 90.2%,代价是使用约 15 倍的 token。
核心原则:只在更简单的方案明确不够用时,才引入多 Agent 复杂度。
适合场景:
- 任务可以拆成互相独立的子任务并行完成
- 不同部分需要专业化处理(实现 / 测试 / 审查 / 调研分别负责)
- 需要互相 review 和验证(一个写,另一个审)
- 任务规模超过单个 Agent 的上下文窗口
不适合场景:
- 步骤严格串行、有强依赖
- 简单问答或一次性小任务
- 预算有限(多 Agent 成本线性增长)
二、三种 Agent 的本质区别
普通 Agent(单体)
一个主 Agent 自己做完所有事。对应到工具上,通常就是你当前的 Claude Code 或 Copilot CLI 主会话。
Subagent(专职工作者)
主 Agent 派专职 Agent 干活,子 Agent 只向主 Agent 汇报。Claude Code 常见为 Subagent;Copilot CLI 常见为 task/background agent。
Agent Team(协作团队)
每个队友独立运行,可以直接互发消息;在支持团队协作的工具里,你也能直接联系某个队友。
三种模式对比
普通 Agent
- 上下文:单一共享上下文
- 通信:你和它直接对话
- 协调:自己决定所有步骤
- 成本:最低
- 适合:单一连贯任务
Subagent
- 上下文:独立上下文,只把结果返回给主 Agent
- 通信:子 Agent 主要向主 Agent 单向汇报
- 协调:主 Agent 管理所有工作分配
- 成本:中等
- 适合:侧任务会污染主上下文;反复用同类工作者
Agent Team
- 上下文:每个队友独立上下文,完全隔离
- 通信:队友之间可直接互发消息,你也能直接联系某个队友
- 协调:共享任务列表 + 自主认领 + Lead 综合
- 成本:最高
- 适合:需要讨论、互相挑战、协作的复杂工作
三、普通 Agent:基础单体
普通 Agent 就是你平时打开的主会话:Claude Code 可以直接调用本地工具,Copilot CLI 也可以在当前终端会话里连续推进任务直到完成。
适合: 单一连贯任务、上下文不超窗口限制、没有需要专业化处理的子任务。
四、Subagent:专职工作者
核心定义
当某个侧任务会把主对话淹没在搜索结果、日志或文件内容里,而且这些中间过程之后不会再引用时,就应该拆给独立 Agent。
两个典型使用时机:
- 侧任务会污染主上下文:比如搜索 100 个文件,结果不需要留在主对话里
- 反复需要同类工作者:比如每次都要“审查代码”,可以固化成专职 Agent
上下文隔离机制
关键: 子 Agent 执行过程中产生的大量内容不会进入主 Agent 的上下文,这是保护主上下文的核心机制。
创建 Subagent
/project/agents/swift-analyzer.md
---
name: swift-analyzer
description: |
Swift 代码质量分析师。
当需要分析 Swift 代码结构、找潜在问题、输出质量报告时调用。
不负责修改代码,只负责分析和报告。
tools: Read, Grep, Glob
model: fast
maxTurns: 20
---
你是一个 Swift 代码质量分析师。
## 分析维度
1. **安全问题**:force unwrap、未处理的错误、硬编码敏感信息
2. **规范问题**:命名规范、函数长度(超 80 行标记)
3. **架构问题**:循环依赖、单一职责违反
## 输出格式
### 严重问题([文件名:行号] 问题描述)
### 警告
### 建议
每条问题附上修复示例代码。实际落地时,Claude Code 和 Copilot CLI 的 Agent 声明方式、字段名、启动入口可能不同,但“任务描述自包含 + 工具权限最小化 + 输出格式固定”这三个原则相同。
前台 vs 后台
- 前台(默认) — 主 Agent 等子 Agent 完成才继续,适合子 Agent 的结果是主 Agent 下一步输入的情况
- 后台(
background: true或等价能力) — 主 Agent 继续响应你,子 Agent 并发执行,适合完全独立、不影响主流程的任务
五、Agent Team:协作团队
核心定义
Agent Team 是“多个独立 Agent 共同完成一项任务”的模式。Claude Code 更偏向内建团队协作;Copilot CLI 更常见的是主会话调度多个并行 agent / background task,本质上都属于多 Agent 编排。
四个组成部分
Team Lead(队长)
- 职责:创建团队、分配任务、监控进度、综合结果
- 特点:就是你当前的主会话,拥有最完整的上下文
Teammates(队友)
- 职责:领取任务、独立执行、通信协作、标记完成
- 特点:每个队友都是独立 Agent,有独立上下文;加载项目级规则和工具配置,但不继承 Lead 的完整对话历史;给队友的任务描述必须自包含
Task List(共享任务列表)
任务认领方式:
- Lead 显式分配:告诉 Lead 把哪个任务给哪个队友
- 队友自主认领:完成当前任务后,自动认领下一个可用任务
Mailbox(消息系统)
Subagent vs Agent Team 通信差异
两种显示模式
- In-process 模式(默认):所有队友在主终端同一界面,适合单窗口调度
- Split panes 模式(需要 tmux 或 iTerm2):每个队友独占一个窗格,可同时看到所有队友实时进度
六、五种核心协调模式
来自公开资料 Building Effective Agents
模式 1:Orchestrator-Workers(最常用)⭐
Orchestrator 不执行具体工作,只负责分解和协调。适合: 功能开发、代码重构、分析大型代码库。
模式 2:Parallelization(并行)
经验规律:当子 Agent 内部还能并行调用多个工具时,整体执行时间通常会显著下降。
适合: 分析多个不相关文件、搜索多个数据源。
模式 3:Prompt Chaining(链式)
适合: 架构分析 → 实现 → 测试这类有严格顺序依赖的工作。
模式 4:Routing(路由)
适合: 不同类型的 bug 用不同专家处理,不同语言或平台用不同代码生成器。
模式 5:Evaluator-Optimizer(评估 + 优化循环)
适合: 代码质量要求高、需要多轮迭代改进的场景。
七、实战案例:iOS / 移动端 / IoT 场景
场景 1:iOS 插件新功能开发
任务: 给一个 iOS 插件新增功能,流程包含架构分析、代码实现、单测编写、代码审查四个环节。
任务依赖关系
推荐编排
architect:扫描/project/ios-plugin/Sources/,输出新增文件、修改文件、接口定义、数据流implementer:按设计实现 Swift 代码test-writer:补 XCTest,覆盖正常路径 / 边界条件 / 错误路径reviewer:检查错误处理、线程切换、内存管理、命名和 API 一致性
适合的协调模式
- 主流程:Prompt Chaining
- 实现 + 单测:Parallelization
- 最终收口:Evaluator-Optimizer
场景 2:跨仓库依赖升级
任务: 同步升级主工程、底层 SDK、UI 组件库三套仓库中的同一依赖版本,并确认编译和接口兼容性。
推荐编排
planner:先拉取三个仓库的依赖现状、版本边界、Breaking Changes- 三个仓库 Agent 并行执行:各自修改依赖声明、处理 API 变更、运行本仓库构建
validator:汇总编译错误、接口不兼容点、需要同步发布的顺序
关注点
- 不同仓库是否共用同一版本约束
- 组件库升级后主工程是否存在二次适配
- 是否需要按照 SDK → UI 组件库 → 主工程 顺序推进
场景 3:IoT 设备调试排查
任务: 针对一段设备连接异常或指令执行失败的问题,完成日志分析、协议解码、问题定位。
推荐编排
log-agent:抽取关键事件、错误码、超时点,生成时间线protocol-agent:解码上下行 payload,标注字段含义和异常值device-state-agent:根据握手、绑定、控制、回执阶段推断状态机停在哪一步merge-agent:汇总成“现象 → 证据 → 根因 → 建议修复”的定位报告
适合的协调模式
- 日志 / 协议 / 状态:Parallelization
- 根因判断:Orchestrator-Workers
- 复验假设:Evaluator-Optimizer
场景 4:代码审查与重构
任务: 对一个跨多个文件的大型改动做并行 review,并形成可执行的重构报告。
推荐编排
- 按审查维度分工,而不是按文件机械切分
- 汇总 Agent 只输出高价值问题:功能回归、线程问题、资源泄漏、接口耦合、重复逻辑
- 如果确认需要重构,再派
refactor-agent按报告逐项落地
报告结构建议
- 严重问题(必须修)
- 设计债务(建议本次一起修)
- 可延后优化项
- 建议的重构顺序与风险点
八、Agent 配置字段说明
不同工具的字段名、存放位置、调用入口可能不同;下面保留的是两类工具都常见的配置意图。
name必填 — 唯一标识,小写字母 + 短横线,如swift-analyzerdescription必填 — 决定系统何时调用该 Agent,要写清触发场景,是最重要的字段tools可选 — 允许的工具列表,不填则继承全部,只给必要工具disallowedTools可选 — 强制禁用的工具,确保只读 Agent 不能写文件model可选 — 轻量任务用快速模型,复杂推理用高质量模型permissionMode可选 — 控制是否自动接受编辑、是否需要额外确认maxTurns可选 — 最大执行轮次,建议 15–30skills可选 — 预加载的 Skills / 流程能力;子 Agent 通常不自动继承父会话的全部能力mcpServers可选 — 可用的外部服务与工具扩展hooks可选 — 生命周期钩子(如 PreToolUse / PostToolUse / Stop),用于日志、拦截危险操作memory可选 — 持久记忆范围:user/project/localbackground可选 —true表示后台运行,独立任务不阻塞主对话effort可选 — 推理强度或执行强度,如low/medium/highisolation可选 — 隔离执行环境,如worktreecolor可选 — 显示颜色,多个 Agent 并发时便于区分initialPrompt可选 — 启动时自动发送的第一条消息
九、最佳实践
- 团队规模 — 从 3–5 个 Agent 开始,每增加一个 Agent,token 和协调成本都会上升
- 任务粒度 — 每个 Agent 负责“能产出清晰交付物的自包含单元”,不要拆得过碎
- 上下文传递 — 队友不加载 Lead 的完整对话历史,给队友的任务描述必须自包含
- 文件冲突 — 不同 Agent 尽量拥有不同文件集合,避免同时写同一个文件
- 启动顺序 — 先从只读、边界清晰的研究 / review 任务开始,再逐步放开写操作
- 输出模板 — 对分析型 Agent 固定输出结构,避免最终汇总时格式不统一
- 验证收口 — 最后必须有一个收口 Agent 负责 build、test、diff 审核或结果汇总
十、已知限制
- 上下文不自动共享 — 无论 Claude Code 还是 Copilot CLI,独立 Agent 的上下文都需要通过任务描述显式传递
- 任务状态可能滞后 — 队友有时忘记标记完成,会阻塞有依赖的后续任务
- 关闭较慢 — 队友通常会等当前请求完成才关闭
- 并行写入有冲突风险 — 多个 Agent 同时改同一文件,极易产生覆盖或冲突
- 团队能力依赖终端环境 — Split panes、tmux、后台任务、日志跟踪等能力依赖本地环境支持
- 嵌套编排要谨慎 — 子 Agent 再派更多 Agent 虽然可行,但排查成本会快速升高
十一、选择指南
成本参考:普通 Agent < Subagent < 多 Subagent < Agent Team
使用建议
Only add agentic complexity when simpler solutions demonstrably fail. Single optimized LLM calls often suffice.
只有更简单的方案明确不够用时,才引入多 Agent 复杂度。一个调优好的单次调用往往就够了。
十二、实际工作中的 Agent 编排建议
面向通用 iOS 开发者,建议按下面的顺序使用 Agent:
- 先单 Agent,后多 Agent:先让主 Agent确认范围、关键文件、风险点,只有任务明确可拆时再并行
- 先读后写:第一批 Agent 只做扫描、分析、列计划,不要一开始就放多个写入 Agent
- 按职责拆,不按人名拆:优先拆成
architect、implementer、tester、reviewer,不要拆成“Agent1、Agent2” - 按文件边界拆写任务:UIKit 页面、业务层、数据层、测试层尽量由不同 Agent 负责,降低冲突
- 把验证独立出来:build、单测、lint、日志校验单独交给
validator或reviewer,不要让实现者自己宣布完成 - 日志 / 协议 / 崩溃排查天然适合并行:移动端和 IoT 问题排查里,时间线、协议字段、状态机推断通常可以分开做
- 跨仓库任务必须设总控 Agent:主工程、SDK、组件库联动时,一定要有一个 Agent 专门维护升级顺序、接口兼容和最终报告
- 输出固定模板:统一要求每个 Agent 给出“结论、证据、风险、下一步”,汇总效率最高
- 保留人工决策点:API 变更、架构改动、公共组件抽取这类高影响决策,应该由人最终拍板
- 把多 Agent 当放大器,不是替代品:它擅长扩展并行度、隔离上下文、加快验证,不擅长替你定义模糊需求
参考来源: Building Effective Agents · Claude Code Sub-agents · GitHub Copilot