Agent任务生产排障别只靠日志：Checkpoint Replay是底座

上周帮一个团队排查 Agent 的线上问题，又听到了那句再熟悉不过的话：

这句话释放的信号其实很明确：Agent 已经从“能跑就行”的 demo 阶段，正式迈入了“跑出问题怎么办”的生产阶段。在 demo 阶段，日志能回答“程序有没有跑”；到了生产阶段，日志最多能回答“它大概发生过什么”。真正让人头疼的问题，一个比一个棘手：

• 用户明明问的是 A，Agent 为什么偏偏去检索了 B？
• 工具返回了一个边界值，模型为什么没有嗅到异常、继续追问？
• 第三步失败了，重试时为什么把第一步已经执行的外部操作又做了一遍？
• 人工确认前后，Agent 的内部状态是否一致？
• 修完 prompt 或工具 schema 后，旧的坏案例能不能稳定地复现并验证？

如果这些问题全靠翻日志、拼上下文、手动构造请求来猜测，那系统迟早会沦为“玄学服务”。一个很明确的判断是：Agent 生产化的真正分水岭，不是有没有 tracing，而是有没有 checkpoint replay。

这里的 checkpoint replay 并非一个沉重的平台概念。可以先把它理解成：在 Agent 执行的关键节点，记录下足够完整、结构化且可校验的状态快照；当线上出现异常时，能把某个运行过程恢复到指定步骤，以“只读 / mock / 幂等保护”的方式重新执行，完整复现当时的决策链条。

这篇文章不打算空谈理念，直接聚焦工程落地：哪些状态必须存，哪些东西不能重放，如何用一个轻量级的 Node.js 实现把日志升级为 checkpoint replay，以及团队如何按一周、一个月、一个季度的节奏逐步落地。

先把四个概念分清：trace、checkpoint、replay、store

很多团队说自己“有观测”，实际上不过是将几段零散的日志打到了某个平台。在 Agent 场景里，至少需要区分清楚四层东西：

LangGraph 的文档把 checkpointer 和 store 区分得很清楚：checkpointer 负责持久化单个 thread 的图状态，适用于会话连续性、人类介入、time tra vel 和 fault tolerance；store 则用于跨 thread 的长期数据。这个区分很关键，因为生产事故大多发生在“一个 run 内部的状态演化”过程中，而不是长期记忆本身。

Trace 工具当然也很重要。LangSmith、Langfuse 这类平台能帮你看到调用链、模型输入输出、评估指标和 prompt 版本等信息。问题是：trace 更像录像，checkpoint replay 更像存档点。录像只能回放，存档点却能让你回到现场再做一次实验。

Agent 的复杂性就在这里：一次执行中，既有概率性的模型调用，也有确定性的工具调用，还夹杂着外部系统的副作用。只靠看录像，很难验证“如果改了工具 schema，这个坏案例会不会修好”；有了 checkpoint，才能把修复变成一次可执行的回归测试。

为什么“只存日志”在 Agent 场景会失效

传统后端服务排障时，日志、指标和 trace 已经能覆盖绝大多数问题。请求来了，代码路径相对确定，数据库状态可查，重试语义也可控。但 Agent 服务多了三类不确定性。

第一类是上下文不确定性。模型看到的并非用户的原始输入，而是一大坨动态拼装后的上下文：系统规则、历史消息、检索片段、工具列表、权限、预算、临时策略。日志里如果只记录“用户问了什么”和“模型答了什么”，中间最关键的 prompt 组装过程就彻底丢失了。

第二类是决策不确定性。Agent 的每一步并不都由业务代码决定。它可能先规划、再调用工具、再根据结果修正计划。一次错误的工具调用，原因可能不在工具本身，而是上一轮模型输出中隐藏的错误假设。

第三类是副作用不确定性。Agent 调用的工具越来越接近真实业务：发消息、建工单、改配置、查账单、触发工作流。失败后直接“再跑一遍”，可能造成重复操作；不跑又无法复现现场。

所以，只存日志会出现三个断点：

1. 上下文断点：不知道模型当时完整看到了什么。
2. 状态断点：不知道每一步执行后 Agent 内部变量如何变化。
3. 副作用断点：不知道哪些外部动作已经真实发生，哪些只是准备发生。

Checkpoint replay 要补的，正是这三个断点。

一个最小可用的 checkpoint 长什么样

建议不要一上来就追求“全量录制一切”。最小可用 checkpoint 只需要覆盖 7 类字段：

