Claude Code 架构——多智能体机制(02):从 Subagent、Coordinator 到 Agent Teams

本文深入解析Claude Code的多智能体机制,涵盖Subagent(子任务委派与侧链执行)、Coordinator(主Agent调度与多阶段任务协调)及Agent Teams(团队协作、状态管理与消息通信)三层架构。重点阐述三者在上下文隔离、执行调度、结果综合、进程模型与通信路径上的技术差异与协同关系,并说明其在代码审查、重构、跨模块开发等场景中的适用边界与实现约束。

⏱ 约 9 分钟读完 ✍️ 4312 字

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,会继承创建时父会话已有的上下文。

维度普通 SubagentFork
起始信息委派说明与自身配置父会话已有上下文
角色指令使用子 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
statuscompleted、failed 或 killed
summary执行状态摘要
result最终结果,可选
usageToken、工具调用和耗时等信息,可选

在该实现中,这些通知以 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