Claude Code 是怎么跑起来的：从 Agent Loop 理解代理循环实现

如果你已经会调用大模型、也知道 tool calling 和 agent 的基本概念那接下来最值得看的问题通常不是“怎么再包一层 prompt”而是一个真正能跑任务的 agent到底是怎么在代码里运转起来的。这篇文章不从抽象定义讲起而是直接从 Claude Code 的实现思路切入拆解它最核心的一条执行主线Agent Loop。1. 什么是 Agent Loop一句话Agent Loop是让模型从“一次回答”升级为“持续决策系统”的控制循环。你可以把它理解成一个回合制 runtime每一回合都做同样的事情读取当前上下文调用模型生成动作意图如果有工具调用就执行工具把工具结果写回上下文判断是否进入下一回合。这个循环停止时系统才真正产出“任务完成态”的结果而不是中间状态。2. 最小可用模型先跑通闭环先看一个最小版本letmessages[userMessage];while(true){constassistantawaitcallModel(messages);messages.push(assistant);consttoolUsesextractToolUseBlocks(assistant);if(toolUses.length0){break;}consttoolResultsawaitrunTools(toolUses);messages.push(...toolResults);}returnbuildFinalAnswer(messages);这段代码虽然简单但已经包含了 agent 的本质状态是累积的不是每次从零思考决策是迭代的不是一轮生成定生死外部世界可进入推理链工具结果会回流给模型。如果你只能记住一个原则就是这个工具结果不是“展示给用户就完了”而是“下一轮推理输入”。3. 真实实现的主流程在工程实现里Agent Loop 一般会拆成“外层编排 内层循环 模型流式适配”三层是否Orchestrator会话编排Agent Loop回合循环Model Stream流式消息是否出现 tool_use?执行工具并产出 tool_result结束循环并输出结果这种分层有个明显好处你可以在不改核心循环逻辑的前提下替换模型供应商、切换工具执行策略或者接入远端会话。这句话可以拆开理解。核心循环真正关心的其实只有几件事当前消息上下文是什么这一轮模型产出了什么事件有没有tool_use工具结果什么时候回流当前任务是否应该继续下一轮。也就是说Agent Loop关心的是“控制流程”而不是某个具体实现细节。比如如果你把底层模型从 Anthropic 换成 OpenAI只要新的模型适配层仍然能把输出整理成统一的消息事件流循环本身就不需要重写。如果你把工具执行从“串行执行”换成“并发执行”或“流式执行”只要工具结果最终还是按统一格式回到消息链循环判断逻辑也不用变。如果你把运行方式从“本地单进程”换成“远端 agent 会话”只要远端返回的消息还能被还原成同一套 assistant、tool result、status 事件循环依然可以照常推进。所以这层设计的关键价值是“隔离变化”上层编排器负责会话和运行环境中间的 Agent Loop 负责任务推进下层适配器负责模型协议、工具协议、远端通信。这样一来变化最多的部分被压到了外围最核心的循环本身反而能保持稳定。4. 一个回合是怎么结束的Claude Code 如何做健壮收口这一节其实只想说明一个核心点在 Claude Code 里“这一轮没有新的工具调用了”并不等于“立刻结束”。真正的逻辑是先看这一轮是否还需要 follow-up如果不需要也不会马上返回系统会先尝试几条恢复路径只有恢复都失败了才真正结束这一轮。先看续轮判断本身。在query.ts里Claude Code 还是会先根据消息内容里的真实tool_use来设置needsFollowUp// query.tsconsttoolUseBlocks:ToolUseBlock[][];letneedsFollowUpfalse;constmsgToolUseBlocksmessage.message.content.filter(contentcontent.typetool_use,)asToolUseBlock[];if(msgToolUseBlocks.length0){toolUseBlocks.push(...msgToolUseBlocks);needsFollowUptrue;}但关键在后面。Claude Code 的健壮性不在于它会判断needsFollowUp而在于它在!needsFollowUp时不会立刻退出而是先检查“这次能不能修一修再继续跑”。把这一段抽象后可以写成下面这样// src/query.ts - 简化后的退出/恢复逻辑if(!needsFollowUp){constlastMessageassistantMessages.at(-1);// 恢复路径 1: Prompt 太长 - 尝试上下文折叠if(isPromptTooLongMessage(lastMessage)){constdrainedcontextCollapse.recoverFromOverflow(messages);if(drained.committed0){state.messagesdrained.messages;continue;}// 恢复路径 2: 响应式压缩if(!state.hasAttemptedReactiveCompact){constcompactedreactiveCompact(messages);state.messagescompacted;state.hasAttemptedReactiveCompacttrue;continue;}}// 恢复路径 3: max_tokens 截断 - 增加 token 预算if(lastStopReasonmax_tokens){state.maxOutputTokensOverridecurrentLimit*2;state.maxOutputTokensRecoveryCount;continue;}// 真正退出return{reason:end_turn};}这段逻辑最值得注意的地方是连续的三个continue。它说明 Claude Code 对“结束”这件事的态度不是保守退出而是优先恢复如果是 prompt 太长先尝试上下文折叠折叠不够再尝试响应式压缩如果是输出被 token 上限截断再提高 token 预算重试只有这些恢复路径都走不通才真正返回end_turn。所以这一节真正想表达的就是一句话在 Claude Code 里一个回合结束不是“没工具了就退出”而是“没工具了之后先把能恢复的情况恢复掉恢复不了才结束”。这就是它和普通 demo 的差别。demo 往往只会判断“继续还是退出”而 Claude Code 还多做了一层“退出前恢复”因此在长上下文、输出截断这类真实问题面前循环不会轻易中断。5.queryLoop才是真正的发动机它的流式输出是“按消息块”推进的如果说 Agent Loop 的概念骨架是while (true)那真正让 Claude Code 跑起来的是queryLoop这种“边接收、边判断、边产出”的实现方式。这里有一个很值得讲清楚的点Claude Code 的流式不是很多人想象中的“逐字打印”。它更接近一种“按消息块、按事件块”的流式。也就是说系统不是每生成一个字就立刻往外吐一次而是随着模型流中的事件推进不断yield message。这个差别很重要因为它直接影响你怎么理解queryLoop。5.1 为什么yield message就等于流式输出理解 Claude Code 的流式最好的方式不是只看一层代码而是看它怎么“一层一层往外yield”。先看里面这一层也就是queryLoop。它一边跑 Agent Loop一边把每轮里从模型拿到的消息往上抛// src/query.tsasyncfunction*queryLoop(params:QueryParams,):AsyncGeneratorStreamEvent|Message,Terminal{while(true){forawait(constmessageofqueryModel(state.messages,systemPrompt,tools,signal,)){yieldmessage;}// ---- 步骤 2: 检查是否需要继续 ----if(!needsFollowUp){return{reason:end_turn};}// ---- 步骤 3: 执行工具收集结果 ----// ---- 步骤 4: 追加工具结果到消息列表 ----// ---- 步骤 5: 回到步骤 1 ----state.turnCount;}}这说明第一层流式非常直接queryModel()持续产生消息queryLoop()就持续yield message。所以对queryLoop来说流式的本质就是“这轮里有什么消息到达我就继续往上一层送什么消息”。再看外面这一层也就是QueryEngine。它接收用户输入把消息放进跨轮次保存的mutableMessages然后继续消费内部的query()再把内部消息流转成对外消息流// src/QueryEngine.tsexportclassQueryEngine{// 跨轮次持久化的消息列表 —— 这就是教学版的 messages[]privatemutableMessages:Message[]privateabortController:AbortControllerprivatetotalUsage:NonNullableUsage// 入口用户输入进来响应消息流出去async*submitMessage(prompt:string|ContentBlockParam[],options?:{uuid?:string;isMeta?:boolean},):AsyncGeneratorSDKMessage,void,unknown{// 1. 处理用户输入const{messages:messagesFromUserInput}awaitprocessUserInput({...})this.mutableMessages.push(...messagesFromUserInput)// 2. 调用核心查询循环forawait(constmessageofquery({messages:[...this.mutableMessages],tools:this.tools,systemPrompt:this.systemPrompt,...})){// 3. 累积消息并持久化if(message.typeassistant){this.mutableMessages.push(message)yield*normalizeMessage(message)}}}}这样一来整条链路就清楚了queryModel()先在最底层按事件产生消息queryLoop()在每一轮里把这些消息yield出来QueryEngine.submitMessage()再把内部消息流继续yield给外部。所以 Claude Code 的“流式”本质上不是某一层单独在流而是异步生成器在层层传递消息。可以用一张图先把这条链路记住queryModel底层模型事件流queryLoop按轮次处理并 yield messageQueryEngine.submitMessage消费内部消息流并继续 yieldUI / SDK接收对外消息流很多人以为“流式”就一定是 token 级别的逐字显示但 Claude Code 这类 runtime 通常不会直接把最底层 token 流暴露给最外层逻辑。原因是 runtime 真正要处理的不只是文本还有很多结构化信息assistant messagestream eventtool usetool resultprogressstatusresult这些东西本身就不是“一个字一个字”的概念而是分段、分块、分事件到达的。所以更准确地说Claude Code 的流式是LLM 底层协议是更细粒度的事件流中间层把这些事件整理成可消费的消息块queryLoop再把这些消息块持续yield给外层。这就是为什么你会感觉它是“一段一段出来”而不是终端里那种纯文本逐字打印。6.QueryEngine是外层编排器它不负责思考但负责把循环组织起来理解完queryLoop之后再看QueryEngine会更清楚。queryLoop是发动机但发动机本身并不负责整辆车的所有事情。Claude Code 还需要有一个更外层的组件把会话、消息记录、结果聚合、状态同步这些事情组织起来这就是QueryEngine这类角色存在的意义。你可以把它理解成“外层编排器”。它通常不直接决定模型这一轮该不该调工具也不直接决定工具参数是什么。那些都是 loop 内部和模型共同完成的事情。QueryEngine更关心的是这次查询从哪里开始初始消息怎么组装流式过程中哪些消息要记录哪些中间消息要回放给 UI 或 SDK本轮结束后最终结果应该如何包装返回会话级别的 usage、cost、turn count 如何累计。这件事在源码里也非常直观。QueryEngine一开始维护的就是一批会话级状态// QueryEngine.tsexportclassQueryEngine{privatemutableMessages:Message[];privateabortController:AbortController;privatepermissionDenials:SDKPermissionDenial[];privatetotalUsage:NonNullableUsage;privatereadFileState:FileStateCache;}进入一次查询之后它会继续跟踪这次会话的关键统计// QueryEngine.tsletcurrentMessageUsage:NonNullableUsageEMPTY_USAGEletturnCount1letlastStopReason:string|nullnullforawait(constmessageofquery({...})){// 消费 query() 产出的消息并累计 usage / turn / stop_reason}最后再把这些状态收束成对外返回的 result// QueryEngine.tsyield{type:result,subtype:error_max_budget_usd,duration_ms:Date.now()-startTime,num_turns:turnCount,stop_reason:lastStopReason,total_cost_usd:getTotalCost(),usage:this.totalUsage,}这里虽然展示的是一个具体错误分支但它已经足够说明QueryEngine的职责它负责把 loop 过程中分散产生的状态最后整理成一个完整、统一、可返回的结果对象。也就是说QueryEngine解决的是“这一整次交互怎么被托管”而queryLoop解决的是“这一轮又一轮怎么往前跑”。6.1 为什么要有这一层如果没有QueryEngine这一层很多原本应该属于“会话级”的工作就会被硬塞进 loop 里比如transcript 持久化历史消息回放result 聚合session 级别统计UI/SDK 的输出适配。这样一来queryLoop会越来越胖最后既要管控制流又要管存储又要管展示维护成本会非常高。把QueryEngine单独拉出来之后职责边界就清楚了QueryEngine负责托管整次查询queryLoop负责推进 agent 回合更底层的 model adapter 负责协议流工具执行器负责工具生命周期。这正是前面提到的“隔离变化”的具体体现。7. 结语如果只用一句话总结这篇文章我会说Claude Code 的 Agent Loop本质上是一套围绕“消息流”组织起来的运行时。前面几节其实都在说明这件事只是从不同层次切进去在第 4 节里我们看到一个回合并不是“没工具了就退出”而是会先尝试恢复恢复不了才真正结束在第 5 节里我们看到所谓流式输出并不是单层函数在打印文本而是queryLoop和QueryEngine两层异步生成器在层层yield在第 6 节里我们又看到QueryEngine如何把这些分散的中间状态组织成一整次可托管、可返回的查询过程。把这些点连起来看Claude Code 其实回答了一个很实际的问题一个 agent 为什么能持续跑下去而且还能在复杂情况下不轻易跑崩答案不是“它 prompt 写得更好”而是它把消息、回合、恢复和对外输出组织成了一套清晰的 runtime 结构。所以读完这篇文章之后最值得带走的并不是某个具体函数名而是这条主线queryLoop负责把一轮一轮的 agent 行为跑起来QueryEngine负责把这套循环托管成一次完整交互整个系统通过消息流把模型输出、工具结果和最终结果串成同一条链路。当你理解了这一点再回头看 Claude Code就会发现它真正厉害的地方不是“会调用工具”而是它把 agent 的执行过程做成了一个稳定、连续、可恢复的运行时。