多Agent协作 — Claude Code 技术解析

三种 Agent 执行模型

根据执行方式和通信需求，Claude Code 提供三种不同的 Agent 运行模型。

异步后台 · local_agent

🔄 Local Async Agent

通过 AgentTool() 在后台派生
TaskID 格式：a-{16HEX}
结果通过 <task-notification> XML 回传
可通过 SendMessageTool 继续对话
继承父 Agent 工具集（过滤交互式工具）
支持 isolation: 'worktree' 沙箱执行

同进程 · in_process_teammate

👥 In-Process Teammate

Team Swarm（TEAM_SWARMS 特性）
身份标识：agentName@teamName
通过 AsyncLocalStorage 上下文隔离
支持 Plan Mode 和权限桥接
通过 Mailbox 文件系统通信
Leader 可广播消息给所有 Teammate

远程 · remote_agent

☁️ Remote Agent

部署到 CCR（Claude Code Remote）
仅异步执行，TaskID 格式：r-{16HEX}
完全独立的会话生命周期
通过 isolation: 'remote' 参数触发
网络通信，结果亦通过 task-notification 返回

Coordinator 编排架构

通过环境变量 CLAUDE_CODE_COORDINATOR_MODE=1 激活。Coordinator 接管系统提示词，转变为多 Worker 编排者身份。

Coordinator 系统提示词核心内容

编排者角色定义

当 Coordinator 模式激活时，系统提示词替换为：

定义编排者身份（不直接执行，通过 Workers）
并行调度是核心优势，尽可能并发派发
综合结果后才回复用户，不转发原始输出
通过 SendMessage 继续已有 Worker（避免重复创建）
通过 TaskStop 终止不再需要的 Worker

Worker 工具过滤规则

子 Agent 可用工具限制

agentToolUtils.ts 中的过滤逻辑：

MCP 工具（mcp__*）：所有 Agent 均可用
交互式工具：异步 Worker 不可用（无法弹窗）
SendMessageTool：异步 Worker 不可用
AgentTool：子 Agent 默认不可再派生（防递归）
Fork 子 Agent（无 subagent_type）加 boilerplate 防止重复派生

三种消息传递机制

根据目标 Agent 类型，SendMessageTool 路由到不同的通信通道。

📨

Task Notification（异步 Worker 结果回传）

Worker 完成后，结果以 <task-notification> XML 格式注入到 Coordinator 的下一轮用户消息中。Coordinator 解析 task-id 识别来源，可决定继续还是综合。

<task-notification>
  <task-id>a-1a2b3c4d5e6f7890</task-id>
  <status>completed</status>
  <summary>Found 3 auth-related files, analyzed JWT flow</summary>
  <result>
    The authentication flow uses JWT tokens stored in...
  </result>
  <usage><total_tokens>4521</total_tokens><duration_ms>12400</duration_ms></usage>
</task-notification>
            

📫

Mailbox 系统（In-Process Teammate 通信）

基于文件系统的消息队列，位于 ~/.claude/teams/{teamName}/inboxes/{agentName}.json。使用 proper-lockfile 实现文件锁，保证并发安全。Teammate 在每轮边界轮询收件箱。

// ~/.claude/teams/my-team/inboxes/researcher.json
[
  {
    from: "leader",
    text: "Please also check the database schema",
    timestamp: "2025-01-01T10:00:00Z",
    read: false,
    color: "#58a6ff",
    summary: "Check database schema"
  }
]
// 广播: from: "*" → 发送到所有 Teammate
            

📬

Pending Message Queue（异步 Agent 继续）

通过 SendMessageTool({to: "a-xxx", message: "..."}) 向运行中的异步 Agent 发送消息。消息被入列到 LocalAgentTask 的 pendingMessages 队列，在 Agent 完成当前轮次后被消费为下一轮输入。

// SendMessageTool 路由逻辑
function handleMessage(recipientName, message) {
  if (isLocalAgentTask(task))
    return queuePendingMessage(taskId, message)       // 异步Queue
  if (isInProcessTeammateTask(task))
    return writeToMailbox(agentName, message, team)   // 文件Mailbox
  if (to === "*")
    return broadcastToAll(message, team)              // 广播
}
            

MCP 工具动态集成

Model Context Protocol 服务器通过标准化 RPC 协议动态暴露工具，Claude Code 自动发现并规范化工具名称。

工具注册流程

1

连接 MCP Server

stdio / SSE / HTTP / WebSocket 四种传输协议

2

ListTools RPC 发现工具

获取所有工具定义（名称、描述、inputSchema）

3

名称规范化

my-tool → mcp__server-name__my_tool

4

注入到工具池

与内置工具合并，传递给 Claude API 的 tools 参数

5

子 Agent 继承

父 Agent 的 MCP clients 自动传递给子 Agent，可通过 frontmatter 添加专属 MCP 服务器

MCP 服务器连接状态

connected

已连接，tools 可用，instructions 已注入系统提示词

needs-auth

需要 OAuth 或 API Key 认证，触发 elicitation 流程

pending

正在重连，tools 暂时不可用

failed

连接失败，记录错误信息，用户可手动重试

disabled

用户主动禁用，不在 tools 列表中

MCP 配置作用域

4 种配置来源

local：当前目录 .claude/mcp.json
user：~/.claude/mcp.json（用户全局）
project：项目根目录配置
managed/enterprise：企业管理员推送

Agent 专属 MCP

Agent 定义中的 MCP 配置

通过 Agent 定义文件（YAML frontmatter）中的 mcpServers: ["server-name"] 字段，为特定子 Agent 挂载专属 MCP 服务器，在 initializeAgentMcpServers() 中初始化，Agent 退出时自动清理。

MCP Instructions

服务器自定义指令

已连接的 MCP 服务器可提供 instructions 字段，被注入到系统提示词的 "# MCP Server Instructions" 段。该段被标记为 DANGEROUS_uncached，因为服务器连接状态可能随时变化（避免缓存过期）。

Fork 子 Agent 模式

FORK_SUBAGENT 特性启用后，调用 AgentTool 不指定 subagent_type 时，创建一个继承父 Agent 完整上下文的"分叉"。

Fork 与普通 Worker 的区别

特性	Fork	普通 Worker
上下文	继承父 Agent 完整对话	全新空白上下文
系统提示词	与父 Agent 完全相同	可独立配置
Prompt Cache	字节完全一致（命中率高）	独立 cache key
递归限制	boilerplate tag 防止再次 fork	AgentTool 默认不可再派生

// AgentTool 输入类型 (AgentTool.tsx)
type AgentToolInput = {
  description: string    // 3-5词描述，用于TaskID标签
  prompt: string       // 自包含的任务描述
  subagent_type?: string  // 不填 → Fork模式
  name?: string        // 可寻址的Agent名称
  model?: 'sonnet'|'opus'|'haiku'
  run_in_background?: boolean  // 默认true
  isolation?: 'worktree'|'remote'
  cwd?: string         // 工作目录覆盖
}

// Fork 时父Agent提示词中的 boilerplate 标记
// 防止 Fork 再次 fork（避免无限递归）
const FORK_BOILERPLATE = `
**If you ARE the fork** — execute directly; 
do not re-delegate.
`
      

🤝 多 Agent 架构