type AgentCheckpoint = {runId: string;stepIndex: number;threadId: string;nodeName: string;createdAt: string;versions: {agentVersion: string;promptVersion: string;toolSchemaVersion: string;modelRoute: string;policyVersion: string;};input: {userMessageHash: string;messages: Array<{ role: string; content: string }>;retrievedContext?: Array<{ id: string; source: string; textHash: string; text?: string }>;};state: {plan?: unknown;scratchpad?: unknown;variables: Record<string, unknown>;budget: { maxSteps: number; usedSteps: number; maxTokens?: number; usedTokens?: number };};toolCall?: {name: string;arguments: unknown;argumentsHash: string;idempotencyKey?: string;sideEffectLevel: 'none' | 'read' | 'write' | 'external';};toolResult?: {ok: boolean;resultHash: string;resultPreview?: unknown;errorType?: string;latencyMs?: number;};replay: {mode: 'live' | 'mock' | 'dry-run';canResumeFromHere: boolean;unsafeReasons?: string[];};};

这里面有几个字段容易被低估。

versions 必须存。Agent 出坏案例，很多时候不是“模型突然变笨了”，而是 prompt、工具 schema、路由策略、权限策略中有一个发生了变化。没有版本信息，你根本无法判断一次 replay 的差异源自修复，还是源自环境漂移。

retrievedContext 最好既存 hash，在合规允许的情况下也存文本快照。只存文档 ID 是不够的，因为知识库内容可能已经更新。排查的是“当时为什么错”，而不是“现在看起来应该怎样”。

sideEffectLevel 是 replay 安全的核心。读操作可以 live replay；写操作默认只能 mock 或 dry-run；外部不可逆动作则必须要求人工确认或幂等键保护。

canResumeFromHere 不要自动推断，应该由节点显式声明。有些节点天然可恢复，比如“根据已保存的工具结果继续总结”；有些节点不应恢复，比如“已经发出外部付款请求但确认状态不明”。

可重放边界：别把 replay 做成事故放大器

Checkpoint replay 最大的坑，是把“复现”误做成了“重新执行一遍”。Agent 系统里，重放必须按边界分层。

1. 模型调用：记录输入，允许替换输出

模型调用本身可以 replay，但要区分两种模式：

• exact replay：使用当时保存的模型输出，不再调用模型，用于复盘状态机和工具链。
• regression replay：用新的 prompt / schema / model route 再调用一次，用于验证修复效果。

两者都需要同一个 checkpoint，但目的完全不同。exact replay 回答的是“当时系统为什么走到这里”；regression replay 回答的是“现在是否还会犯同样错误”。不要混在一起。

2. 工具读操作：可以 live，但要记录环境

例如搜索、数据库查询、读取工单详情。这类操作理论上可重放，但数据源会随时间变化。因此 checkpoint 至少要保存 result hash 和必要的 preview。排障时，如果 live replay 的结果 hash 和当时不同，系统应提示“外部数据已漂移”，而不是把这种差异算成模型修复的功劳。

3. 工具写操作：默认 mock，除非有幂等键

例如创建工单、发送通知、更新配置。这类操作绝对不能直接重放。正确的做法是：

• 记录 idempotencyKey；
• 记录请求 hash；
• 记录外部系统返回的 envelope；
• replay 时默认返回已保存的 toolResult；
• 只有在沙箱环境或显式 dry-run endpoint 下，才允许重新调用。

这和支付系统、消息系统的思路很像：外部副作用必须有幂等和状态查询能力，否则重放只会制造新的事故。

4. 人工确认：确认本身也是状态

很多 Agent 系统有 human-in-the-loop，但只把它当成一个 UI 弹窗。在生产中，人工确认点应该进入 checkpoint：确认人、确认时间、确认前状态 hash、确认后的策略、允许执行的动作范围。否则你会遇到一个很麻烦的问题：事故发生后，没人说得清“人当时到底确认了什么”。

参考实现：用 SQLite 做一个轻量 checkpoint recorder

下面给一个最小 Node.js 版本的实现。它不依赖某个 Agent 框架，适合直接塞进现有服务里先跑起来。生产环境可以把 SQLite 换成 Postgres，结构不变。

