Agent Loop 是 Claude Code 的
「心脏」—— 它如何把
"模型 + 工具 + 错误恢复"编成一台状态机？

01Agent Loop 是什么

一句话定义：接收用户输入 → 调模型 → 执行模型请求的工具 → 把工具结果反馈给模型 → 循环， 直到模型产出最终响应（不再调用工具）。这种"模型生成 — 工具执行 — 结果反馈"的迭代结构，是所有 Agent 框架的本质。

1.1 两层架构

Agent Loop 由两层组成：外层编排负责会话级的 IO 与状态管理；内层循环负责单次提交内的模型/工具往返。

1.2 五条核心设计原则

02QueryEngine · 外层编排器

QueryEngine 是会话生命周期的拥有者，持有跨 turn 的累积状态。 它把"用户敲下一条消息"翻译成"驱动 query() 跑完一整个回合"。

2.1 类内部结构

export class QueryEngine {
  private config: QueryEngineConfig           // 不可变配置
  private mutableMessages: Message[]          // 跨 turn 累积的消息
  private abortController: AbortController     // 中断控制
  private permissionDenials: SDKPermissionDenial[]  // 权限拒绝记录
  private totalUsage: NonNullableUsage          // 累计 token 用量
  private readFileState: FileStateCache         // 文件读取缓存
  private discoveredSkillNames: Set<string>     // 已发现技能
  private loadedNestedMemoryPaths: Set<string>  // 已加载嵌套记忆
}

2.2 submitMessage 的七步处理流程

图 2.1 · submitMessage 七步流程

2.3 关键细节 · Transcript 为什么必须预写？

2.4 流式消息分发 · query() 输出的 7 种 message.type

2.5 compact_boundary 的双重裁剪

当 query() 产出 compact_boundary 系统消息时，QueryEngine 同步裁剪两套消息引用：

03queryLoop · 内层状态机

这是 Agent Loop 的真正心脏。一个 while(true)， 每轮按 7 个阶段顺序执行。任何错误恢复都不递归 —— 而是更新 state 后 continue。

3.1 query() 是 queryLoop() 的薄包装

export async function* query(params: QueryParams) {
  // 创建/复用 Langfuse trace（可观测性）
  const langfuseTrace = params.toolUseContext.langfuseTrace
    ?? (isLangfuseEnabled() ? createTrace({...}) : null)
  const paramsWithTrace = ...

  try {
    yield* queryLoop(paramsWithTrace, consumedCommandUuids)  // ← 委托
  } finally {
    if (ownsTrace) endTrace(...)  // 保证 trace 被关闭
  }
}

3.2 State · 跨迭代的可变状态

3.3 八种状态转换 · transition 类型一览

3.4 单轮迭代的 7 个阶段

下方是 queryLoop 的核心心智模型。每轮迭代严格按 Phase 0 → Phase 7 顺序执行。

3.5 七阶段流程图

图 3.1 · queryLoop 单轮迭代的 7 个阶段

04模型调用阶段详解

Phase 2 是 queryLoop 中最复杂的阶段。它不仅要把 messages / systemPrompt 发给 API， 还要处理流式响应、并行启动工具执行、识别可恢复错误、做流式 fallback。

4.1 callModel 参数构建

deps.callModel({
  messages: prependUserContext(messagesForQuery, userContext),  // ← 注入用户上下文
  systemPrompt: fullSystemPrompt,                                // ← 已含 systemContext
  thinkingConfig: toolUseContext.options.thinkingConfig,        // adaptive | disabled
  tools: toolUseContext.options.tools,
  signal: toolUseContext.abortController.signal,
  options: {
    model: currentModel,                // 可能被 fast mode 切换
    fallbackModel,                       // 主模型不可用时切换目标
    isNonInteractiveSession,
    querySource,                          // repl_main_thread | sdk | compact | agent:* ...
    agents: activeAgents,
    maxOutputTokensOverride,             // 升档时设为 64k
    taskBudget: { total, remaining },    // API 侧整轮预算感知
    langfuseTrace,
  },
})

4.2 流式响应的事件流

图 4.1 · 流式响应 + 流式工具执行（StreamingToolExecutor）

4.3 withheld 机制 · 错误暂缓暴露

let withheld = false

// context-collapse 的 PTL 恢复
if (contextCollapse?.isWithheldPromptTooLong(message, ...)) {
  withheld = true
}

// reactive compact 的 PTL/媒体错误恢复
if (reactiveCompact?.isWithheldPromptTooLong(message)) {
  withheld = true
}

