Agent Checkpointing & Resumability/ 智能体检查点与断点续传

Agent Checkpointing（检查点机制）是在智能体执行长任务过程中，定期将当前状态——包括对话历史、已完成的工具调用结果、内存中的中间数据、推理上下文——序列化保存到持久化存储中。当任务因超时、网络中断、LLM 限流或程序崩溃等原因中断后，Agent 可以从最近的检查点「复活」继续执行，而不是从零开始重新推理和调用工具。这相当于给 Agent 的长任务装上了「存档按钮」，避免已完成的昂贵推理（尤其是多轮 LLM 调用和工具 API 调用）付诸东流。

检查点机制在 Agent 系统中按粒度分为三种层级，通常三层协同工作：

**1. 消息级检查点（Message-Level Checkpoint）——最细粒度**

每次 LLM 推理完成后，将完整的对话消息列表（含 system prompt + user messages + assistant responses + tool results）序列化保存。这是最基础的检查点形式。恢复时直接还原消息列表，LLM 从最后一个 assistant 消息之后继续推理。优势是实现简单、开销低（仅序列化 JSON 消息数组），但只能恢复到上一轮推理，不能恢复「推理到一半」的状态。

**2. 工具级检查点（Tool-Level Checkpoint）——关键节点**

在每次工具调用完成后保存检查点。除了消息列表外，还包含工具调用的完整上下文：工具名称、输入参数、返回结果、调用时间戳。这种粒度允许在工具调用中途崩溃后恢复，避免重复昂贵的 API 调用（如一次文件上传、一次数据库事务）。实现要点：每个工具调用的结果必须是幂等可重放的——即恢复后，Agent 能识别出「这个工具已调用过，直接用缓存结果」而不是重新执行。

**3. 图级检查点（Graph-Level Checkpoint）——完整状态**

对于采用 DAG/状态图编排的 Agent（如 LangGraph），检查点保存完整的图执行状态：当前节点位置、所有边的遍历记录、各节点的输入输出。这是 LangGraph 内置的 `checkpointer` 机制——支持从任意中间节点恢复执行。优势是可以在复杂分支流程中准确定位恢复点，但序列化开销最大。

核心设计原则：检查点必须包含三要素——**状态快照**（当前已知信息）、**位置指针**（任务进度标记）、**幂等标记**（已完成操作的指纹，防止重复执行）。

• **测试一：检查点保存与恢复正确性验证**

• 操作：构造一个包含 5 轮 LLM 推理 + 3 次工具调用的 Agent 任务（如「搜索资料 → 提取要点 → 生成摘要 → 发送邮件」），在第 3 轮推理后手动注入崩溃（kill -9 进程），然后从检查点恢复执行。验证恢复后的最终结果与未中断的完整执行结果一致

• 工具：LangGraph 内置的 MemorySaver/SqliteSaver checkpointer（https://langchain-ai.github.io/langgraph/reference/checkpoints/）；Pytest 自动化测试框架

• 指标：检查点恢复正确率（≥ 100%——恢复后的结果不应比完整执行差）、恢复后的 Token 节省比例（目标 ≥ Token 节省 60%，即跳过已完成的推理和工具调用）、恢复延迟（目标 < 3s 从检查点恢复到开始执行）

• **测试二：幂等性保障——防止重复执行**

• 操作：在工具调用完成后保存检查点，从检查点恢复后，确认 Agent 对已执行的工具调用不再发起重复请求。测试包含非幂等工具（如「发送邮件」「创建订单」）场景

• 工具：LangGraph checkpointer + 自定义工具包装器（给每个工具结果添加调用哈希）；SQLite 作为检查点后端

• 指标：重复工具调用次数（目标 = 0——恢复后不应重复任何已完成工具调用）、工具缓存命中率（≥ 100%——全部命中）

• **测试三：检查点存储开销与性能评估**

• 操作：运行 Agent 执行 50 轮复杂对话（每轮含多轮推理和多工具调用），对比不同检查点策略（每轮保存 vs 每 3 轮保存 vs 仅在工具调用后保存）的存储开销、序列化耗时和恢复耗时

• 工具：Python memory_profiler + cProfile 性能剖析；SQLite 存储大小对比

• 指标：单检查点体积（目标 < 500KB，避免序列化成为瓶颈）、检查点写入耗时（目标 < 100ms，不影响主流程）、存储增长曲线（50 轮后总存储 < 25MB）

1. **检查点「腐烂」——恢复后环境已变**：Agent 崩溃后恢复时，外部状态可能已经变化（如文件被删除、API Token 过期、数据库记录被修改），导致恢复后的操作基于过期假设继续执行。典型场景：Agent 在崩溃前调用了「创建临时文件 /tmp/agent_work/input.csv」并写入检查点，恢复时文件已被清理脚本删除。解决方案：检查点中保存的是「执行结果」而非「假设前提」——即恢复时优先使用检查点中的缓存结果，仅在确实需要重新执行外部操作时才做前置条件校验（防御性检查）。

1. **检查点与流式输出的交互问题**：流式模式下，LLM 逐 Token 输出，如果 Agent 在流式输出中途崩溃，检查点通常只保存到「上一轮完整回复」而非「当前流式回复的部分内容」。恢复时会导致用户看到「回复说了一半没了然后接上新的」的糟糕体验。解决方案：对于流式 Agent，检查点应包含「流式缓冲区」（已输出但未完成的 Token 序列），恢复时先用流式方式回放已输出的部分，再继续生成。Or，简化处理：仅在每轮完整回复后保存检查点，避免中途保存。

1. **检查点依赖 LLM 上下文「温度」不可复现**：LLM 推理本质上是概率性的——即使从完全相同的历史消息恢复，带 temperature > 0 的模型可能产生不同的后续输出，导致「恢复后的执行路径与原始路径偏离」。这对「精确复现」场景（如审计、调试）是致命的。解决方案：检查点中保存模型的采样参数（temperature、seed），恢复时使用相同的参数调用 API；对于不支持固定 seed 的模型（如某些旧版本），应在检查点中直接缓存 LLM 推理结果（消息内容），恢复时替换原始回复而非重新推理。

• LangGraph 官方文档 - Persistence & Checkpoints: https://langchain-ai.github.io/langgraph/concepts/persistence/

• Anthropic - Building Effective Agents (含容错设计): https://www.anthropic.com/engineering/building-effective-agents

• OpenAI Agents SDK - Conversation & Session Management: https://openai.github.io/openai-agents-python/

• Temporal.io - Durable Execution for Long-Running Workflows: https://docs.temporal.io/develop/python/durable-execution