知序
返回
保存草稿
发布
H1
H2
H3
1
2
3
Excalidraw 图
AI 写作
AI 优化
目录
输入内容后显示目录
Markdown
# Agent Checkpoint 设计方案 > 导读:本文从"Agent 跑到第 7 步进程被 OOM 干掉,能不能别从头再来,还别把第 3 步已经提交的支付接口重复调一遍"这个真实痛点出发,把 Checkpoint(检查点)、状态快照字段、触发时机、Resume(恢复)流程、副作用幂等、分布式多实例下的租约与乐观锁一致性、存储选型逐项讲透,最后给出工程实践与踩坑清单。适合正在做 Agent 平台基建、或准备 Agent 系统设计面试的同学。 ## 一、先建立全局认知 ### Q:Agent 的 Checkpoint 到底解决什么问题? A:结论先行——Checkpoint 的唯一核心目标,是**让 Agent 中断后能够恢复完整执行上下文并继续跑,而不是从头重跑**,需要覆盖进程 crash(崩溃)、用户手动暂停、执行超时、工具调用失败后回滚或续跑这几类场景。 具体来说,一个 Agent Run 可能因为以下原因中断: - 进程 crash、容器被驱逐、OOM(Out Of Memory,内存溢出被系统杀掉); - 用户主动点击"暂停"; - 单步执行超时、整体任务超时; - 工具调用失败,需要回滚到某个一致状态后换条路重试。 如果没有 Checkpoint,唯一的恢复手段就是"重跑",代价是重复的 token 费用、重复的等待时间,以及最致命的——**重复的外部副作用**(重复写库、重复发消息、重复扣款)。 ### Q:Agent 的 Checkpoint 和普通大模型 Chat 的历史记录,差别在哪? A:结论先行——Chat 只需要存对话历史,而 Agent 除了对话历史之外,还必须存**工具状态、中间子任务、内存(memory)、迭代步数、外部资源句柄**这五类运行时状态。 普通 Chat 是"无状态 + 追加消息"的线性结构,把 messages 存下来就能重放。Agent 是"有状态 + 带副作用"的循环结构:它有自己的工作内存、规划出来的子任务列表、已经调用过的工具及其结果、当前跑到第几步,还可能握着外部系统的资源句柄(文件、会话、事务)。因此 Checkpoint 保存的是一份"Agent 运行时状态的完整快照",而不只是聊天记录。 ### Q:一个 Agent Run 和一份 Checkpoint 是什么关系? A:结论先行——**一个 agent_run_id 对应一条任务,它会随时间产生多份 checkpoint**;checkpoint 是 run 在某个时刻的状态快照,是"版本"的概念,而不是"一对一"。 这个"一对多"的模型很关键,它直接决定了后面所有设计: - 支持多版本,就能支持 rewind(回退到历史某一步,实现 Agent undo); - 有多版本,就必须区分"哪个版本是稳定的、哪个版本是应急的"; - 有多版本,就必然面临"并发写时谁覆盖谁"的一致性问题。 ## 二、Checkpoint 的数据模型与粒度设计 ### Q:Checkpoint 里到底要存哪些字段? A:结论先行——按"LLM 会话上下文、Agent 运行状态、工具调用状态、控制参数、外部资源引用、断点类型"六类来组织,其中**Agent 运行状态和工具调用状态是最容易被忽略、却最不能漏的**。 下面是一份可直接落地的最小 Schema(模式定义): ```json { "checkpoint_id": "cp_xxx", "agent_run_id": "run_xxx", "created_at": "timestamp", "status": "running|paused|failed|completed", "messages": [], "system_prompt": "agent系统提示词", "step": 5, "max_step": 20, "sub_tasks": [ {"id": "t1", "desc": "xxx", "status": "done|pending|running", "result": "..."} ], "agent_memory": { "facts": [], "variables": {}, "reflections": [] }, "tool_call_history": [ { "tool_call_id": "tc_123", "tool_name": "search", "arguments": {}, "status": "pending|success|failed", "result": "...", "error": null } ], "pending_tool_calls": [], "config": { "llm_model": "xxx", "temperature": 0.1, "planning_strategy": "react|plan_execute" }, "external_refs": { "vector_db_snapshot_id": null, "file_list": [] }, "break_reason": "timeout|manual_pause|tool_error|crash" } ``` 关键点解读: 1. `messages` + `system_prompt` 是 LLM 会话上下文,决定了"重放时模型能看到的输入"; 2. `step` / `max_step` / `sub_tasks` / `agent_memory` 是 Agent 自身运行状态,是最核心的部分,少了它就无法从断点续跑; 3. `tool_call_history` + `pending_tool_calls` 是工具调用状态,是**防重复调用的关键**; 4. `config` 保存模型、温度、规划策略等控制参数,保证恢复后行为一致; 5. `external_refs` 只存引用(如向量库快照 id、文件列表),**绝不把大二进制塞进 checkpoint**; 6. `break_reason` 标记断点原因,便于恢复策略分流与排障。 ### Q:Checkpoint 应该按什么粒度来打?每次都全量落盘吗? A:结论先行——按 Agent 的执行结构分成三类粒度:**Step Checkpoint(每步一存)、Task Checkpoint(每个子任务一存)、Emergency Checkpoint(异常触发即时 dump)**,日常主力是 Step Checkpoint。 | 类型 | 触发点 | 适用形态 | 特点 | |---|---|---|---| | Step Checkpoint | ReAct 每一轮"思考 + 工具返回"闭环完成 | ReAct Agent | 最常用,粒度最细 | | Task Checkpoint | 一个子任务执行完成 | Plan-and-Execute | 规划结果不复算 | | Emergency Checkpoint | crash / 超时 / 工具异常立刻 dump | 所有形态 | 应急处置,不等本轮结束 | 这里有一个非常重要的设计取舍:**不建议在工具调用"发出但未返回"的中途作为主 Checkpoint 持久化。** 因为外部 IO 状态不可控——请求已经发出去了,此时持久化并在恢复时"重发",极易重复执行工具,产生写文件、发消息、支付这类副作用。正确做法是:只有一轮 Agent 循环闭环完成(拿到工具返回结果)才生成稳定可恢复的 Checkpoint;pending 状态只作为应急快照,恢复时必须做校验。 ### Q:什么时候应该自动触发 Checkpoint? A:结论先行——在"状态一致的边界"上触发,具体有五种:每完成一个完整 step、每完成一个子任务、达到步数阈值、捕获异常、用户手动暂停。 - Agent 每执行完一个完整 step(思考 + 工具返回)→ 写入 Checkpoint(ReAct 标准做法); - 每完成一个子任务(Plan-Execute 形态); - 达到指定步数阈值(例如每 N 步落盘一次),避免 IO 过于频繁; - 捕获异常:LLM 报错、工具抛异常、超时、收到 SIGINT / SIGTERM 进程信号; - 用户通过 API 手动暂停。 反过来,**不推荐的时机**有两个: 1. LLM stream(流式)输出中途频繁快照——数据不完整,恢复点不可靠; 2. 工具已发出、结果还没回来的时刻作为主 Checkpoint——外部 IO 状态不可控,恢复极易重复执行。 一句话总结最佳实践:**只有一轮 Agent 循环闭环完成(拿到工具返回)才生成稳定可恢复的 Checkpoint;pending 工具调用只作为应急快照,恢复要做校验。** ### Q:ReAct 型和 Plan-and-Execute 型 Agent,Checkpoint 设计有什么不同? A:结论先行——ReAct 是"单层、每轮循环结束",Plan-and-Execute(以及 Multi-Agent)是"两层:Plan 层 + Execute 层"。 ReAct Agent(循环式:思考—行动—观察): - 粒度:每一轮循环结束; - 保存:messages、step 计数、tool_call_history、memory; - 恢复:把完整 messages 直接喂给 LLM,从下一个 step 继续思考。 Plan-and-Execute / Multi-Agent: - 两层结构:Plan 层 Checkpoint + Execute 层 Checkpoint; - Plan Checkpoint:保存完整的任务拆解子任务列表,这样即使执行崩了,**规划结果不用重新生成**(省一次大模型调用); - Execute Checkpoint:每个子任务执行完成做一次快照; - 恢复:优先复用已完成子任务的结果,只跑未完成的子任务。 这个取舍的本质是"把昂贵的、稳定的规划结果与廉价的、易变的执行结果分层保存",避免让一次执行抖动把昂贵的规划也一起作废。 ## 三、Resume 恢复流程与副作用幂等 ### Q:Resume 的完整流程是怎样的? A:结论先行——**校验状态 → 重建内存 → 处理 pending 工具调用 → 从断点 step 继续迭代**,其中第三步是防重复副作用的重中之重。 ```text 输入:checkpoint_id 1. 读取完整 checkpoint 对象 2. 校验状态: - completed:直接返回结果,不再执行 - running / paused / failed:恢复执行 3. 恢复 Agent 内存、子任务列表、messages、配置 4. 处理 pending_tool_calls(重点:防重复副作用) for each pending tool_call: 查询外部工具:该 tool_call_id 是否已执行完成 - 已有结果:回填 tool result,从 pending 移除,继续下一步 - 工具已超时失效:标记失败,让 Agent 重新生成工具调用 5. 从 checkpoint.step 继续迭代 注意:不要从头跑 system prompt + 全部历史重新规划 6. 恢复过程中产生新 step,持续生成新 checkpoint;旧 checkpoint 保留/归档 ``` 两个关键点必须强调: 1. **恢复时不要从头重算规划。** Checkpoint 的价值就是跳过已经完成的工作,如果恢复后又把 system prompt 和全部历史丢给模型重新规划,那和重跑几乎没有区别,还多了一次昂贵的调用。 2. **pending 工具调用必须先"查询"而不是"重发"。** 这是幂等的核心动作。 ### Q:Checkpoint 最大的坑是什么?怎么防? A:结论先行——最大的坑是**恢复时重复执行有副作用的工具**;对策是"全局唯一 tool_call_id + 工具服务层幂等 + 恢复优先复用旧结果 + 不可幂等系统不允许在 pending 断点"。 具体三条对策: 1. 每个 tool_call 分配全局唯一的 `tool_call_id`;工具服务层做幂等,相同 call_id 的重复请求直接拒绝或直接返回历史结果,**禁止重复执行业务副作用逻辑**; 2. Checkpoint 记录每个工具调用的状态(pending / success / failed),恢复时优先复用旧结果,不重新发起; 3. 对于无法做成幂等的外部系统,**不允许在 pending 状态断点**,必须等工具返回后再打 Checkpoint。 这三条里,第 3 条最容易被忽视但也最实用:与其费劲去给一个"天生不幂等"的外部系统打补丁,不如直接在设计上禁止它出现在断点窗口里。 ### Q:Checkpoint 存哪里?存储怎么选型? A:结论先行——**Redis 适合短生命周期、高吞吐的在线会话;PostgreSQL / MongoDB 是生产持久化的首选;本地文件只用于调试**。 | 存储 | 适用场景 | |---|---| | Redis | 短生命周期 Agent,高频读写,checkpoint 序列化 JSON,设置 TTL;适合在线会话 | | PostgreSQL / MongoDB | 持久化,大量 agent run,支持查询历史 checkpoint,生产首选 | | 本地文件 JSON | 调试、demo,不适合分布式多实例 | 一个容易被忽略的细节:**大 messages 不要无限膨胀**。可以在 Checkpoint 里做摘要压缩,原始完整消息另存归档(对象存储 / 日志系统),Checkpoint 只保留"能恢复执行"的最小必要信息。 ## 四、分布式多实例下的一致性设计 ### Q:单机没问题,多实例部署后 Checkpoint 会出现什么新问题? A:结论先行——核心是四类问题:**多 Worker 同时 resume 同一个 run、读写时序错乱导致旧状态覆盖新状态、异步工具回调与写 Checkpoint 并发造成状态撕裂、实例崩溃留下半写快照**。 分布式场景下,同一个 `agent_run_id` 可能被多个 Agent Worker 抢到;再加上异步工具回调、crash、网络抖动、重试、自动恢复,会带来: 1. 多 Worker 同时 Resume 同一个 Run → 重复执行工具,产生副作用(写库、发消息、调用支付接口); 2. Checkpoint 写-读时序错乱:WorkerA 已经 step=5,WorkerB 读到旧 Checkpoint step=3 继续往下跑,状态被回写覆盖; 3. 工具异步回调与 Agent Worker 写 Checkpoint 并发,状态撕裂; 4. 实例崩溃,留下只写了一半字段的 partial checkpoint(半完成快照); 5. 长耗时 pending 工具调用,多实例恢复时重复派发工具请求。 对应的核心目标有四条: - 同一个 agent_run,**同一时刻最多只有 1 个 Worker 在执行**; - Checkpoint 读写满足**状态线性一致性,禁止旧状态覆盖新状态**; - 工具调用严格幂等,杜绝副作用重复执行; - 支持 Worker 宕机后其它实例安全接管。 ### Q:分布式下 Checkpoint Schema 要补哪些字段? A:结论先行——补四个关键字段:**state_version(乐观锁版本)、run_lease(运行租约)、max_committed_step(已提交最大步)、partial_flag(半写标记)**。 ```json { "checkpoint_id": "cp_xxxx", "agent_run_id": "run_xxxx", "schema_version": "v2-dist", "run_lease": { "worker_instance_id": "worker-03", "lease_expire_at": "2026-08-07T10:00:00Z", "lease_version": 7 }, "current_step": 5, "max_committed_step": 5, "state_version": 12, "run_status": "IDLE|RUNNING|PAUSED|FAILED|COMPLETED", "partial_flag": false, "messages": [], "sub_tasks": [], "tool_call_history": [], "pending_tool_calls": [] } ``` 字段解释: 1. **`state_version` 乐观锁**:更新必须携带读到的旧 version,DB/Redis 做 CAS(Compare-And-Swap,比较并交换),版本不匹配就拒绝写入,解决旧状态覆盖新状态; 2. **`run_lease` 运行租约**:谁拿到租约谁才有权执行该 run,租约带过期时间,Worker 定期续租,宕机后租约自动过期,其它实例可接管; 3. **`max_committed_step`**:真正落地完成的稳定步数。应急快照(crash、工具 pending)不能提升这个字段;只有一轮完整闭环(think-call-observe 全完成)才递增;**Resume 只能从 max_committed_step 恢复**,拒绝从 partial 半完成快照直接执行业务逻辑; 4. **`partial_flag`**:标记这是应急 dump,不能直接拿来 Resume,仅用于人工排查;恢复时会回滚到上一个非 partial 的稳定 Checkpoint。 由此形成两类快照的清晰划分: - ✅ **Committed Checkpoint(稳定快照)**:`partial_flag=false`,`max_committed_step` 已更新,可以被正常 Resume; - ⚠️ **Partial Emergency Checkpoint(应急快照)**:进程 crash、SIGTERM 触发 dump,`partial_flag=true`,仅留存现场,**不能直接恢复执行**。 ### Q:怎么保证"同一个 run 同一时刻只有一个 Worker 在跑"? A:结论先行——用**租约(lease)+ TTL(存活时间)+ 后台续租协程**的抢占模型:Agent Run 不属于某个固定 Worker,而是"谁抢到租约谁执行"。  *图:Worker 抢占 run_lease 接管 run 并恢复 Checkpoint 的流程* ```text Worker 尝试接管 run_id │ ▼ 抢占 run_lease CAS 条件:run_status = IDLE 或 租约已过期 │ ┌────┴────┐ ▼ ▼ 成功 失败(已被其它 worker 持有) │ │ │ └──► 退出,不执行该 run ▼ 写入 worker_id / lease_expire / lease_version,run_status = RUNNING │ ▼ 加载该 run 最新的稳定 Committed Checkpoint(忽略 partial 应急快照) │ ▼ 启动后台续租协程 │ ▼ 进入 Agent 执行循环 ``` 租约机制的细节: - 租约 TTL 建议 **30s ~ 120s**,根据 Agent 单步最大耗时配置; - 持有租约的 Worker 必须用后台协程**周期性续租**,例如每 1/3 TTL 刷新一次过期时间; - Worker 正常结束(完成 / 手动暂停):主动释放租约,`run_status` 置为 IDLE / PAUSED / COMPLETED; - Worker 崩溃:不再续租,租约超时自动失效,调度器可让其它 Worker 接管; - **禁止**:没有持有有效租约的 Worker 不能写任何业务 Checkpoint 状态,只允许写 partial 应急 dump。 注意租约的能力边界:它解决"多实例同时跑同一个 run",但**不能解决网络分区**。极端分区场景下,TTL 窗口内仍可能出现双活,必须靠状态乐观锁 + 工具幂等来兜底。 租约对应的 run 状态机: | run_status | 含义 | 是否允许抢占租约 | |---|---|---| | IDLE | 空闲,可以被接管 | ✅ | | RUNNING | 已有 worker 持有租约执行 | ❌(租约过期后变为 IDLE) | | PAUSED | 用户手动暂停 | ✅ | | FAILED | 执行失败等待重试 | ✅ | | COMPLETED | 任务结束,终态 | ❌,不可再执行 | ### Q:写 Checkpoint 时怎么保证不被旧状态覆盖? A:结论先行——**原子条件更新(CAS),绝不"先查再改"**;条件不匹配就放弃本次写入并终止执行。 稳定 Committed 快照的写入流程: 1. Worker 必须持有该 run 的有效租约,否则拒绝写业务快照,仅允许写 partial dump; 2. 本地内存状态 `state_version + 1`; 3. 执行原子写(数据库 UPDATE / Redis CAS): ```sql UPDATE agent_runs SET state_version = :new_version, current_step = :step, max_committed_step = :step, partial_flag = false, -- ... 其余业务状态 ... WHERE agent_run_id = :run_id AND state_version = :old_version; -- 乐观锁条件 ``` 4. 如果条件不匹配(version 已变化):说明别的实例已经改过状态,**直接放弃本次写入,Worker 终止执行并释放租约**,避免状态冲突。 而应急 Partial Checkpoint(SIGTERM、OOM、进程即将退出)则相反:**不修改 `max_committed_step`、不递增正式 `state_version`,只设置 `partial_flag=true`,允许无租约写入,仅做现场留存**。Resume 逻辑永远不会把 partial checkpoint 作为恢复起点。 ### Q:分布式下 Resume 的处理,和单机有什么不同? A:结论先行——pending 工具调用的处理必须**从"查本地内存"改成"查分布式工具服务中心"**,因为工具调用是独立服务,不在 Worker 本地。 ```text Resume 恢复流程: 1. 获取 run 记录,校验 run_status;COMPLETED 直接返回结果 2. 抢占租约成功 3. 查询该 run 下所有 checkpoint,过滤掉 partial_flag=true, 取 max_committed_step 最大的稳定快照 4. 加载快照,重建 Agent 内存状态 5. 处理 pending_tool_calls: for tool_call in pending_tool_calls: 通过 tool_call_id 去【分布式工具服务】查询执行状态 case1 工具已执行完成 → 回填 result,从 pending 移除,加入 tool_call_history case2 工具正在运行中 → 继续等待,Agent 挂起,不生成新工具调用 case3 工具已超时/失效 → 标记该 tool_call 失败,Agent 重新规划生成新调用 ``` **工具层的分布式幂等兜底**是租约和乐观锁之外的最后一道防线(因为网络分区下它们都可能短暂失效): 1. 每次工具调用生成**全局唯一 `tool_call_id`**,由 Agent 生成并传给工具服务; 2. 工具服务侧以 `tool_call_id` 做幂等 key;收到重复相同 id 的请求,直接返回历史结果,禁止重复执行业务副作用; 3. 工具服务持久化每个 tool_call 的状态(PENDING / SUCCESS / FAILED);**Agent Worker 永远不本地信任 pending 状态,恢复必须向工具中心查询**; 4. 有副作用的工具(写 DB、API 提交)强制开启幂等;无副作用工具(search 查询)可以宽松,但依然要记录 tool_call_id。 ### Q:存储层要怎么支撑这套一致性要求? A:结论先行——选**支持原子条件更新(CAS)的存储**,并采用"run 主表 + checkpoint 子表"的两表架构。 | 存储 | 分布式能力 | CAS / 原子条件更新 | 适合场景 | |---|---|---|---| | PostgreSQL | 主从分布式 | ✅ WHERE 条件原子 UPDATE,行锁 | 生产首选;agent run 作为行,checkpoint 单独表,run_id 外键 | | MongoDB | 分片 | ✅ updateOne pre-filter | 大规模 agent run | | Redis Cluster | 分布式 | ✅ SET + NX / CAS | 高吞吐短生命周期 Agent;租约用 EX 实现 TTL;注意集群下 CAS 只保证 slot 内原子 | 架构建议两张表: 1. `agent_runs`:保存 run 级元数据、租约、state_version、max_committed_step(行粒度锁,**核心一致性都收敛在这一行**); 2. `agent_checkpoints`:每个版本一条快照记录,关联 agent_run_id,保存完整 state,可保留多版本用于 rewind 回滚。 不要把巨大的 checkpoint 全部塞进 `agent_runs` 主表行里——主表要尽量轻,快照放子表。 整体架构如下:  *图:分布式 Checkpoint——调度器、Worker、租约与快照存储* ```text ┌────────────┐ │ 调度器 │ └──┬──────┬──┘ │ │ ┌────▼──┐ ┌─▼─────┐ │Worker1│ │Worker2│ └──┬─┬──┘ └──┬──┬─┘ ①抢占租约/CAS │ │ ②各版本快照 │ │ │ └───┬────────┘ │ ▼ ▼ ▼ ┌───────────────┐ ┌──────────────────┐ │ agent_runs 表 │ │agent_checkpoints │ │ run_id/租约/ │ │ 各版本 state 快照 │ │ state_version │ └──────────────────┘ │ max_committed │ └───────────────┘ │ ③tool_call_id 幂等调用 ▼ ┌──────────────────────┐ │ 分布式工具服务中心 │ ├──────────────────────┤ │ tool_call_state 存储 │ │ (tool_call_id 全局态) │ └──────────────────────┘ Worker1/Worker2 -. 后台协程续租 .-> agent_runs 表 ``` ### Q:几个典型异常场景,具体怎么收场? A:结论先行——四类场景分别用"忽略 partial 快照 + 幂等""CAS 写失败即退出""回调只写工具中心、Agent 主动拉取""事务保证不半写"来处理。 **场景 1:WorkerA 执行中 crash,租约超时,WorkerB 接管** 1. WorkerA 崩溃,来不及写最新 committed checkpoint,可能留下 partial 应急快照; 2. 租约 TTL 到期,run_status 变为 IDLE; 3. WorkerB 抢占租约成功,**忽略 partial 快照,加载上一个 max_committed_step 的稳定 checkpoint**; 4. 查询分布式工具服务的 pending 工具状态,继续执行。 代价:最近一轮未闭环的 step 会重做一次;依靠 tool_call_id 幂等,不会产生副作用。 **场景 2:网络分区,短暂出现双 Worker 持有租约窗口** 1. 网络分区,WorkerA 还认为自己持有租约,实际 TTL 已过期,WorkerB 抢占成功; 2. WorkerA 后续尝试写 checkpoint:`state_version` 已被 B 递增,CAS 条件失败,写入被拒; 3. WorkerA 检测写失败,主动终止 Agent 循环退出; 4. 工具层幂等兜底,即使 A 还发工具调用,tool_call_id 不会重复执行。 **场景 3:异步工具回调回来,但 Worker 已经宕机** - 工具回调不直接推送给 Worker,回调结果写入**分布式工具中心 DB**; - 新 Worker 接管 Resume 时主动拉取工具结果,不依赖回调。 不建议依赖 MQ 回调直接修改 Agent Checkpoint:回调只写工具服务,Agent 主动拉取状态,这样一致性模型更简单。 **场景 4:Checkpoint 半写(数据库部分字段成功、部分失败)** - 使用数据库事务:**整个 committed checkpoint 的写入放在一个事务内**,要么全成功要么全失败; - partial 应急 dump 允许非事务,仅用于现场排查,不作为恢复源。 ## 五、工程实践与踩坑 1. **增量 vs 全量 Checkpoint。** 简单实现是每次全量序列化全部 messages,step 一多文件会越来越大;优化是增量 Checkpoint,只存 delta 变更并引用上一个 cp_id,恢复时链式加载——但复杂度显著上升,用不用取决于规模。 2. **不要把大外部数据塞进 Checkpoint。** 例如检索返回的大文档,只存 reference id,原始文档放向量库 / 对象存储。 3. **版本兼容。** Checkpoint 必须带 `schema_version`,后续字段变更做向前兼容,否则旧快照无法恢复。 4. **回滚能力。** 保留多个历史 Checkpoint,支持跳回之前的 step(Agent undo),而不是只能恢复最新。 5. **并发控制。** 同一个 agent_run 只允许一个恢复实例运行,加锁,防止多进程同时 resume 造成重复工具调用。 6. **事务边界。** Committed 快照必须在一个事务里写完,否则会出现"step 变了但 tool_call_history 没变"的撕裂状态。 7. **续租协程要隔离。** 续租必须由独立协程/线程负责;续租失败要立刻终止 Agent,不能让一个已经没有租约的 Worker 继续跑。 8. **性能优化方向。** 大规模高并发下,考虑快照裁剪(只存恢复必需字段)、消息压缩、冷热分离(近期快照热存、历史快照冷存)。 ### Q:Checkpoint 高频落盘会不会拖慢 Agent?性能开销怎么控? A:结论先行——用三招:**异步落盘 + 快照裁剪 + 冷热分离**;但异步化会引入一个新的风险窗口,必须配应急 dump 兜住。 ```text 1. 异步落盘:主循环同步等待写库会直接叠加延迟(一次 DB 写入可能 5~20ms, 20 步就是上百毫秒)。做法是把快照提交到落盘队列,由独立协程写库。 ⚠️ 代价:引入"提交延迟窗口"——提交入队但未落盘时进程崩溃,会丢最后一轮。 所以必须配合 Emergency dump(partial 快照)兜底。 2. 快照裁剪:只存"恢复必需"字段。 - messages 可做摘要压缩,原始完整消息归档到对象存储 - tool_call_history 可只保留最近 N 条 + 关键结果的对象存储引用 - 工具返回的大文档只存 reference id,绝不内联 3. 冷热分离:最近几份快照热存(Redis),更早的版本归档到对象存储/PG 子表, 支持 rewind 但不在热路径上。 4. 序列化成本:优先用紧凑 JSON / 二进制格式,避免深层嵌套与冗余字段。 ``` 关键点解读:这里有一个不可交换的约束——**"异步落盘"可以放宽"何时到达存储",但不能放宽"什么状态才算已提交"**。也就是说:`max_committed_step` 仍然只在"一轮闭环完成"时提升,异步只是让这个动作不阻塞主循环,而不是让"工具 pending 时的中间态"变成可恢复点。**优化的是延迟,不是语义**——把这两件事混起来,就会出现"恢复时跑到一半的 step"这种最难排查的 bug。 ### Q:什么时候该用增量 Checkpoint,什么时候不该? A:结论先行——**步数少、单步状态大 → 用增量;步数多、单步状态小 → 用全量**,判断依据是"序列化总量 vs 恢复复杂度"。 - **增量(只存 delta + 引用上一个 cp_id)** 的优势在于写入量小,适合"messages 飞快膨胀、每步都要全量写很浪费"的场景;代价是恢复时要**链式加载多个版本**,链越长恢复越慢,而且任何一环损坏都会导致整条链不可用; - **全量**的优势是恢复简单(读一份就能跑)、容错好;代价是写入量随步数线性增长。 一个务实的分界是:**Agent 的典型步数在 20 步以内、单次 messages 在几十 KB 量级时,全量快照 + 压缩比增量更划算**;只有当"步数上百、单步状态持续增长、且写入成为瓶颈"时,增量的复杂度才值得付。极端场景下还有一种折中:**每 N 步一次全量、中间步用增量**,兼顾恢复速度与写入量。 ### 生产级落地检查清单 ```text ✅ 1. Agent Run 使用租约 + TTL,同一 run 最多一个 worker 执行 ✅ 2. Run 元数据表使用乐观锁 state_version,原子条件更新,禁止旧状态覆盖新状态 ✅ 3. 区分 Committed 稳定快照 / Partial 应急快照;Resume 只用稳定快照 ✅ 4. max_committed_step 只有一轮完整 Agent 闭环才提升,pending 工具阶段不提升 ✅ 5. 工具调用全局 tool_call_id,工具服务层幂等存储调用状态, 恢复时外部查询,不信任 Worker 内存 pending ✅ 6. Committed Checkpoint 写入使用数据库事务,避免半写 ✅ 7. 没有持有有效租约的 Worker 禁止写业务状态,仅允许写 partial dump ✅ 8. 终态 COMPLETED 的 run 禁止再次抢占租约执行 ✅ 9. 租约续租协程必须隔离,续租失败 Agent 立刻终止 ``` ### 和 LangGraph 的对照理解 LangGraph 的 Checkpoint 本质上就是上面这套思路的工程化封装: - 保存 graph state(即上面的 Agent 运行状态); - 每个 node 执行完成写一次 Checkpoint; - Checkpoint-ID 对应 state 版本,支持 rewind 回到任意历史 state; - 底层 Store 支持 Redis、SQLite、Postgres。 在分布式实现上(其 Redis-Postgres 分布式模式)也遵循同样的模式:Thread 对应 agent_run_id、Checkpoint 多版本快照、Thread Version 乐观锁对应 state_version、分布式执行用 worker lease 租约(crash 后租约过期由其它 worker 接管);但**工具调用的幂等需要业务自己保证,框架不做工具层幂等**。 自己实现 Agent 不必照搬框架,抓住三件事即可:**状态快照、执行粒度闭环、工具调用幂等防重**。具体框架的字段命名与线协议细节,需结合版本确认。 ### 极简参考实现(Python 伪代码) ```python from dataclasses import dataclass, asdict @dataclass class AgentCheckpoint: run_id: str step: int messages: list sub_tasks: list tool_call_history: list memory: dict status: str schema_version: str = "v1" class CheckpointStore: def save(self, cp: AgentCheckpoint): data = asdict(cp) # 写入 Redis / DB(分布式场景下再加 CAS 条件:WHERE state_version = old) ... def load(self, run_id) -> AgentCheckpoint: ... # Agent 每轮循环结束保存 while not agent.done and agent.step < agent.max_step: agent.think() agent.call_tools() agent.observe() # 一轮闭环完成,写 checkpoint cp = AgentCheckpoint( run_id=agent.run_id, step=agent.step, messages=agent.messages, sub_tasks=agent.sub_tasks, tool_call_history=agent.tool_call_history, memory=agent.memory, status="running", ) checkpoint_store.save(cp) agent.step += 1 # 恢复 cp = checkpoint_store.load(run_id) agent.restore_from_checkpoint(cp) agent.run() # 从 cp.step 继续执行,不重跑历史 ``` 关键点解读:`save` 的调用点放在 `observe()` 之后(一轮闭环),而不是 `call_tools()` 之后(工具已发出、结果未回);恢复入口只依赖 `load` + `restore_from_checkpoint`,业务循环完全无感知——这是把"可恢复性"做成横切能力的基础形态。 ## 小结 - Checkpoint 的目标是**断点续跑而非重跑**,要保存的远不止对话历史,还包括工具状态、子任务、内存、步数、外部引用; - 触发时机要选在**状态一致的边界**(一轮闭环 / 子任务完成),绝不在工具 pending 中途作为主断点; - Resume 的核心动作是**先查询 pending 工具、复用旧结果**,而不是重发; - 副作用工具靠**全局 tool_call_id + 工具服务幂等**兜底; - 分布式下用**租约保证单执行者、乐观锁保证状态不回退、max_committed_step 区分稳定与应急快照、事务保证不半写**; - 最小心智模型三件事:状态快照、执行粒度闭环、工具调用幂等防重。 ## 思考题 1. 如果某个外部系统(例如老式支付网关)既不支持幂等、调用耗时又长达数分钟,你会怎么设计 Checkpoint 的断点策略?能不能接受"这一步永不进入 pending 断点"? 2. 增量 Checkpoint(只存 delta + 引用上一版本)在网络存储下可能导致恢复时链式加载很长,你会怎么权衡"存储成本"与"恢复延迟"? 3. 租约 TTL 设得太短会频繁误判宕机导致接管、设得太长会拉长故障恢复时间,你会用什么指标来驱动这个参数调优? 4. 如果要求支持 Agent undo(回退到第 3 步重新走),对已经产生的**外部副作用**(例如第 5 步已发的消息)你打算怎么补偿? 5. 想一想:为什么把回调结果写进工具中心、由 Agent 主动拉取,比让 MQ 回调直接改 Checkpoint 更好?请从一致性模型和故障域两个角度回答。
预览
发布文章
添加摘要让读者更快了解文章内容
取消
确认发布
AI 写作助手
输入一个主题,AI 将为你生成一篇 Markdown 博客文章
AI 正在写作中...
取消
开始生成
AI 优化助手
描述你的修改需求,AI 将在原文基础上进行补充或微调
AI 正在优化中...
取消
开始优化
画布
从已有图里选
✕
图名
保存后生成 /images/excalidraw/<图名>.svg(只能用字母、数字、短横线、下划线、点)
取消
保存并插入