AI Agent 长任务怎么保存中间状态：checkpoint、恢复点与幂等回放验收

AI Agent 执行几分钟甚至几小时的长任务时，真正难的不是让它走完第一步，而是遇到进程重启、网络中断或者单个工具调用失败后，还能从正确的节点接着往下跑。解决这类问题的核心思路不是堆更多提示词，而是把整个执行过程切出可恢复的 checkpoint：存好已经确认的事实、下一步执行计划和幂等边界，再用回放测试把恢复路径跑通验证。

上下文漂移到底发生在哪里

大家常说的上下文漂移，很多时候根本不是模型突然忘了指令。更普遍的情况是应用层在拼接消息的时候就已经弄丢了事件边界：比如一次搜索请求的结果被错当成另一次请求的返回，超时重试生成了两个响应，或者旧会话里的工具输出没有和当前会话状态做正确隔离。模型只能拿到应用层传给它的消息做关联推断，不可能反过来帮应用补上已经丢了的关联标识。

所以我们可以先把一次工具调用拆成三个独立对象：请求事件、执行事件和结果事件。请求事件记录工具名、参数摘要和调用标识；执行事件记录开始、结束、重试和超时状态；结果事件记录可以给模型做推理参考的事实。三类事件共用同一个 tool_call_id，后续日志、缓存和消息编排才能准确指向同一条执行链路。

tool_call_id 不是普通流水号

调用标识要在模型刚决定调用工具的时候就生成，全程跟着队列、执行器、重试器和最终消息流转。不能等工具返回结果的时候才临时创建，也不能直接用数组下标代替。毕竟并行调用的完成顺序可能和发起顺序不一样，数组位置会随着排序、过滤、重试操作不停变动，很容易错乱。

{
  "tool_call_id": "call_weather_01J9X7",
  "tool_name": "get_weather",
  "status": "succeeded",
  "facts": {"city": "Shanghai", "temperature_c": 28},
  "display_summary": "上海当前 28°C",
  "error": null
}

往数据库或者缓存里存数据的时候，建议把会话标识、回合标识和工具调用标识分开存。会话用来做用户隔离，回合用来定位某一次模型决策动作，调用标识用来定位单个工具事件。如果把三者混成一个 key，后面出问题的时候重试和并行分支的问题根本没法排查。

给工具结果划出三条边界

工具返回的原始响应里通常包含 HTTP 头、服务商调试字段、分页游标和内部错误信息，这些内容没必要直接全部塞进模型上下文里。推荐把结果拆成三层：「事实字段」「用户可见摘要」「仅日志字段」。事实字段保持稳定、机器可读；摘要服务于当前回合的模型推理；日志字段留在观测系统里，后续需要的时候再通过调用标识查询调取。

做这个分层还有个好处：当模型需要更详细的数据时，应用层可以基于 tool_call_id 主动发起一次明确的「展开结果」请求，不用第一次返回结果就把所有内容都塞进去。上下文窗口的占用会更可控，敏感字段也更容易留在服务端边界里，不会意外外泄。

并行工具调用要保留未完成状态

两个工具同时执行的时候，先返回的结果不能代表另一个工具返回了空值。编排器要为每一个调用单独保存明确状态，比如 pending、succeeded、failed 和 timed_out。只有在业务策略明确允许继续执行的场景下，才把部分返回结果交给模型，同时明确告知它哪些调用还没跑完。

parallel batch
  ├─ call_inventory: succeeded
  ├─ call_price: timed_out (retryable)
  └─ context: partial_result, do_not_infer_missing_price

这里说的「不要推断缺失价格」不是加提示词做限制，而是内置在状态机里的规则。应用可以往结果消息里写入机器可读的 missing_fields 字段，在业务层直接拦截模型生成的确定性结论，直到所有必要的工具调用全部完成。

重试时如何避免旧结果污染

超时重试是最容易生成重复响应的场景。重试操作应该生成新的执行尝试编号，但沿用同一个逻辑 tool_call_id，并且在结果里记录 attempt 字段。落库的时候用「调用标识加尝试编号」做唯一约束保证幂等，最终编排逻辑只接收符合当前策略的那一个有效结果。

如果第一次调用实际上已经成功，只是回调超时没收到通知，第二次重试不能直接覆盖原有结果。反过来，执行器需要先查询对应调用的当前状态，再判断要不要真的发起远端请求。针对本身不支持幂等的工具，必须把这个状态查询步骤放在重试动作之前，不然 Agent 很可能重复创建订单、发送通知或者修改线上资源。

五组回归用例必须覆盖

• 并行完成顺序打乱：验证每个返回结果仍然能对应到正确的 tool_call_id。
• 第一次超时、第二次成功：验证上下文只会消费最终的有效结果，全量日志里仍然保留两次尝试记录。
• 部分成功：验证模型明确知道哪些字段缺失，不会主动从旧回合的历史内容里猜测补全。
• 重复投递同一结果：验证消息自动去重，不会生成两条重复事实记录。
• 原始结果超长：验证只保留摘要和必要事实，调试类内容不会进入模型上下文。

常见问题

tool_call_id 必须由模型生成吗？

不建议完全依赖模型自行生成。应用层要提前校验格式、唯一性和当前回合归属，等调用进入执行队列的时候就建立不可变的关联关系。

工具失败后要不要把完整错误交给模型？

通常只返回可行动的错误类别、是否可重试和下一步操作限制就行。堆栈、内部 URL 和密钥相关的敏感字段都留在日志系统里，不要透传给模型。

摘要会不会丢失重要信息？

有可能，所以摘要不能直接替代事实字段。稳定的业务事实保留结构化字段，摘要只负责帮助当前回合快速阅读，必要时还可以通过调用标识再次展开全量内容。

把工具结果当成可验收的事件

稳定性合格的 Agent 不会把执行逻辑赌在「模型应该能记住前文」这种不确定的假设上，而是给每个工具结果都配上清晰的身份、状态和可消费边界。先用 tool_call_id 把全链路串起来，再把事实、摘要和调试三类信息做分层隔离，最后用并行、重试和部分成功等场景的用例做回归验证，就能把上下文漂移从没法定位的玄学问题，变成完全可控可排查的工程问题。