当你的 AI 架构从「一个 Agent 一堆工具」进化到「多个 Agent 互相调度」Harness 的复杂度就不是线性增长而是指数跳升。你不再只是给一匹马套缰绳而是要协调一支马队——每匹马有自己的任务马与马之间要通信要防止失控要在某匹马跑飞时拉住它。Claude Code 对这个问题给出了一套工程答案AgentTool Coordinator 模式 Agent Swarms IterationBudget。今天我们从源码出发把这套多 Agent 架构彻底讲透。01 | 问题一个 Agent 撑不起复杂任务先说为什么需要多 Agent。当任务简单时单 Agent 够用一个对话循环工具调来调去最终给出答案。但当任务规模增大单 Agent 模式会撞上三堵墙第一堵墙上下文窗口想让 Agent 同时分析 20 个文件、跑 10 次测试、查询 5 个 API——你很快会遇到「max tokens exceeded」。所有的中间过程都堆在同一个 context 里到后面连模型都开始「记不住」前面的结果。第二堵墙串行等待单 Agent 模式下A 任务做完才能做 B 任务。如果 A、B 完全独立这就是白白浪费时间。实际项目里一个代码 review 任务可能分解成分析架构 → 检查安全漏洞 → 验证测试覆盖 → 检查代码风格——这四件事完全可以并行但单 Agent 只能排队。第三堵墙失败无隔离子任务崩了整个 session 就挂着。没有 fallback没有重试只有一个卡住的主循环。多 Agent 系统用三种方式解决这三堵墙上下文隔离每个子 Agent 只看到自己的任务上下文父 Agent 只接收最终结果并行执行多个子 Agent 同时工作总耗时从「各任务时间之和」降到「最长任务时间」故障隔离子 Agent 崩溃不会波及父 Agent父 Agent 可以感知失败并重试听起来很美好。但「多 Agent」本身也引入了新问题谁来调度怎么通信出错怎么处理预算怎么控制这就是 Harness 工程学要解决的。02 | 行业怎么做LangGraph / AutoGen / CrewAI 的多 Agent 方案在拆 Claude Code 的方案之前先看看业界其他成熟框架是怎么做的。LangGraph有向图调度LangGraph 用状态机 有向图来建模多 Agent 协作。每个 Agent 是图上的一个节点节点之间的边表示数据流向和执行顺序。# LangGraph 多 Agent 示意fromimportresearcherwriterreviewer# 定义边researcher → writer → reviewerresearcherwriterwriterrevisereviewerdonecompileLangGraph 的优势是流程可视化图结构天然可以画出来、调试起来清晰。限制是灵活性差图结构需要提前定义动态任务不知道要创建几个子 Agent很难处理。AutoGen对话驱动协作AutoGen 把多 Agent 协作建模成「对话」每个 Agent 是一个对话参与者通过发消息来协调工作。# AutoGen 多 Agent 对话示意fromimportcodermodelgpt-4testermodelgpt-4reviewermodelgpt-410# 最多对话 10 轮AutoGen 的强项是自然语言协调Agent 之间直接对话不需要写调度代码。弱点是难以精确控制对话走向由模型决定可能绕弯路预算难以约束。CrewAI角色分工CrewAI 把多 Agent 组织成「团队」定义角色Role、职责Goal、背景Backstory让模型自己想怎么分工。# CrewAI 角色分工示意fromimport研究员深度调研技术方案10年架构经验作者把技术内容写成易读文章技术写作专家调研 multi-agent 框架写一篇技术分析文章CrewAI 的优势是易上手几行代码就能建立多 Agent 工作流。缺点是底层控制弱内部调度是黑箱失败恢复、预算控制都不够精细。三框架对比维度LangGraphAutoGenCrewAI协调模式有向图对话角色分工灵活性中需预定义图高中可控性高低中调试难度低图可视化高中预算控制手动max_round无共同缺点这三个框架都缺乏进程级隔离。所有 Agent 跑在同一个 Python 进程里共享内存一个 Agent 崩溃可能影响全局。而且通信都走 Python 函数调用或内存队列不支持真正的并行多进程执行。Claude Code 的设计走了一条不同的路。03 | AgentTool递归子 Agent 与嵌套深度防护Claude Code 的多 Agent 入口是AgentTool。当 Claude 调用Agent(prompt修复这个 bug)时触发了一个完整的子 Agent 实例。子 Agent 的执行链路// AgentTool 执行链路src/tools/AgentTool/AgentTool.tsxAIAgentAgentToolcallAgentForkGPfilterDeniedAgentsassembleToolPoolAgentrunAgentAgentgetAgentSystemPromptqueryAgent关键设计点子 Agent 走的是完整的query()主循环不是简化版。它有独立的工具池、独立的权限上下文是一个完整的 Agent 实例——只是上下文只包含当前任务描述而不是父 Agent 的全量对话历史。递归防护两道防线最危险的场景子 Agent 也能调用 AgentTool然后孙子 Agent 再调用形成无限递归。Claude Code 用两道防线解决防线一querySource 检查运行时状态// Fork 子进程启动时标记constagent:builtin:fork// 主循环决定是否允许再次 ForkfunctioncanForkquerySource: stringbooleanreturnstartsWithagent:builtin:fork// 已经是 fork 子进程 → 拒绝再次 forkquerySource存在运行时内存里不受上下文压缩Compaction影响。防线二消息标签扫描持久化标记// Fork 子进程启动时注入标签YouDo// 主循环扫描消息历史functionisAlreadyInForkmessages: Message[]booleanreturnsomem contentincludesfork-boilerplate消息标签在上下文里是持久的即使querySource在某些边缘场景进程恢复、序列化丢失这道防线仍然有效。Harness 工程学视角这是「双保险」模式——运行时检查 持久化标记。对于不可逆的灾难性操作无限递归会把 API 额度烧穿单一防线不够两道才稳。04 | Coordinator 模式控制面与数据面的分离AgentTool 解决了「父 Agent 调子 Agent」的问题但当任务复杂到需要专门的调度逻辑时Claude Code 提供了 Coordinator 模式。核心思路Coordinator 模式的架构很清晰一个Coordinator协调者负责任务分配和决策多个Worker执行者负责具体执行两者之间通过消息协议通信。// coordinatorMode.ts 中的 Coordinator 系统提示核心摘录You are Claude Code, an AI assistant that orchestrates software engineering tasks across multiple workers.## Your RoleYou are a coordinator. Your job is to:- Help the user achieve their goal- Direct workers to research, implement and verify code changes- Synthesize results and communicate with the user- Answer questions directly when possible — dont delegate work that you can handle without toolsEvery message you send is to the user. Worker results and system notifications are internal signals, not conversation partners.这段 system prompt 定义了关键约束Coordinator 只和用户对话Worker 的结果是「内部信号」。这就是控制面和数据面的分离——Coordinator 是控制面做决策、发指令、汇报结果Worker 是数据面执行工作、产出数据。Coordinator 专属工具集// Coordinator 只有这几个工具constCOORDINATOR_TOOLSAGENT_TOOL_NAME// 派遣 Worker控制指令SEND_MESSAGE_TOOL_NAME// 给 Worker 发消息持续对话TASK_STOP_TOOL_NAME// 终止 Worker紧急停止subscribe_pr_activity// 订阅 PR 事件外部信号接收// Worker 工具集从源码提取constWORKER_TOOLSASYNC_AGENT_ALLOWED_TOOLSfiltername INTERNAL_WORKER_TOOLShas// 包括Bash、FileRead、FileEdit、MCP 工具...// 不包括TeamCreate、TeamDelete、SendMessage 等控制工具控制面工具和数据面工具完全分离Coordinator 没有执行工具Worker 没有调度工具。Worker 结果回传格式Worker 完成任务后结果通过标准化的 XML 格式回传task-notificationtask-id/task-idstatus/statussummary/summaryresult/resultusagetotal_tokens/total_tokenstool_uses/tool_usesduration_ms/duration_ms/usage/task-notification结构化 XML 而不是自由文本让 Coordinator 可以精确解析结果获取 task-id用于继续对话、状态判断成功/失败、资源消耗用于预算控制。对应 Python 生态的参考实现# Coordinator 模式的 Python 对应概念fromimportfromimportfromimportOptionalclassTaskStatusEnumpendingrunningcompletedfailedkilleddataclassclassTaskNotificationstrstrOptionalstrNoneOptionalintNoneOptionalintNoneOptionalintNoneclassCoordinator控制面只做调度和决策不执行具体工作def__init__selfselfdictstrdefspawn_workerself, task: strstr派遣 Worker返回 task_idself# 异步启动returndefon_worker_completeself, notification: TaskNotificationWorker 完成时的回调决策下一步ifselfelifselfclassWorker数据面只执行具体任务不做调度决策defexecuteself, task: strstr# 执行工具调用、代码分析、文件操作...pass05 | Agent SwarmsUDS 进程间通信实现真正并行Coordinator 模式定义了调度逻辑但「多个 Agent 怎么跑起来、怎么互发消息」是另一个工程问题。这就是Agent Swarms要解决的。为什么选 Unix Domain SocketClaude Code 的多 Agent 通信用的是Unix Domain SocketUDS不是 HTTP也不是消息队列。原因很简单通信方式延迟跨机端口冲突适合场景HTTP1-10ms✅需要端口分配微服务、跨机Unix Domain Socket0.1ms❌文件路径唯一单机进程间Redis/MQ1-5ms✅依赖中间件异步、持久化Claude Code 的场景是单机多进程并行——多个 Agent 进程跑在同一台机器上。UDS 通过文件路径寻址天然无端口冲突延迟在微秒级完全满足需求。三段式地址解析// src/utils/udsMessaging.ts — 消息寻址parseMessageAddressfunctionparseMessageAddresstarget: stringifstartsWithuds:returnschemeudstargetslice4// 直接 UDSifstartsWithbridge:returnschemebridgetargetslice7// IDE 桥接ifstartsWith/returnschemeuds// 绝对路径returnschemeother// 走 mailbox 文件系统三种路径对应三种场景uds:前缀点对点高频通信如心跳检测bridge:前缀把 Swarm 进度暴露给 VS Code/JetBrains GUI普通名称走 mailbox存储转发接收方不需要实时在线Mailbox专为 LLM Agent 设计的异步队列直接 socket 通信要求接收方实时在线但 Agent 的状态是「LLM 调用 → 工具执行 → 等待消息 → LLM 调用」的循环有大量的「忙碌中」时段。Mailbox 解耦了这个问题// mailbox 物理路径/.claude//mailbox/jsonl// 每条消息是 JSONL 格式的一行fromcoordinatortext请先分析 auth 模块的结构timestamp1718323200000readfalse// Agent 在每次 LLM 调用前注入 mailbox 新消息asyncfunctionattachTeammateMailboxcontext: ToolUseContextconstawaitreadMailboxiflength0return// 作为 system-reminder 注入当前轮 contextreturntypeusermessagecontentformatMessagesisMetatrue关键设计洞察消息不是通过独立接收线程处理而是注入 LLM context。这意味着 Agent「看到」新消息的方式和「看到」任务描述完全一致——都是上下文里的文本。不需要额外的线程消息自然融入 Agent 的思考过程。AgentId 命名规范// src/utils — makeAgentId 函数// 格式agentNameteamNamefunctionmakeAgentIdagentName: string, teamName: stringstringreturn${agentName}${teamName}// 同名 Agent 自动去重functiondeduplicateAgentNamename: string, existingNames: string[]stringifincludesreturnlet2whileincludes${name}-${counter}return${name}-${counter}// researcher → researcher-2 → researcher-3researchermy-team比 UUID 直观调试日志一眼看出是谁socket 文件路径直接从 agentId 派生不需要额外的服务发现。Python 对应实现importimportimportfromimportfromimportdataclassclassMailboxMessagestrstrintboolFalseclassAgentMailbox基于文件系统的异步消息队列def__init__self, agent_name: str, team_name: str, base_dir: str ~/.agentselfteamsmailboxf{agent_name}.jsonlselfTrueTruedefsendself, from_agent: str, text: str发送消息写入文件int1000withopenselfaas\ndefread_unreadselflist读取未读消息ifnotselfreturnwithopenselfrasforinifnotreturndefinject_to_contextselfstr将未读消息格式化为 LLM context 注入selfifnotreturnf[来自 {m.from_agent}]: {m.text}forinreturn\n06 | 迭代预算让子 Agent 不会跑飞的工程设计多 Agent 系统面临一个特有风险子 Agent 可能在一个循环里无限工作调用无数个工具烧掉大量 Token甚至在错误路径上越走越深。IterationBudget就是给每个 Agent 套上「工作上限」的工程机制。7 种 TaskType 9 字符 ID先看 Claude Code 如何精确追踪每个任务的预算消耗。// src/Task.ts — TaskType 枚举exporttypeTaskTypelocal_bash// b 前缀本地 shell 命令local_agent// a 前缀本地子 Agentremote_agent// r 前缀远程 AgentTeleport 执行in_process_teammate// t 前缀进程内协作者local_workflow// w 前缀本地工作流monitor_mcp// m 前缀MCP 流式监控dream// d 前缀AutoDream 记忆整合// ID 生成1 字符前缀 8 字符随机数 9 字符constTASK_ID_ALPHABET0123456789abcdefghijklmnopqrstuvwxyzexportfunctiongenerateTaskIdtype: TaskTypestringconstTASK_ID_PREFIXEStype// b / a / r / t / w / m / dconstrandomBytes8letforlet08TASK_ID_ALPHABETTASK_ID_ALPHABETlengthreturn// e.g. a3x7k2m9p — 一眼看出是 local_agent9 字符 ID 设计36^8 ≈ 2.8 万亿种组合足以抵抗暴力破解防止恶意 symlink 攻击前缀字母让调试日志一眼可读。这是「可读性 安全性」的双赢设计。IterationBudget 的工作机制// 每个 Agent 启动时分配独立预算interfaceAgentBudgetmaxIterationsnumber// 最大迭代次数工具调用轮次currentIterationsnumber// 已用迭代次数number// 可选最大 Token 消耗number// Coordinator 分配的预算 Token// Agent 主循环中的预算检查asyncfunctionrunWithBudgetconfig: AgentConfigPromiseAgentResultconstbudgetAgentBudgetmaxIterationsmaxIterations100// 默认 100 轮currentIterations0while// 预算检查超限则优雅终止ifcurrentIterationsmaxIterationsreturnstatusbudget_exceededmessageReached iteration limit (${budget.maxIterations}). Stopping.partialResult// 执行一轮工具调用constawaitrunOneTurncurrentIterations// 更新 Coordinator 显示的进度updateBudgetDisplayreturnstatuscompletedresult预算控制的三个层次Claude Code 的预算控制是分层的层次一IterationBudget每 Agent 独立每个 Agent 实例有独立的迭代预算防止单个子 Agent 失控。即使 Agent A 跑飞Agent B、C 仍然正常工作。层次二budgetTokensCoordinator 分配Coordinator 可以在 system prompt 里为 Worker 分配 Token 预算// coordinatorMode.ts — getCoordinatorUserContext// 当 Coordinator 设置了 budgetTokens 时注入到 Worker contextifbudgetTokens\nBudget: ~${config.budgetTokens} tokens for this task.层次三任务终态守卫防重复触发// src/Task.ts — isTerminalTaskStatusexportfunctionisTerminalTaskStatusstatus: TaskStatusbooleanreturncompletedfailedkilled// 使用场景// 1. 防止向已死亡的 teammate 注入消息// 2. 防止 finished task 重复 evict// 3. 孤儿任务清理时的状态判断这三层防护形成了一个完整的「预算护栏」单 Agent 不会无限跑IterationBudget、整体资源可控budgetTokens、终态任务不会被误操作isTerminalTaskStatus。Python 预算控制示例fromimportfromimportOptionalCallableimportdataclassclassAgentBudgetint100int0OptionalintNoneint0 propertydefiterations_remainingselfintreturnselfself propertydefis_exhaustedselfboolifselfselfreturnTrueifselfandselfselfreturnTruereturnFalseclassBudgetedAgent带预算控制的 Agent 基类def__init__self, task: str, budget: AgentBudgetselfselfselfNoneasyncdefrunselfdictwhilenotself# 预算检查ifselfreturnstatusbudget_exceedediterations_usedselfpartial_resultself# 执行一轮awaitselfself1selftokens0ifdoneselfresultbreakreturnstatuscompletedresultselfasyncdefexecute_turnselfdictraisedefis_doneselfboolreturnselfisnotNone07 | Harness 视角多 Agent 系统的三条护栏现在把所有机制综合起来从 Harness Engineering 的视角提炼出多 Agent 系统的三条护栏。护栏一深度护栏Depth Guard防止 Agent 树无限深入是多 Agent 系统最基础的安全约束。Claude Code 的实现双防线querySource运行时检查 fork-boilerplate持久化标记工程原则对于不可逆的灾难操作无限递归单一防线不够运行时状态 持久化标记 双保险防线逻辑要在 Compaction上下文压缩后仍然有效你可以这样做// 在每个 Agent 启动时检查深度functioncanSpawnSubagentcurrentDepth: number, maxDepth: number 3booleanifconsolewarn[Depth Guard] Max depth ${maxDepth} reached, blocking spawnreturnfalsereturntrue// 在 context 里传递深度信息持久化不受压缩影响constdepth1ancestorIds// ...护栏二预算护栏Budget Guard防止单个 Agent 消耗过多资源是多 Agent 系统的资源保障机制。Claude Code 的实现IterationBudget每 Agent 独立 budgetTokensCoordinator 分配 isTerminalTaskStatus终态保护工程原则预算控制要在 Agent 级别不能只在系统级别超预算时优雅终止返回部分结果而不是直接崩溃终态一旦确定不允许状态回退防止重复处理你可以这样做// 预算守卫函数包装任何 Agent 调用asyncfunctionfn() PromisebudgetnumbernumberPromiseresultnullbudgetExceededbooleanconstDatenowlet0// 通过 AbortController 实现超时constnewAbortControllerifmaxMssetTimeout() abortmaxMstryconstawaitfnreturnbudgetExceededfalsecatchifsignalabortedreturnresultnullbudgetExceededtruethrow护栏三隔离护栏Isolation Guard防止子 Agent 的失败影响父 Agent 和兄弟 Agent是多 Agent 系统的容错基础。Claude Code 的实现每个子 Agent 有独立的上下文不共享父 Agent 历史、独立的工具池、可选的独立进程tmux/iTerm2 模式工程原则上下文隔离子 Agent 只看到自己的任务不看父 Agent 历史失败隔离子 Agent 崩溃只影响当前任务父 Agent 通过task-notification感知失败并决策结果聚合父 Agent 只接收最终结果result标签不接收中间过程三条护栏的协同效果护栏防止的问题没有它会怎样深度护栏Agent 树无限深入无限递归API 额度耗尽预算护栏单 Agent 资源失控一个 Agent 跑飞烧掉全部预算隔离护栏局部失败扩散一个 Agent 崩溃整个系统挂起这三条护栏共同构成了多 Agent 系统的 Harness——不是约束 AI 的自由而是在高速公路上画出车道线让每个 Agent 快速、安全地跑完自己的任务。总结这一篇我们从源码深度拆解了 Claude Code 的多 Agent 架构。核心设计回顾AgentTool子 Agent 用完整的query()引擎运行上下文独立工具池独立。递归防护用双防线运行时querySource 持久化fork-boilerplate标签。Coordinator 模式控制面Coordinator只做调度数据面Worker只做执行。工具集严格分离结果通过标准化task-notificationXML 格式回传。Agent Swarms UDS单机多进程并行Unix Domain Socket 实现微秒级进程间通信。Mailbox 异步队列解耦发送方和接收方消息注入 LLM context 而不是走独立线程。IterationBudget每 Agent 独立预算 Coordinator 全局 Token 分配 终态守卫函数。三层防护让预算可控、状态可追踪。TaskType 9字符ID7种任务类型前缀字母让日志一眼可读36^8 的组合空间保证安全性。Harness 工程学总结多 Agent 系统的三条护栏——深度护栏防无限递归、预算护栏防资源失控、隔离护栏防失败扩散。这三条护栏不是限制 AI 的能力而是确保 AI 的能力可以被可靠地发挥。学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】