// 媒体尺寸错误恢复
if (mediaRecoveryEnabled && reactiveCompact?.isWithheldMediaSizeError(message)) {
  withheld = true
}

// max_output_tokens 恢复
if (isWithheldMaxOutputTokens(message)) {
  withheld = true
}

if (!withheld) {
  yield yieldMessage  // 正常暴露给 SDK
}
// withheld 的消息仍推入 assistantMessages，供 Phase 4 恢复判断使用

4.4 流式 Fallback · 主模型不可用时切换

图 4.2 · 流式 Fallback 完整流程

05工具执行 · 并发安全 vs 串行

Phase 5 处理工具执行。两种模式（流式 vs 批量），两种并发（安全 vs 非安全），一种铁律： tool_use 与 tool_result 必须严格配对，否则 API 报协议错误。

5.1 两种执行模式

5.2 工具批次划分 · partitionToolCalls

工具按"并发安全性"划分批次。规则简单：

5.3 单工具执行流程

图 5.1 · 单工具执行流程（含权限三态判定）

5.4 协议铁律 · tool_use / tool_result 必须配对

// 中断时补齐合成 tool_result，保证下次调用合法
yieldMissingToolResultBlocks(toolUseBlocks, completedResults)

// fallback 时也要丢弃旧 tool_use_id，避免孤儿 result 混入
streamingToolExecutor.discard()  // 进行中的工具收到合成错误结果

06上下文压缩 · 四层递进

每轮调用模型前，Phase 1 按"先轻后重"的顺序执行五道压缩工序。 前面几道便宜（裁剪/cache 编辑），最后才是昂贵的"摘要重建"。

6.1 五道工序流水线

图 6.1 · 上下文压缩五道工序（颜色由轻到重）

6.2 五种压缩详解

6.3 为什么是这个顺序？

6.4 compact 后消息重建

const postCompactMessages = buildPostCompactMessages(compactionResult)
// 包含：
//   - compact_boundary 系统消息（标记裁剪点）
//   - 摘要消息（assistant 摘要历史）
//   - 附件消息
//   - hook 结果消息

messagesForQuery = postCompactMessages
// 旧消息被完全替换，不再保留在内存中
// QueryEngine.mutableMessages 也同步裁剪

07错误恢复 · "先轻后重"策略

Phase 4 是 Agent Loop 最复杂的部分。queryLoop 不会立刻让 SDK 看到错误 —— 它会先在自己内部尝试 1~3 次恢复，恢复成功就 continue，失败才暴露。

7.1 错误恢复总表

7.2 PTL 恢复链 · "先轻后重"的典范

7.3 max_output_tokens 恢复链

图 7.1 · max_output_tokens 恢复链（升档 + 续跑双策略）

7.4 thinking 块的硬约束

08Stop Hooks · 模型说完之后还要做什么

当模型产出最终响应（needsFollowUp=false）且不是 API 错误时，handleStopHooks 触发。 这是会话结束前的"清理 + 增强"环节 —— 记忆提取、prompt 建议、auto-dream、外部 hook。

8.1 Stop Hooks 执行内容

图 8.1 · Stop Hooks 五步流程

8.2 三个后台书签任务

8.3 阻塞机制 · stop hook 如何让循环再跑一轮

09附件注入 · 时机与策略

附件注入发生在 Phase 6，时机至关重要 —— 必须在工具执行完成之后、 下一轮迭代之前。这个顺序由 API 协议约束决定。

9.1 为什么必须在工具结果之后注入？

9.2 七种附件类型

9.3 记忆预取的"异步消费"策略

// queryLoop 入口启动（异步，不阻塞）— 注意 using 关键字
using pendingMemoryPrefetch = startRelevantMemoryPrefetch(...)

// 在 Phase 6 工具执行完成后尝试消费
if (
  pendingMemoryPrefetch.settledAt !== null &&  // 预取已完成
  pendingMemoryPrefetch.consumedOnIteration === -1  // 尚未消费
) {
  const memoryAttachments = filterDuplicateMemoryAttachments(
    await pendingMemoryPrefetch.promise,
    toolUseContext.readFileState,  // 过滤模型已读/写过的记忆
  )
  // 注入为附件
  pendingMemoryPrefetch.consumedOnIteration = turnCount - 1
}

10Token Budget · 双重预算

Claude Code 有两套并行的"预算"机制 —— 一个本地控制何时让模型续跑，一个发给 API 让模型自己感知整体预算。

