Agent 长任务的可靠性:检查点、幂等与断点续跑
目录
热点引入:当 Agent 开始「上长班」
2026 年 9 月,Cognition 发布 SWE-2 异步软件工程模型,明确面向长程、异步的软件工程任务——不再是「一问一答」,而是把需求丢给它,几个小时后交付一个可用的分支。这类任务的共同特征是:步骤数以百计、跨越数十次工具调用、运行期间模型与外部世界持续交互。能力叙事之外,一个更朴素的问题浮出水面:长任务几乎必然中途失败。
上下文窗口会溢出,某个工具调用会超时,进程会被 OOM killer 杀掉,网络会抖。短任务失败重跑即可,长任务重来的代价可能是几小时的计算和一笔不小的账单。可靠性,从「加分项」变成了「能不能用」的前提。
本文聚焦三个相互咬合的机制:检查点(checkpoint)、幂等(idempotency)与断点续跑(resume)。它们分别回答三个问题:状态怎么存、失败后怎么安全地重来、以及怎么接着干而不是从头来。这是把 Agent 从 Demo 推向生产系统的分水岭。
技术原理:长程 Agent 为什么会「掉链子」
先给失败分类,否则优化无从下手。长程 Agent 的失败大致四类:
- 上下文溢出:历史消息无限增长,终将撞上 token 上限;即便不撞,关键信息也会被海量中间输出稀释,导致「迷失在中间」。
- 步骤失败:单次工具调用可能超时、被限流、返回脏数据,这是分布式系统的常态,不是意外。
- 重复执行:崩溃恢复后若简单重试,已提交的副作用(发帖、转账、改文件)会被执行两次,酿成事故。
- 状态丢失:进程一挂,内存里的对话历史、计划、中间结果全部蒸发,几小时的工作归零。
对应三道防线。
检查点是把每一步的「输入—决策—工具结果—状态快照」持久化。它不是简单写日志,而是可重建执行现场的最小完备状态:给定检查点,系统应能恢复到一个一致的、可继续推进的状态。实践中常把状态机当前状态、已完成任务、压缩后的上下文摘要、工具结果缓存一起落库。
幂等性是让工具「重试安全」。核心手段是给每个操作分配唯一 operation_id,由服务端或本地去重层做仲裁:同一 ID 的重复请求直接返回首次结果,不再产生副作用。没有幂等,断点续跑就是一个危险动作——你无法确定崩溃发生在副作用提交之前还是之后。
断点续跑是启动时从最近一个有效检查点恢复,而非重头执行。它把「重跑成本」从 O(任务总长) 降到 O(剩余步数)。三者的关系可以概括为一句话:检查点提供「从哪续」,幂等保证「续得安全」,断点续跑是前两者叠加后的收益。
此外还有两个保护阀:最大步数防止 Agent 陷入自我重复的死循环,单步超时防止一次调用无限挂起。它们与状态机配合——每一步都是状态机的一次合法迁移,非法迁移直接拒绝并落错,避免带着脏状态继续跑。
实操:用 SQLite 实现持久化 Agent Loop
先看检查点与状态机的核心实现。SQLite 单文件、事务安全、零运维,足以撑起单机 Agent 的检查点存储。关键在于:每完成一步,在一个事务内同时写入状态与工具结果,保证「步骤完成」与「检查点落盘」是原子的。
| |
think 负责基于当前上下文产出下一步动作,act 执行具体工具。注意恢复逻辑:只要传入同一个 run_id,load 就能取回上次的状态并自然续跑,调用方无需感知「这是第一次还是第 N 次启动」。
实操:幂等工具与去重表
接下来把「有副作用」的工具包一层幂等。操作 ID 必须由业务语义稳定派生——同样的输入永远得到同样的 ID,而不能每次调用都随机生成,否则去重无从谈起。
| |
实操:可观测性与恢复入口
最后补上结构化日志与 trace。长任务出了问题时,你需要回答「它卡在哪一步、当时状态是什么」,散乱的 print 无法支撑这种追溯。用 trace_id 串起同一次 run 的所有步骤,日志直接输出 JSON,便于采集与检索。
| |
工程实践建议与踩坑
几点来自实战的经验,能帮你绕开常见的坑。
检查点频率与成本的权衡。 一步一存最安全,但单步很廉价时频繁落盘的 I/O 开销可观。折中是按「逻辑里程碑」落盘——每完成一次有副作用的调用或每 N 步存一次,接受最多丢失 N 步的代价。选哪档取决于单次重跑成本与落盘成本的比值。
幂等键要防并发竞态。 上面 run_once 在单进程内没问题,但多进程同时处理同一 operation_id 时,两个请求可能都通过了查询、都执行了 fn(),只是插入时有一个被 INSERT OR IGNORE 丢弃——副作用却已经发生两次。生产环境应改为「先插入占位行(带 pending 状态)拿到唯一所有权,再执行副作用,最后更新结果」,用数据库唯一约束做分布式锁。
给幂等记录设 TTL。 去重表无限膨胀会拖慢查询。按业务窗口设置过期时间(例如保留 7 天),超过窗口的请求视为新操作。但要注意:TTL 必须长于「最长可能的重试间隔」,否则迟到的重试会穿透去重。
上下文压缩要外置。 摘要可以进检查点,但工具返回的大块内容(网页、日志)应落对象存储,检查点只留引用,否则它会膨胀成新的「溢出源」。推荐「近期原文 + 远期摘要」的分层结构。
恢复前先做状态校验。 检查点可能因版本升级而结构变化,读取时校验 schema 版本;不兼容的旧检查点要么走迁移,要么明确报错——带病续跑比直接失败更危险。
小结
长程 Agent 的可靠性不是靠「让模型更聪明」解决的,而是靠朴素的工程手段:用检查点保存可重建的执行现场,用幂等把工具变成可安全重试的原语,用断点续跑把失败成本从「全量」压缩到「增量」,再用状态机、步数上限与超时兜住失控边界,用结构化日志留住追溯线索。
当任务从分钟级走向小时级,这些机制不再是锦上添花,而是区分「能演示」与「能上生产」的那条线。先把失败当成默认前提来设计,你的 Agent 才能在真实的异步世界里跑得久、跑得稳。