Claude Code 的多智能体机制,可以从三种协作方式理解:把子任务交给助手、由主 Agent 集中调度,以及组织多个 Agent 持续协作。
它们分别对应 Subagent、Coordinator 和 Swarm / Agent Teams。
| 类型 | 核心定位 | 主 Agent 的职责 | 协作关系 |
|---|---|---|---|
| Subagent | 子任务委派 | 推进整体任务,按需调用助手 | 主从关系 |
| Coordinator | 集中调度 | 拆分任务、派工、综合结果、跟进执行 | 协调器与 Worker |
| Agent Teams | 团队协作 | 作为 Lead 管理成员与整体进度 | Lead 与多个 Teammate |
三者处在不同的架构层次:Subagent 描述委派机制,Coordinator 描述主 Agent 的工作方式,Agent Teams 描述团队协作机制。 它们会复用部分执行设施。
一、Subagent:主会话的侧链与子任务委派
1. 工作方式
Subagent 是具有独立上下文和工具使用能力的子 Agent。主 Agent 提供任务说明,子 Agent 自行分析问题、调用工具,并返回结果。
主 Agent 明确子任务
↓
创建 Subagent,提供任务说明
↓
Subagent 独立推理与调用工具
↓
返回执行结果
↓
主 Agent 综合结果,继续整体任务
这种分工以具体子任务为中心。主 Agent 仍然负责整体推进,也可以继续亲自实现代码。
2. 为什么称为“主会话的侧链”
“侧链”主要描述执行记录与主会话的关系:
- 子 Agent 有独立的消息历史和工具调用过程。
- 详细执行过程写入自己的 sidechain transcript。
- 执行结果返回主会话,供主 Agent 综合使用。
因此,主会话无需容纳子 Agent 搜索、读取文件和试验过程中的全部中间输出。
这里的“独立”指上下文与执行记录分开管理,并不自动意味着文件系统、数据库或运行进程完全隔离。
3. 普通 Subagent 与 Fork 的上下文区别
普通 Subagent 从独立上下文开始,依据任务说明和自身配置工作,不会自动获得主会话全部聊天历史。
Fork 是特殊的子 Agent,会继承创建时父会话已有的上下文。
| 维度 | 普通 Subagent | Fork |
|---|---|---|
| 起始信息 | 委派说明与自身配置 | 父会话已有上下文 |
| 角色指令 | 使用子 Agent 的角色配置 | 继承父会话相关指令 |
| 适合任务 | 边界明确的研究、检查或实现 | 依赖大量前置讨论的旁支任务 |
| 主 Agent 的准备工作 | 提供必要背景 | 重点说明本次分支目标 |
例如,“搜索所有认证入口”通常可以交给普通 Subagent;“基于刚才讨论的三个方案,独立评估第二个方案”更适合 Fork。官方上下文说明
在该快照的 Fork 实验路径中,省略 subagent_type 可以触发隐式 Fork,但前提是对应功能已经启用,不能把“省略类型”直接理解为任何版本都会 Fork。
Fork 还会复用父会话已经渲染好的 system prompt 字节,避免重新构造时出现差异,影响 prompt cache 命中。这说明上下文继承也与模型请求缓存有关。forkSubagent.ts
4. runAgent() 负责什么
AgentTool 处理入口与路由,runAgent() 准备并运行具体 Agent。它承担的主要职责包括:
| 职责 | 作用 |
|---|---|
| 解析角色、模型和工具 | 确定 Agent 的执行能力 |
构造 ToolUseContext | 提供工具调用所需运行环境 |
| 初始化 Agent 专属 MCP 服务 | 接入该 Agent 配置的外部工具 |
执行 SubagentStart Hooks | 在启动时执行扩展逻辑、补充上下文 |
| 记录 Transcript 和元数据 | 保存执行历史与恢复所需信息 |
调用 query() | 进入模型推理与工具调用循环 |
Agent 专属 MCP 服务可以补充父上下文已有的服务。执行结束时,新建连接需要清理,共享连接则应保留。
所以,Subagent 是完整的 Agent 执行过程,能够根据工具结果继续判断和行动。执行与 MCP 初始化实现
二、Coordinator:把主 Agent 的工作重点转向调度
1. 它改变了什么
Coordinator 将主 Agent 定义为协调器:主要负责理解目标、拆分任务、调度 Worker、综合结果和向用户汇报。
理解目标 → 拆分任务 → 派出 Worker
↓
接收执行结果
↓
综合判断与调整方案
↓
继续派工或汇报成果
普通主 Agent 也可以调用多个 Subagent。Coordinator 的特点是通过专门的 system prompt,把组织执行变成主 Agent 的主要职责。
2. 多阶段任务如何推进
Coordinator 的工作流可以分为四个阶段:
| 阶段 | Worker 的工作 | Coordinator 的工作 |
|---|---|---|
| Research | 检查代码、接口与测试 | 明确问题范围和依赖 |
| Synthesis | 提供发现与证据 | 综合结果,确定方案 |
| Implementation | 按具体要求修改代码 | 控制范围,协调冲突 |
| Verification | 测试与边界检查 | 判断是否满足交付目标 |
以登录流程重构为例,协调器可以先让不同 Worker 检查认证逻辑和测试,再综合研究结果,形成具体修改要求,最后组织验证。
并发应服从任务依赖:只读研究通常容易并行;修改同一组文件的工作需要串行或重新划分职责。
3. 派工与结果回流
协调器使用三个主要工具组织执行:
| 工具 | 用途 |
|---|---|
Agent | 创建 Worker 并委派任务 |
SendMessage | 向已有 Worker 追加任务 |
TaskStop | 停止正在运行的任务 |
Worker 的结果通过 <task-notification> 回流,主要包含:
| 字段 | 含义 |
|---|---|
task-id | 用于识别对应 Agent |
status | completed、failed 或 killed |
summary | 执行状态摘要 |
result | 最终结果,可选 |
usage | Token、工具调用和耗时等信息,可选 |
在该实现中,这些通知以 user-role message 进入协调器上下文,但语义上属于系统内部通知,不能当作用户的新指令。
这使任务推进具有事件驱动特点:研究完成后可以追加实现任务,验证失败后可以继续要求修复。结果通知与工作流实现
4. 协调器必须综合结果,再继续派工
协调器的关键能力是理解 Worker 的发现,并把它转化为明确的实施要求。
例如,以下任务包含了目标、范围、约束和验收方式:
在认证校验中增加停用用户检查。保留现有响应结构,只修改认证模块和对应测试。覆盖正常用户、停用用户和不存在用户三种场景,并返回测试结果与未解决的问题。
还应区分两类工作:
- 跟踪进度:通过执行状态和通知了解 Worker 是否完成。
- 验证成果:运行测试或检查行为,证明改动满足要求。
无需再派一个 Worker 专门询问另一个 Worker 的进度;成果验证则应有明确证据。
Coordinator 适合多轮研究、实现与验证的复杂任务。它的主要成本来自任务拆分、结果综合和后续协调。
三、Swarm / Agent Teams:建立可持续协作的团队
1. 团队模式增加了什么
Swarm 是分析文档中的内部称呼,官方产品文档使用 Agent teams。
团队由一个 Lead 和多个 Teammate 组成。Lead 协调整体目标,成员分别执行工作,并在过程中交换信息。
Lead:协调目标、分工与最终验收
├─ 前端成员:页面与交互
├─ 后端成员:接口与业务校验
└─ 测试成员:集成场景与验证
团队协作适合需要持续交流的跨模块任务。例如,前端需要确认接口字段,后端需要了解错误展示要求,测试成员需要同步复现条件。
这里增加的关键能力是:成员身份、团队状态、持续通信、共享任务与生命周期管理。
2. 团队如何创建与保存状态
TeamCreateTool 会创建团队配置、建立对应任务列表,并更新运行时的 teamContext。TeamCreateTool.ts
这些状态各有职责:
| 状态 | 保存内容 | 主要用途 |
|---|---|---|
| Team file | 团队名称、Lead、成员名单及配置 | 确定团队组成 |
| Task list | 工作描述、负责人、状态、依赖 | 组织业务任务 |
| AppState.teamContext | 当前运行时团队信息 | 路由、调度与界面展示 |
| Mailbox | 成员收到的消息和已读状态 | 传递协作信息 |
| Transcript | 消息历史与工具调用过程 | 查看执行记录、支持恢复 |
默认配置目录下的文件结构可以概括为:
~/.claude/
├─ teams/
│ └─ <team_name>/
│ ├─ config.json
│ └─ inboxes/
│ └─ <agent_name>.json
└─ tasks/
└─ <task_list_id>/
└─ <task_id>.json
团队配置记录的是成员关系,任务文件记录的是工作状态,两者分开保存。实际目录还受配置根目录和任务列表解析方式影响。团队文件实现、任务存储实现
3. 成员如何创建:同进程与独立进程
spawnTeammate() 是团队成员创建入口,可以选择不同运行后端。spawnMultiAgent.ts
| 后端 | 运行方式 | 特点 |
|---|---|---|
| In-process | 多个成员运行在同一 Node.js 进程 | 由运行时管理身份、消息与状态 |
| tmux / iTerm2 | 启动独立 Claude Code 进程 | 通过终端窗格展示成员执行 |
同进程创建过程包含:
生成 Agent ID 和运行任务 ID
↓
创建成员身份、上下文和取消控制器
↓
构造 InProcessTeammateTaskState
↓
注册到 AppState
↓
启动成员执行循环
运行状态中包含成员身份、模型、消息记录、待处理消息、空闲标识和关闭请求等数据。spawnInProcess.ts
同进程运行通过 AsyncLocalStorage 区分异步执行链中的身份,避免并发操作错误地使用其他成员的上下文。
它解决的是运行时身份归属,不会隔离磁盘文件、数据库或端口。资源冲突仍需通过明确分工控制。agentContext.ts
4. 通信采用两条主要路径
SendMessage 既可以用于继续本地 Agent,也可以用于团队成员通信。
| 目标 | 主要处理方式 |
|---|---|
| 本地 Agent,仍在运行 | 将消息加入待处理队列 |
| 本地 Agent,已经停止 | 尝试读取 Transcript 并恢复执行 |
| 团队成员 | 将消息写入接收方 Mailbox |
| 团队广播 | 按广播逻辑向多个成员投递 |
因此,SendMessage 同时承担消息路由和执行续接职责。SendMessageTool.ts
Mailbox 提供读取消息、读取未读消息、写入消息和标记已读等操作。写入时加锁,并在取得锁后重新读取当前内容,减少并发写入覆盖。
文件锁保护读写过程,但不能据此推导出完整的分布式消息可靠性保证。teammateMailbox.ts
5. Inbox Poller 如何处理协作消息
Mailbox 写入消息后,需要接收侧将其接回运行流程。
useInboxPoller() 会读取未读内容,并按消息类型分别处理:
| 消息类型 | 处理目的 |
|---|---|
| 普通成员消息 | 交流发现、追加工作 |
| 权限请求与响应 | 处理具体工具操作权限 |
| 计划审批请求与响应 | 决定实现方案是否可以继续 |
| 关闭请求与确认 | 协调成员退出 |
所以,Mailbox 中同时包含普通文本和结构化协作协议。接收侧需要识别类型,再交给执行、权限或界面流程。useInboxPoller.ts
四、整体调用链路与模式限制
1. AgentTool 如何分流
AgentTool 的关键输入可以按用途分类:
| 输入 | 作用 |
|---|---|
description、prompt | 描述任务及具体要求 |
subagent_type | 指定子 Agent 类型 |
model | 提供模型选择 |
run_in_background | 请求后台执行 |
name | 为 Agent 提供可寻址名称 |
team_name | 指定团队,也可以从当前上下文解析 |
mode | 在该快照的成员创建路径中指定权限模式 |
字段是否可见、如何生效,还受功能条件与运行模式影响,不能视为跨版本不变的公开 API。AgentTool 输入与路由实现
主要调用关系如下:
主 Agent / Coordinator
↓
AgentTool.call()
│
├─ 普通 Subagent / Fork
│ └─ runAgent() → query()
│
└─ 团队成员路径
└─ spawnTeammate()
├─ 同进程成员
│ └─ 注册运行任务
│ └─ inProcessRunner
│ └─ runAgent() → query()
│
└─ tmux / iTerm2
└─ 启动独立 Claude Code 会话
团队分支的关键条件是存在解析后的 teamName,同时提供成员 name。
因此,AgentTool 负责创建入口与路由,runAgent() 负责具体执行;同进程 Teammate 也会复用这个执行器。
2. 为什么需要限制嵌套
该快照对 Agent 拓扑设置了明确约束:
| 约束 | 控制目的 |
|---|---|
| Teammate 不能再创建 Teammate | 保持团队成员结构清楚 |
| 同进程 Teammate 不能再启动自己的后台 Agent | 控制与主进程相关的生命周期 |
| Fork 子 Agent 不能递归 Fork | 避免分支扩张失控 |
这些限制不等于禁止所有子任务委派。例如,同进程 Teammate 的同步 Subagent,与再创建一个团队成员,是不同路径。创建约束实现
五、总结
因此,Claude Code 的 multi-agent 不是单一实现,而是一个分层体系:
一、普通 AgentTool 子代理
- 单个主 agent 派出一个 subagent
- 可同步、可后台、可 fork
二、Coordinator Mode
- 主线程变成 coordinator
- 通过 AgentTool 持续派出多个 worker
- worker 结果用 task-notification 回流
三、Swarm / Teammates
- 创建 team
- 产生 lead + teammates
- 支持 in-process / tmux / iTerm2 后端
- 支持 mailbox、权限回流、task list 协作
实际选择可以遵循:
- 局部研究、审查或验证:优先使用 Subagent。
- 多阶段任务,需要反复派工与综合:采用 Coordinator 式组织。
- 跨模块工作,需要成员持续交流:使用 Agent Team。
- 小而明确的修改:单 Agent 通常更直接。
本文首发于 CSDN:Claude Code 架构——多智能体机制(02):从 Subagent、Coordinator 到 Agent Teams