↓跳到主要内容
  1. 技术笔记/

Claude Code Agent Teams 运行机制深度分析

··2028 字 ·2 分钟

这篇内容根据知乎专栏文章整理,作者 Meta(知乎知识会员),首发于“LLM应用技术指北”,发布时间为 2026-03-08。原文链接是 https://zhuanlan.zhihu.com/p/2011414794905859760,参考文档是 https://code.claude.com/docs/en/agent-teams 。下面的拆解以文中给出的工具名和一次 code-review 轨迹为准。

把一段代码审查任务丢给单个 Subagent,父 Agent 只需要等一个结果;如果换成五个 reviewer 并行,父 Agent 要回答的问题就变了:谁负责哪块、做到哪一步、发现要不要互相传递、什么时候可以关掉团队。Claude Code 的 Agent Teams 就是把这几个问题做成了工具链。

两套分解任务的机制 #

Subagent 走的是 Task 工具不带 team_name 的那条路径。父 Agent 给出 subagent_type 和 prompt,子 Agent 在自己的上下文里执行,返回结果后被销毁;它没有团队上下文,上下文只覆盖这一次调用。调用关系是一对一,管控全部留在父 Agent 手里,适合边界清楚、输入输出明确的子任务。

Agent Teams 则先用 TeamCreate 建一个带唯一 team_name 和 description 的团队,再创建一组共享资源:TaskList 和团队配置文件。Leader 之外的每个 Teammate 都是独立的 Agent,有自己的上下文和工具集;它们能用 Read 读取共享配置、发现彼此,围绕同一个任务列表协作,生命周期从创建一直延续到显式解散。示例轨迹里同时跑了 maintainability-reviewer、security-reviewer 等五个 reviewer,每个都按自己的审查维度工作。

两者底层都落在 Task 工具上,区别是调用时有没有 team_name。这个参数像一个开关:不带它,Task 只是一次委托;带上它,Task 会把子 Agent 放进团队,给它团队身份和共享资源。判断该用哪种,取决于子任务之间要不要交换中间发现,任务大小不是主要判据。安全 reviewer 如果发现一个鉴权绕过,维护性 reviewer 需不需要立刻知道,决定了它们应该并行独立跑,还是应该进同一个团队。

共享状态放在哪里 #

团队模式把协调状态从某个 Agent 的上下文里搬到了 TaskList 和团队配置上。TaskList 保存每个子任务的 subject、description、状态和 owner,状态只有 pending、in_progress、completed 三种。TaskCreate 用 subject、description、activeForm 建任务,TaskGet 按 taskId 取完整描述,TaskUpdate 改状态或换 owner,TaskList 拉当前团队的任务概览。

这个设计的直接后果是状态可被所有成员检查。Leader 不需要记住“第三个 reviewer 做到哪了”,它读 TaskList 就行;Teammate 开始工作前用 TaskGet 拿到任务上下文,不必让 Leader 在 prompt 里重复一遍。owner 字段还承担了两个职责:避免两个 Teammate 同时抢同一个任务,以及在出问题时能追溯到是谁改的状态。对于并行审查这种读多写少的任务,这比让 Agent 之间直接互发消息更稳。

共享状态也有代价。TaskList 是中心,所有成员都要读写它,任务拆得太碎时,状态同步本身会占掉一部分注意力;任务描述写得不清楚时,TaskGet 取回来的只是一段模糊的 subject,Teammate 仍然要回去问 Leader。工具链能保证状态一致,保证不了任务定义的质量。

工具链的调用顺序 #

初始化阶段有一条比较固定的顺序。TeamCreate 先建团队和共享资源,TaskCreate 把大任务拆成可执行的条目,Task 用 run_in_background: true 并行拉起 Teammate,TaskUpdate 再把具体任务分配给对应的 owner 并改成 in_progress。Task 的参数里除了 subagent_type 和 prompt,还有 name 和 team_name;前者给 Teammate 一个可识别的名字,后者把它挂到团队上。

关闭阶段需要按协议走,不能直接 kill 进程。所有任务完成后,Leader 用 SendMessage 给每个 Teammate 发 shutdown_request;Teammate 回 shutdown_approved 并自行终止;确认所有成员都退出后,Leader 才调用 TeamDelete 清理目录和配置文件。这个顺序保证了正在执行的任务不会在中途被删掉,代价是 Leader 必须等待每个成员确认,收尾时间会变长。

工具定义里 SendMessage 的 type 有 message、broadcast、shutdown_request 三种,recipient 和 content 分别指定收件人和内容。broadcast 适合发全局约束,比如“所有人只读,不要改工作区”;message 适合点对点传递发现;shutdown_request 只应该由 Leader 在收尾阶段发。把这些语义分开,比让所有 Agent 共享一个自由文本频道更容易控制。

消息推送与任务轮询 #

Mailbox 是消息通道的共享存储,Teammate 用它发报告和空闲通知,Leader 用它发关闭请求,SendMessage 是读写 Mailbox 的工具。文中提到消息会自动推送给 Leader,不需要手动轮询;同时又提到 Leader 会轮询 TaskList 来确认所有任务都是 completed。这两句话描述的是两条通道,不能混在一起理解:消息通道负责把 Teammate 的报告和空闲通知送到 Leader,任务通道负责维护“这件事到底完成没有”的状态。空闲通知让 Leader 知道某个 reviewer 已经空出手,可以动态补任务;任务状态仍要以 TaskList 为准,因为消息可能只说明“我这边告一段落”,不代表对应任务已经被标记完成。

这套机制在任务数量少的时候很自然。每人一个任务,Leader 轮询几次就能收齐结果;空闲通知还能让它把新发现的问题追加成任务,再派给已经空下来的成员。任务数量上去以后,轮询和消息会同时变多,Leader 的上下文会被各种状态更新占满,这时候要么限制团队规模,要么把任务粒度调粗,减少协调次数。

什么场景值得开团队 #

需要多视角并行探索的任务适合 Agent Teams:代码审查、方案对比、跨模块排查,几个 reviewer 可以从安全、可维护性、性能不同角度同时看同一份代码,彼此不需要等待。任务之间有依赖、需要共享中间发现时,团队也比一串串行 Subagent 更合适,因为 TaskList 和 Mailbox 提供了传递状态的地方。

边界清楚、一次调用就能完成的任务更适合 Subagent。让一个 Subagent 去改一个函数、跑一组测试、查一个符号的引用,父 Agent 只关心最终结果,不需要团队身份、任务所有权和关闭协议;开团队反而多出建队、分配、收尾三次开销。写操作多的任务还要额外小心:多个 Teammate 同时改同一片代码,TaskList 的 owner 只能防止任务被重复领取,防不住文件级冲突,切分工作区仍然要由 Leader 事先做好。

还没被公开材料覆盖的部分 #

这套机制能确认的是工具名、调用顺序、任务状态和消息类型;团队配置的具体格式、上下文压缩之后状态怎么恢复、某个 Teammate 进程崩掉后任务怎么重新分配,公开材料都没有给出细节。这些恰好是生产环境最关心的部分,因为没有崩溃恢复,团队规模一大,Leader 就会变成单点。

如果要在真实仓库里开团队,先量两笔账:每个 reviewer 独立读一遍代码带来的 token 成本,以及汇总五份报告时 Leader 需要处理的冲突数量。TaskList 能协调任务状态,重复读代码的 token 成本不会因为进团队而消失。

说明:本文在原文基础上做了结构与表述整理,包含 AI 辅助创作。