每轮结束后检查 token 使用
  ├── action: 'continue'
  │   ├── 注入 nudgeMessage
  │   ├── incrementBudgetContinuationCount
  │   └── continue → token_budget_continuation
  └── action: 'complete'
      ├── diminishingReturns=true → 提前停止
      └── return { reason: 'completed' }

taskBudget: {
  total: number,      // 整轮预算
  remaining: number,  // 剩余预算（compact 后补偿）
}

11关键细节 · 你可能不知道的

本节是阅读源码的"通关秘籍"。这些设计不写出来很难看出来，写出来后会让你恍然大悟"原来是这样"。

11.1 双轨制消息：mutableMessages vs messages

11.2 processUserInput 被调用两次

看起来奇怪，但有原因：

• 第一次：允许 setMessages 回写 —— slash 命令可以改写消息数组（如 /compact 加边界标记）。
• 第二次：setMessages: () => {} —— 不再允许命令改写消息，避免多源修改导致状态漂移。

11.3 assistant 写盘 · 唯一的 fire-and-forget

if (message.type === 'assistant') {
  void recordTranscript(messages)  // ⚠️ 不 await！
} else {
  await recordTranscript(messages)
}

11.4 StreamingToolExecutor.discard 的清理逻辑

// 流式 fallback 发生时
streamingToolExecutor.discard()              // 标记已丢弃
streamingToolExecutor = new StreamingToolExecutor(...) // 重建

// discard 的效果：
//   - 排队的工具不再启动
//   - 进行中的工具收到合成错误 tool_result
//   - 避免旧 tool_use_id 的孤儿结果混入重试

11.5 backfillObservableInput · 路径回填

某些工具的输入字段是"可观察但不可序列化"的（如相对路径展开为绝对路径）：

if (tool?.backfillObservableInput) {
  const inputCopy = { ...originalInput }
  tool.backfillObservableInput(inputCopy)
  // 仅在"新增字段"时才产出克隆消息
  // 纯覆盖场景跳过，避免破坏 transcript VCR 哈希
}

11.6 消息队列的代理作用域

消息队列是进程级单例，主协调器与子代理共享：

这避免了子代理意外消费主线程的用户 prompt。

11.7 compact_boundary 的双重写入

11.8 硬阻塞阈值预检的三个豁免

自动 compact 关闭时，queryLoop 在 API 调用前会做硬阻塞预检。但下列场景豁免：

1. compact/snip 刚执行后 —— usage 读数仍是旧窗口，预检会误拦截。
2. compact / session_memory 分叉代理 —— 在此阻塞会自锁。
3. reactive compact / context-collapse 已启用 —— 不应在 API 前合成错误，否则真实 413 恢复链路拿不到触发点。

11.9 QueryDeps · 为什么只有 4 个钩子

export type QueryDeps = {
  callModel: typeof queryModelWithStreaming
  microcompact: typeof microcompactMessages
  autocompact: typeof autoCompactIfNeeded
  uuid: () => string
}

11.10 using 关键字 · ES2025 显式资源管理

using pendingMemoryPrefetch = startRelevantMemoryPrefetch(...)
// 离开作用域时自动调用 [Symbol.dispose]()
// 替代了传统的 try-finally 手动清理
// 保证 AsyncGenerator 在所有退出路径都正确释放资源

11.11 querySource 的六种值与差异行为

11.12 Terminal 的十种终止原因

12完整示例 · 单轮对话全程

最后用一条具体消息把所有概念串起来。场景：用户输入 "帮我分析这个文件"， 模型决定先 Read 文件再回答。这是一个典型的双 API 调用会话。

图 12.1 · 单轮对话的完整时序（双 API 调用，含 Read 工具）

12.1 数据视角的全程

12.2 最终返回给 SDK 的 result 对象

{
  type: 'result',
  subtype: 'success',
  result: "这个文件实现了 XXX 功能...",
  usage: {
    input_tokens: 12500,
    output_tokens: 320,
    cache_read_input_tokens: 11800,  // 第二轮命中前缀缓存
    cache_creation_input_tokens: 0,
  },
  total_cost_usd: 0.024,
  duration_ms: 3420,
  num_turns: 2,
}

13核心源码文件索引

想自己读源码？以下是按职责分类的关键文件清单。建议从 QueryEngine.ts 开始， 然后顺着 query() 调用链进入 queryLoop。

建议的阅读路径