Agent 协作流程

职责概述

Claude Code 的 Agent 协作系统（代号 Swarm）允许多个 AI 实例协同工作。一个 Leader Agent 可以生成多个 Teammate Agent，它们在独立的终端面板或进程内运行，通过文件邮箱系统交换消息。本页深入分析 Agent 层级关系、消息传递协议、任务委派模式和错误处理机制。

架构设计

Agent 协作系统采用三层架构，从后端到业务逻辑清晰分层：

三种执行后端

后端自动检测优先级

核心数据流

Agent 生成与生命周期

消息传递流程

权限请求流程

关键类型与接口

TeammateIdentity

// swarm/backends/types.ts:191-200
type TeammateIdentity = {
  name: string           // 如 "researcher", "tester"
  teamName: string       // 团队名
  color?: AgentColorName // UI 颜色标识
  planModeRequired?: boolean
}

TeammateSpawnConfig

// swarm/backends/types.ts:205-225
type TeammateSpawnConfig = TeammateIdentity & {
  prompt: string
  cwd: string
  model?: string
  systemPrompt?: string
  systemPromptMode?: 'default' | 'replace' | 'append'
  worktreePath?: string
  parentSessionId: string
  permissions?: string[]
  allowPermissionPrompts?: boolean
}

TeammateExecutor 统一接口

// swarm/backends/types.ts:279-300
type TeammateExecutor = {
  readonly type: BackendType
  isAvailable(): Promise<boolean>
  spawn(config: TeammateSpawnConfig): Promise<TeammateSpawnResult>
  sendMessage(agentId: string, message: TeammateMessage): Promise<void>
  terminate(agentId: string, reason?: string): Promise<boolean>
  kill(agentId: string): Promise<boolean>
  isActive(agentId: string): Promise<boolean>
}

InProcessRunnerConfig

// swarm/inProcessRunner.ts:471-502
type InProcessRunnerConfig = {
  identity: TeammateIdentity
  taskId: string
  prompt: string
  agentDefinition?: CustomAgentDefinition
  teammateContext: TeammateContext
  toolUseContext: ToolUseContext
  abortController: AbortController
  model?: string
  systemPrompt?: string
  systemPromptMode?: 'default' | 'replace' | 'append'
  allowedTools?: string[]
  allowPermissionPrompts?: boolean
  description?: string
  invokingRequestId?: string
}

CLI 标志继承

// swarm/spawnUtils.ts:38-89 — 传递给子进程的标志
function buildInheritedCliFlags(options?): string {
  // --dangerously-skip-permissions (如 Leader 使用)
  // --model (模型覆盖)
  // --settings (设置文件路径)
  // --plugin-dir (插件目录)
  // --teammate-mode (队友模式)
  // --chrome / --no-chrome
}

环境变量转发

// swarm/spawnUtils.ts:96-128 — 转发给 tmux 队友的环境变量
const TEAMMATE_ENV_VARS = [
  'CLAUDE_CODE_USE_BEDROCK',    // API 提供商
  'CLAUDE_CODE_USE_VERTEX',
  'CLAUDE_CODE_USE_FOUNDRY',
  'ANTHROPIC_BASE_URL',         // 自定义端点
  'CLAUDE_CONFIG_DIR',          // 配置目录
  'CLAUDE_CODE_REMOTE',         // CCR 标记
  'HTTPS_PROXY',                // 代理变量
  'SSL_CERT_FILE',
  // ...更多
]

设计模式与亮点

// inProcessRunner.ts:1160-1161
await runWithTeammateContext(teammateContext, () =>
  runWithAgentContext(agentContext, () =>
    runAgent({ ... })
  )
)

代码索引