import crypto from 'node:crypto';import Database from 'better-sqlite3';export type SideEffectLevel = 'none' | 'read' | 'write' | 'external';export type CheckpointInput = {runId: string;threadId: string;stepIndex: number;nodeName: string;versions: Record<string, string>;input: unknown;state: unknown;toolCall?: {name: string;arguments: unknown;idempotencyKey?: string;sideEffectLevel: SideEffectLevel;};toolResult?: unknown;replay?: {canResumeFromHere: boolean;unsafeReasons?: string[];};};function sha256(value: unknown) {return crypto.createHash('sha256').update(JSON.stringify(value)).digest('hex');}export class CheckpointStore {private db: Database.Database;constructor(file: string) {this.db = new Database(file);this.db.exec(`create table if not exists agent_checkpoints (run_id text not null,thread_id text not null,step_index integer not null,node_name text not null,created_at text not null,versions_json text not null,input_json text not null,state_json text not null,tool_call_json text,tool_result_json text,replay_json text not null,state_hash text not null,primary key (run_id, step_index));create index if not exists idx_agent_checkpoints_threadon agent_checkpoints(thread_id, created_at);`);}sa ve(cp: CheckpointInput) {const replay = cp.replay ?? { canResumeFromHere: true, unsafeReasons: [] };const stateHash = sha256({versions: cp.versions,input: cp.input,state: cp.state,toolCall: cp.toolCall,toolResult: cp.toolResult,});this.db.prepare(`insert into agent_checkpoints (run_id, thread_id, step_index, node_name, created_at,versions_json, input_json, state_json, tool_call_json,tool_result_json, replay_json, state_hash) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(cp.runId,cp.threadId,cp.stepIndex,cp.nodeName,new Date().toISOString(),JSON.stringify(cp.versions),JSON.stringify(cp.input),JSON.stringify(cp.state),cp.toolCall ? JSON.stringify(cp.toolCall) : null,cp.toolResult ? JSON.stringify(cp.toolResult) : null,JSON.stringify(replay),stateHash,);return { stateHash };}get(runId: string, stepIndex: number) {const row = this.db.prepare(`select * from agent_checkpointswhere run_id = ? and step_index = ?`).get(runId, stepIndex) as any;if (!row) return null;return {runId: row.run_id,threadId: row.thread_id,stepIndex: row.step_index,nodeName: row.node_name,createdAt: row.created_at,versions: JSON.parse(row.versions_json),input: JSON.parse(row.input_json),state: JSON.parse(row.state_json),toolCall: row.tool_call_json ? JSON.parse(row.tool_call_json) : null,toolResult: row.tool_result_json ? JSON.parse(row.tool_result_json) : null,replay: JSON.parse(row.replay_json),stateHash: row.state_hash,};}}

保存 checkpoint 的位置，建议放在每个节点完成之后，而不是整个 run 结束之后。否则 Agent 中途崩溃时，你正好会丢掉最需要的那部分信息。

一个包装工具调用的例子如下：

async function runToolWithCheckpoint(params: {store: CheckpointStore;runId: string;threadId: string;stepIndex: number;toolName: string;args: unknown;sideEffectLevel: SideEffectLevel;execute: () => Promise<unknown>;}) {const idempotencyKey = `${params.runId}:${params.stepIndex}:${params.toolName}`;params.store.sa ve({runId: params.runId,threadId: params.threadId,stepIndex: params.stepIndex,nodeName: `before_tool:${params.toolName}`,versions: currentVersions(),input: { toolArgsHash: sha256(params.args) },state: currentAgentState(),toolCall: {name: params.toolName,arguments: params.args,idempotencyKey,sideEffectLevel: params.sideEffectLevel,},replay: {canResumeFromHere: params.sideEffectLevel === 'read',unsafeReasons: params.sideEffectLevel === 'read' ? [] : ['tool_has_side_effect'],},});const started = Date.now();try {const result = await params.execute();params.store.sa ve({runId: params.runId,threadId: params.threadId,stepIndex: params.stepIndex + 0.1,nodeName: `after_tool:${params.toolName}`,versions: currentVersions(),input: { toolArgsHash: sha256(params.args) },state: currentAgentState(),toolCall: {name: params.toolName,arguments: params.args,idempotencyKey,sideEffectLevel: params.sideEffectLevel,},toolResult: {ok: true,resultHash: sha256(result),resultPreview: preview(result),latencyMs: Date.now() - started,},replay: { canResumeFromHere: true, unsafeReasons: [] },});return result;} catch (err: any) {params.store.sa ve({runId: params.runId,threadId: params.threadId,stepIndex: params.stepIndex + 0.1,nodeName: `after_tool:${params.toolName}`,versions: currentVersions(),input: { toolArgsHash: sha256(params.args) },state: currentAgentState(),toolCall: {name: params.toolName,arguments: params.args,idempotencyKey,sideEffectLevel: params.sideEffectLevel,},toolResult: {ok: false,resultHash: sha256({ name: err.name, message: err.message }),errorType: err.name,latencyMs: Date.now() - started,},replay: { canResumeFromHere: true, unsafeReasons: [] },});throw err;}}

上面代码里的 currentVersions()、currentAgentState()、preview() 是你自己系统里的函数。重点不是这些函数怎么写，而是记录的位置：工具调用前存意图，工具调用后存结果。只存结果会丢掉“当时为什么要调用”；只存意图会丢掉“外部世界到底返回了什么”。两边都存，排障才能形成闭环。

Replay Runner：重放时默认不碰外部世界

有了 checkpoint，还需要一个 replay runner。最小规则是：

• read 工具可以 live replay，但要标记数据漂移；
• write / external 工具默认使用保存的 toolResult；
• 模型调用默认 mock 成旧输出，除非显式进入 regression 模式；
• replay 输出必须生成 diff，而不是只给一个“成功 / 失败”的结论。

伪代码如下：

type ReplayMode = 'exact' | 'regression';async function replayFrom(params: {store: CheckpointStore;runId: string;stepIndex: number;mode: ReplayMode;}) {const cp = params.store.get(params.runId, params.stepIndex);if (!cp) throw new Error('checkpoint_not_found');if (!cp.replay.canResumeFromHere) {return {ok: false,reason: 'unsafe_checkpoint',unsafeReasons: cp.replay.unsafeReasons,};}const sandbox = createReplaySandbox({mode: params.mode,toolPolicy: (toolCall) => {if (toolCall.sideEffectLevel === 'read') return 'live-with-drift-check';return 'mock-sa ved-result';},modelPolicy: params.mode === 'exact' ? 'mock-sa ved-output' : 'call-current-route',});const replayResult = await sandbox.run({versions: cp.versions,input: cp.input,state: cp.state,});return {ok: true,checkpointHash: cp.stateHash,outputHash: sha256(replayResult.output),diff: compareReplay(cp, replayResult),};}

工程上最有价值的是 diff。它至少应该回答以下几个问题：

• prompt / policy / tool schema 版本是否变化？
• 检索上下文 hash 是否变化？
• 工具参数是否变化？
• 工具结果是否变化？
• 最终答案是否变化？
• 这些变化是否命中了预期的修复点？

没有 diff 的 replay，只是在“重新跑一次”。有了 diff，replay 才会真正变成回归测试。

一条真实排障链路应该怎么走

假设线上报警：Agent 在自动处理工单时，把“需要人工确认”的退款请求错误地归类成了“可自动处理”。传统日志排障的路径大概是：搜 runId、翻 prompt、翻工具结果、问业务同学、手动构造一个相似请求再跑一次。

而 Checkpoint replay 的流程应该是这样的：

1. 从报警拿到 runId 和失败的 step。
2. 打开 trace，看执行链路和耗时，确认异常节点。
3. 定位该节点前后的 checkpoint。
4. 进行 exact replay：用旧的模型输出和旧的工具结果恢复执行，验证状态机是否能复现错误的路径。
5. 查看 checkpoint diff：发现 policyVersion=refund-policy-2026-07-01，而工具 schema 里 requires_manual_approval 字段在该版本中没有进入模型上下文。
6. 修复 schema 映射或 prompt assembly。
7. 进行 regression replay：使用新版本重新跑同一 checkpoint，确认 Agent 会进入人工确认分支。
8. 将该 checkpoint 固化为 eval case，加入发布前的回归集。

这个流程最大的收益不是“快了一点”，而是把一次事故从口头复盘，变成了结构化的资产。每一个线上坏例子，都能沉淀为可重放的样本。后面改 prompt、改工具、换模型路由时，都能拿出来跑一遍。

Checkpoint Replay 和 Eval Harness 的关系

很多团队已经在做 eval harness：准备一批输入，看模型输出是否符合预期。这当然有用，但 Agent 的坏案例往往不是单轮输入输出导致的，而是中间状态出了错。

离线 eval 更像“题库”；checkpoint replay 更像“事故切片”。两者应该合并起来：

• 从线上 checkpoint 中筛选出高价值的坏案例；
• 清理敏感字段，生成可共享的 replay fixture；
• 给 fixture 标注期望路径，而不只是期望最终答案；
• 每次发布 prompt / schema / route 前，跑一遍 replay regression；
• 对差异生成报告，要求 reviewer 看过之后再上线。

一个 fixture 可以长这样：

{"case_id": "refund_manual_approval_001","source_run_id": "run_20260713_0830_9fc2","start_checkpoint": 4,"expected": {"must_call_tools": ["get_refund_policy"],"must_not_call_tools": ["execute_refund"],"final_state": "WAITING_HUMAN_APPROVAL"},"redactions": {"user_id": "hash","order_id": "synthetic"}}

注意这里的 expected 不是“回答里必须包含某句话”，而是路径约束。在 Agent 工程里，路径往往比文案更重要。一个答案看起来没问题，但如果它绕过了审批工具，那就是事故。

什么时候只做 trace 就够，什么时候必须做 replay

并非所有 Agent 都需要一开始就上 replay。下面这张表可以作为判断依据：

一个简单的建议：只要 Agent 会调用业务工具，尤其是会产生写操作，就不要只停留在 trace 阶段。至少先把 checkpoint 的数据结构定下来，哪怕 replay runner 晚一点再做。

最容易踩的 6 个坑

坑一：只存自然语言摘要。 摘要适合人看，但不适合机器重放。checkpoint 必须存结构化字段，摘要只能作为附属信息。

坑二：不存版本。 没有 promptVersion、toolSchemaVersion、policyVersion，replay 产生的差异基本不可解释。

坑三：把长期记忆当 checkpoint。 长期记忆会被更新、压缩、合并，不适合作为事故现场。checkpoint 要保留的是当时的原始现场。

坑四：重放时真的执行写工具。 这是最危险的。写工具必须 mock、dry-run，或通过幂等键确认状态。

坑五：没有脱敏策略。 checkpoint 会保存上下文和工具结果，必须在采集层做字段级脱敏、加密和访问控制。否则观测系统本身会变成新的数据风险点。

坑六：只给平台团队用。 replay 的价值不应该只局限在基础设施团队。业务负责人、客服、测试、算法同学都应该能看到“这次错误的路径是什么”，只是权限视图不同。

团队落地路线：别一口吃成平台

如果团队目前只有日志，不建议立刻去做一个大平台。完全可以按三个阶段来推进。

第一周：把关键节点状态存下来

目标很简单：每个 run 有 runId，每个 step 有 checkpoint。先覆盖以下内容：

• 用户输入 hash；
• prompt / tool schema / policy 版本；
• 工具调用参数和结果 hash；
• 外部副作用级别；
• 错误类型和耗时。

这一阶段不要求完整的 replay，只要求事故发生后能看到一个结构化的现场。

第一个月：做 exact replay 和 diff

第二阶段，做一个内部 CLI 或页面：输入 runId 和 stepIndex，可以从 checkpoint 恢复，使用保存的模型输出和工具结果跑状态机，并生成 diff。这个阶段的重点是验证：你的状态机是否真的可恢复；哪些字段缺失会导致 replay 失败；哪些工具没有明确的副作用级别。

第一个季度：接入回归与发布门禁

第三阶段，把线上 badcase 变成 fixture，接入发布流程。每次改 prompt、工具 schema、模型路由、权限策略，都跑一遍 replay regression。如果某个高风险 case 从 WAITING_HUMAN_APPROVAL 变成了 AUTO_EXECUTE，发布应该直接阻断。这个门禁，比“平均分提升 2%”更有生产意义。

一个实用的 checkpoint 分级标准

为了避免过度采集，可以将 checkpoint 分成三级：

不要所有场景都上 L3。真正要做的是：按风险决定采集深度。一个内部知识库问答助手，L1/L2 可能就够用了；一个能改配置的运维 Agent，则必须上 L3。

对工程团队的真正价值

Checkpoint replay 听起来像是一个“排障工具”，但它最终会改变整个团队的协作方式。

对开发来说，它把“我本地复现不了”变成了“从第 5 步 checkpoint 开始 replay”。

对测试来说，它把线上事故变成了可回归的样本，而不是写在复盘文档里的故事。

对产品和业务来说，它能解释 Agent 为什么做出某个决策，而不是只给出一个最终答案。

对管理者来说，它让 Agent 的质量评估从“感觉还行”变成了“关键路径 badcase 是否回归通过”。

这也是为什么说 checkpoint replay 会成为 Agent 工程的基础设施，而不是某个框架的高级功能。框架可以换，模型可以换，但“线上现场可恢复”这件事不会过时。

结论：Agent 生产化，要从“看见”走向“回到现场”

过去一年，很多团队补上了 tracing、prompt 管理、评估集，这些都很必要。但 Agent 真正进入生产后，最值钱的问题会变成：发生问题后，你能不能真正回到那个出错的现场？

如果不能，你就只能靠日志去猜。如果能回到现场，你就可以复盘、修复、回归，甚至在发布前阻断风险。

一个很直接的结论是：只要你的 Agent 已经接入了业务工具，从今天开始给它加 checkpoint。先不用搞得太复杂，先把版本、状态、工具意图、工具结果、副作用级别存下来。等下次线上 badcase 出现时，你会庆幸自己留下的不仅仅是一堆“模型调用成功”的日志。

日志告诉你它曾经来过。Checkpoint replay 则让你回到它出错的那一刻。