09 | Claude Code技术深度解析(九):多Agent协作架构

09 | Claude Code技术深度解析(九):多Agent协作架构声明：📝 作者：甜城瑞庄的核桃（ZMJ）原创学习笔记，欢迎分享，但请保留作者信息及原文链接哦～本文全面剖析Claude Code的多Agent协作机制,包括3种协作模式、内置Agent类型、工具过滤机制、Context继承策略等核心技术。通过源码解析,彻底理解多Agent系统的设计与实现。目录一、多Agent概述二、3种协作模式三、内置Agent类型四、Agent Definition规范五、工具过滤机制六、Agent生命周期七、Coordinator模式深度解析八、自定义Agent开发九、常见问题解答一、多Agent概述1.1 为什么需要多Agent单Agent的局限:上下文混乱(重构+测试+文档混在一起)角色冲突(既要实现又要测试)Token浪费(每步都携带全部历史)错误传播(一步错全部白费)多Agent优势:角色专注(每个Agent只做一件事)并发执行(独立任务并行)上下文隔离(互不干扰)容错性强(一个失败不影响其他)1.2 核心机制// Agent Tool - 调用入口{name:'Agent',description:'调用专门的sub-agent处理特定任务',input_schema:{subagent_type:string,// Explore/Plan/General等prompt:string,// 任务描述attachments?:File[]// 可选附件}}// Agent Definition - Agent定义interfaceAgentDefinition{agentType:string// 类型名称whenToUse:string// 使用场景描述tools?:string[]// 允许的工具disallowedTools?:string[]// 禁止的工具model?:ModelAlias// 使用的模型maxTurns?:number// 最大轮次permissionMode?:string// 权限模式getSystemPrompt:()=string// System Prompt生成器}二、3种协作模式2.1 Sub-Agent模式(同步)主Agent等待子Agent完成后继续。用户:"重构user.ts"Main Agent:1.分析任务2.调用Agent({subagent_type:"Explore",prompt:"找user.ts所有用法"})3.【等待】Explore Agent执行4.收到结果:"找到12处引用"5.基于结果制定重构计划6.执行重构实现:// src/tools/AgentTool/runAgent.tsexportasyncfunctionrunSubAgent(definition:AgentDefinition,prompt:string,parentContext:Context):Promisestring{// 1. 创建子Agent上下文constsubContext=createSubagentContext(parentContext,definition)// 2. 运行Agent Loop(阻塞)constresult=awaitquery({messages:[createUserMessage({content:prompt})],context:subContext,tools:filterTools(definition.tools,parentContext.tools)})// 3. 返回结果returnresult.finalResponse}2.2 Fork模式(异步)子Agent在后台运行,主Agent继续处理其他请求。用户:"部署到staging"Main Agent:1.调用Agent({subagent_type:"fork",prompt:"执行staging部署"})2.立即返回任务ID:"agent-abc123"3.继续处理其他用户请求[后台]Deploy Agent:运行测试 → 构建 → 部署 → 验证 完成后推送通知:task-notification.../task-notificationMain Agent:看到通知,告知用户"部署完成"关键代码:// src/tools/AgentTool/forkSubagent.tsexportfunctionbuildForkedMessages(directive:string,assistantMessage:AssistantMessage):MessageType[]{// 克隆父Agent的assistant messageconstfullAssistantMessage={...assistantMessage,uuid:randomUUID()}// 为所有tool_use创建占位符tool_resultconsttoolUseBlocks=assistantMessage.message.content.filter(b=b.type==='tool_use')consttoolResultBlocks=toolUseBlocks.map(block=({type:'tool_result',tool_use_id:block.id,content:[{type:'text',text:'Fork started — processing in background'}]}))// 构造user message: 占位符 + fork指令consttoolResultMessage=createUserMessage({content:[...toolResultBlocks,{type:'text',text:buildChildMessage(directive)}]})return[fullAssistantMessage,toolResultMessage]}// Fork子Agent的指令模板exportfunctionbuildChildMessage(directive:string):string{return`fork_boilerplate 你是forked worker process,不是主Agent。 规则: 1. 不要对话/提问/建议 2. 直接使用工具执行任务 3. 修改文件后commit 4. 最后报告结果 输出格式: Scope: 任务范围 Result: 执行结果 Key files: 相关文件 Files changed: 修改的文件+commit hash Issues: 遇到的问题 /fork_boilerplate DIRECTIVE:${directive}`}2.3 Coordinator模式(编排)主Agent作为编排者,管理多个Worker Agent协同工作。用户:"修复auth bug"Coordinator:1.并行启动研究:-Agent({desc:"调查auth bug"})-Agent({desc:"研究auth测试"})2.收到研究结果后综合分析3.启动实现:Agent({desc:"修复validate.ts:42的空指针"})4.启动验证:Agent({desc:"运行auth测试套件"})5.汇总结果返回用户Coordinator System Prompt(精简):你是coordinator,负责: - 帮助用户实现目标 - 指导workers研究/实现/验证 - 综合结果并与用户沟通 工具: - Agent - 启动新worker - SendMessage - 继续现有worker - TaskStop - 停止worker Worker能力: - 标准工具(Bash, Read, Edit, Grep等) - MCP工具 - 项目技能(/commit, /test等) 任务流程: 1. Research(并行) - Workers调查代码 2. Synthesis(你) - 理解发现,制定方案 3. Implementation - Workers执行修改 4. Verification - Workers测试验证 关键: - 并行是你的超能力,尽可能并发 - Worker结果作为task-notificationXML到达 - 必须综合研究结果,不要说"based on your findings" - 选择continue(SendMessage) vs spawn(Agent)看上下文重叠度实现:// src/coordinator/coordinatorMode.tsexportfunctiongetCoordinatorSystemPrompt():string{return`You are Claude Code, an AI assistant that orchestrates software engineering tasks across multiple workers. ## Your Role - Coordinator: direct workers, synthesize results, communicate with user - Workers handle implementation, you handle strategy ## Your Tools - Agent - spawn new worker - SendMessage - continue existing worker - TaskStop - stop running worker ## Task Workflow | Phase | Who | Purpose | |-------|-----|---------| | Research | Workers(parallel) | Investigate codebase | | Synthesis | You | Understand findings, create spec | | Implementation | Workers | Make changes | | Verification | Workers | Test changes | ## Writing Worker Prompts - Self-contained: workers can't see your conversation - Synthesize findings: include file paths, line numbers, exact changes - Never "based on your findings" - prove you understood by being specific - Add purpose statement: "This research will inform a PR description..." ## Continue vs Spawn | Situation | Use | Why | |-----------|-----|-----| | Research covered exact files needing edit | Continue | Context overlap high | | Research broad, implementation narrow | Spawn fresh | Avoid noise | | Correcting failure | Continue | Has error context | | Verifying other worker's code | Spawn fresh | Fresh eyes | Example: User: "Fix auth bug" You: [Agent({desc: "Investigate auth", prompt: "Find null pointer in src/auth/..."})] [Agent({desc: "Research tests", prompt: "Find auth test files..."})] Investigating from two angles. task-notificationFound null pointer in validate.ts:42.../task-notification You: Found the bug. [SendMessage({to: "agent-a1b", message: "Fix null pointer in src/auth/validate.ts:42. Add null check before user.id access..."})] Fix in progress.`}三、内置Agent类型3.1 Explore Agent(快速搜索)特点:只读模式(禁用Edit/Write)