Agent 跑到一半挂了是做 Agent 落地的人迟早要撞上的事。我维护某客服工单处理系统时一个多步骤 Agent 任务跑了半个多小时调用了二十多次模型结果倒数第二步因为第三方物流接口限流直接抛错。整个任务从头重跑Token 花了两倍用户还在那多等了十分钟。那之后我下定决心把“断点继续”做进 Agent 的底层框架这篇就讲我在实战里总结出来的完整方案失败到底长什么样、检查点怎么设计、工具调用的重复副作用怎么处理、什么断点值得救、恢复时有哪些暗坑。适合正在做 Agent 应用的人看尤其是那些被重跑成本、Token 浪费、任务不可恢复折磨过的同学。这篇不聊概念全是能落地的设计思路和代码结构。1. 先搞清楚失败长什么样Agent 中断的常见形态与根因做断点恢复之前必须先把你遇到的“失败”分类。我见过太多人一上来就写恢复逻辑结果恢复逻辑本身就是个脆弱的玩具因为连失败发生在哪个阶段都没搞清楚。1.1 进程级失败与逻辑级失败两种不同的恢复思路Agent 跑挂了从表象上看是“任务没完成”“报错了”但底层原因可以分成两大类。进程级失败是指运行环境出了问题内存溢出、容器被杀、部署重启、依赖服务崩溃、进程被 OOM Killer 干掉。这类失败的特点是Agent 的整个状态包括保存在内存里的聊天记录、任务队列、中间变量全部没了。逻辑级失败则是指 Agent 自身在“规划—执行—观察”循环中走入了死胡同上下文溢出、模型输出格式不符合解析要求、工具调用返回了意外结构、规划步骤形成了死循环或者某一步抛出了没有兜底的异常。这两类的恢复策略完全不同。进程级失败只要能拿回外部持久化的状态原地重建执行环境就可以续跑。逻辑级失败单纯续跑往往没用因为导致失败的条件还在你得先修正计划、截断上下文或者切换策略。我在最初设计恢复机制时犯过的一个错误就是把所有失败都当成“抛异常”处理。后来发现上下文溢出根本不会抛异常就是模型输出忽然变得乱七八糟解析器报错然后整个循环结束。这类失败如果只做“重试”只会把同样的错误再来一遍。1.2 按执行层拆解失败点模型、工具、编排三处最脆弱把 Agent 一次完整执行拆开看失败概率最高的就三处模型调用、工具调用、编排解析。模型调用这层的失败主要是超时、限流、服务不可用以及最要命的“输出不符合预期”。输出不符合预期包括JSON 格式破裂、字段缺失、意图偏移、废话连篇。这层失败的特征是失败点之前的状态往往还是干净的重试的代价也可控。工具调用这层的失败就复杂了。第三方 API 超时、返回 5xx、返回结构变化、限流限频都会导致 Agent 拿不到可用观测结果。更麻烦的是工具调用可能有副作用——扣费、发消息、写数据库、调外部系统。这类失败不能简单重试因为上一次调用可能已经在服务端执行成功了只是结果没传回来。编排层的失败则发生在我们自己写的 Agent 框架里。比如多步执行的状态管理冲突、步骤依赖关系断裂、上下文窗口被塞满、规划进入死循环。这类失败最隐蔽因为它不像模型调用那样有明确的错误码往往需要翻日志才能定位。有一个很反直觉的事实真正让 Agent 任务全盘崩溃的往往不是模型而是我们对工具返回值的处理太草率。模型偶尔偷个懒、格式飘一下只要解析层做了容错都能救回来。但工具调用一旦带着副作用失败后续所有步骤的状态就不可信了。1.3 一个真实的任务执行链路里状态到底存在哪要设计断点恢复你得先回答一个问题一个 Agent 任务在任意时刻状态的完整集合是什么我用过的最朴素但有效的模型是从四个维度记录状态。任务级元数据任务 ID、目标描述、创建时间、当前阶段、已重试次数。执行计划与进度规划出来的步骤列表哪些步骤已完成哪些正在执行。上下文消息历史和模型交互的完整消息列表包括系统提示、用户目标、历次助手回复、工具调用结果。工具调用的副作用账本哪些工具被调过、传了什么参数、返回了什么结果、是否确认成功。这四个维度缺一个恢复的时候就会出问题。比如只保存消息历史不保存步骤进度那恢复时就得从第一条消息重新推理虽然模型能“回忆”出之前干了什么但工具已经带副作用执行过了重推的时候很可能重复调用。我在实际项目里习惯把所有状态统一存在一个可持久化的状态对象里每个步骤执行前都序列化一次。这样崩溃之后我拿到的不是一段孤立的日志而是“这个任务在那一刻的完整照片”。2. 断点继续的底层思路把 Agent 执行当成一条可回放的日志很多人一听“断点继续”第一反应是“把模型实例存下来”。这是误区大模型服务本身是无状态的你根本存不下“模型的思考状态”。能存下的只有执行环境里那些可以被回放和重建的数据。2.1 核心认知Agent 是状态机不是函数我踩过最大的坑就是把 Agent 当成一个大函数觉得“调用它、等结果”就行了。实际上一个负责多步骤任务的 Agent 是一个状态机每执行完一步状态就向前推进一截每调用一次工具外部世界就产生了一处变化。状态机的好处是任何一步执行完只要把当前状态落盘就算后面全部崩溃也能回到落盘点重新往下走。坏处是状态机里每个步骤都不是纯粹的它夹着模型推理和工具副作用所以恢复起来比普通重试要复杂得多。用游戏存档来类比就很容易理解。你玩一个长流程游戏每过一个关卡系统帮你存档下次进入游戏读档你不需要把整个关卡重新打一遍。Agent 也一样每个“关卡”就是一次模型调用加一次工具执行存档就是状态快照。但 Agent 比游戏存档麻烦的地方在于游戏存档只需要记录角色位置、血量、物品栏而 Agent 要记录的不仅有“当前走到哪一步了”还有“之前调用过哪些工具、产生了什么结果、哪些副作用已经生效”。这些信息散落在代码里、数据库里、外部 API 里收集起来比想象中麻烦。2.2 事件溯源与状态快照两种持久化策略的取舍做状态持久化我实际尝试过两条路事件溯源和定期快照。事件溯源的做法是把每一步的执行过程追加写入一条不可变事件记录。比如“模型生成了计划”“工具 A 被调用参数是 X返回 Y”“步骤 2 完成”。恢复的时候从头把事件重放一遍就能把状态重建到最后一条事件对应的位置。定期快照的做法是每隔几个步骤或者每个步骤结束时把完整状态对象一次性序列化保存下来。恢复的时候直接加载最近的快照不需要重放。两条路各有适用场景。事件溯源的优点是粒度细、可审计、能精确恢复到最后一步缺点是重放成本高事件多了以后很慢。快照的优点是恢复快、实现简单缺点是丢失两次快照之间的状态变化而且如果状态对象里有不可序列化的内容快照就存不了。我在生产环境用的是混合方案每个步骤完成时打一个轻量快照同时把关键事件按日志形式追加。恢复时先加载最近的快照再用事件日志把进度推进到中断点之前的最后一个有效状态。这样既有兜底又有精度。2.3 保存时机不是每次调用都要存但不是每次都能偷懒什么时候落盘一次这个问题我见过很多种答案。有人只在任务开始时存一次有人等任务完成后存一次有人每一步都存。我的建议是模型调用发出去之前存一次工具调用发出之前存一次这两个时机是必须打点的。理由很简单模型调用之前存的状态是“这一步还没开始”的干净状态如果调用超时或模型输出无法解析从这个状态重试毫无压力。工具调用之前存的状态则是“副作用尚未发生”的状态一旦工具调用失败可以判断副作用到底产生了没有再决定是重试还是清理。至于工具返回之后、进入下一个步骤之前建议也存一次因为这时候工具的结果已经进入了上下文下一步要基于这个结果继续推理。错过这个点恢复后就得多一次推理才能重建同样的上下文。存太频繁也有代价。每一步都全量序列化遇到大上下文时序列化时间和存储开销都会上涨。我后来把序列化拆成了两层高频轻量层只存步骤 ID、步骤状态、关键变量低频全量层才存完整上下文。这样崩溃后先拿轻量层快速定位需要时再加载全量上下文。3. 检查点方案的落地设计状态结构、保存流程与恢复算法思路理清之后最重要的就是把检查点机制落进代码里。下面是一套我在实际项目里验证过的设计可以直接照搬微调。3.1 三类状态表结构任务、步骤、工具调用账本状态持久化用关系数据库或者文档数据库都行关键是表结构要能表达任务执行的层次关系。我设计过三张核心表结构如下。任务表记录任务的全局信息{ task_id: task_20250101_001, goal: 处理售后工单需要完成退换货流程, status: in_progress, current_step_id: step_7, plan: [step_1: 调用户订单接口, step_2: 校验售后条件, ...], attempt_count: 3, max_attempts: 5, created_at: 2025-01-01 10:00:00, updated_at: 2025-01-01 10:25:30 }步骤表记录每个步骤的执行状态{ step_id: step_7, task_id: task_20250101_001, step_desc: 调用物流接口获取最新轨迹, status: failed, depends_on: [step_6], retry_count: 1, input_snapshot: {\order_id\: \PO20250101\}, output_snapshot: null, error_info: api_rate_limit_exceeded, started_at: 2025-01-01 10:20:00, finished_at: null }工具调用账本表专门记录带副作用的调用{ call_id: toolcall_1042, task_id: task_20250101_001, step_id: step_7, tool_name: logistics_track, arguments: {\order_id\: \PO20250101\}, status: executed_unknown, idempotency_key: task_20250101_001_step_7_logistics_track, response_summary: null, created_at: 2025-01-01 10:20:05 }需要注意的关键字段是工具调用表里的idempotency_key它保证了即使在网络超时的情况下也能识别“这个调用我是不是已经发出过”后面讲副作用处理时再展开。3.2 保存流程每个关键节点都写一次“状态照片”检查点保存的代码逻辑我推荐写成一个装饰器或者执行器内部的回调函数而不是散落在业务代码里。伪代码如下。async def run_agent_step(task_state, step): # 1. 在模型调用前保存状态 checkpoint(task_state, phasebefore_model_call) # 2. 调用模型生成回复 response await call_model(task_state.messages) if not is_valid(response): # 模型输出无效从 before_model_call 检查点恢复 raise RecoverableCheckpointError(model output invalid) # 3. 如果模型要求调用工具则在调用前记录账本 if response.tool_calls: for tool_call in response.tool_calls: record_tool_call(task_state, tool_call) # 在工具调用发出前保存状态 checkpoint(task_state, phasebefore_tool_call) # 4. 执行工具调用 tool_results await execute_tool_calls(response.tool_calls) # 5. 把结果写回上下文并保存状态 task_state.messages.append(tool_result_message) checkpoint(task_state, phaseafter_tool_call) # 6. 更新步骤状态 mark_step_complete(task_state, step) checkpoint(task_state, phasestep_complete)这段代码看起来简单实际运行起来你会发现真正让恢复变得可靠的不是哪一次单独的保存而是“模型前、工具前、工具后、步骤后”这四个点的组合。3.3 恢复算法定位最后一个干净状态沿步骤续跑恢复算法不需要多高深核心就三条找到最近的干净检查点、确认哪些步骤已经完成、从失败步骤的下一个可执行步骤继续往下走。async def recover_task(task_id): # 1. 读取任务状态和检查点 task_state load_latest_checkpoint(task_id) # 2. 找出所有未完成且可执行的步骤 pending_steps get_pending_steps(task_state) # 3. 如果不依赖已完成步骤且不是重试陷阱就继续执行 for step in pending_steps: if step.status completed: continue if not dependencies_satisfied(task_state, step): continue task_state.current_step_id step.step_id step.retry_count 1 # 4. 如果该步骤已经产生过副作用先做幂等校验 if has_side_effect_record(step): side_effect check_side_effect_status(step) if side_effect confirmed_success: mark_step_complete(task_state, step) continue elif side_effect unknown: # 需要人工或自动确认 await confirm_or_cleanup(step) # 5. 重新执行当前步骤 await run_agent_step(task_state, step) # 6. 所有步骤完成后汇总输出 return task_state这里有个容易被忽略的细节恢复时的上下文消息列表不能简单地把所有历史消息全部塞回模型输入。因为 Agent 执行到一半失败时上下文里可能已经积累了很长一大段对话其中很多内容在规划决策中已经没有价值了。恢复时应该基于“最近 N 轮有效交互 任务初始目标 已完成步骤摘要”来重建上下文既节省 Token又让模型更快进入状态。4. 最难的坑工具调用的副作用怎么避免重复和漏处理如果说状态保存是断点继续的地基那工具调用的幂等性处理就是地基里最容易塌的那块砖。恢复做得再好只要工具被执行了两次业务上的账就乱了。4.1 为什么“执行失败”不等于“没有执行”最常见的场景是第三方 API 调用超时。你的 Agent 调用了支付接口请求发出去了但等待响应时连接断了代码这边认为调用失败。实际上服务端那边可能已经扣款成功、已经发了消息、已经改了订单状态。这种情况下如果你在恢复时直接重试这个工具调用就会导致重复扣款、重复发消息。更麻烦的是如果你不重试又可能错过真正还没执行的那个操作。这是分布式系统里经典的“at-least-once vs at-most-once”问题。对 Agent 来说大部分步骤我们都能接受“至少执行一次”但带财务性质、通知性质、写操作性质的工具调用必须做到“最多执行一次”或者“精确识别已执行”。4.2 幂等键与“先记账后执行”模式我的做法是规定所有可能产生副作用的工具调用在真正发出去之前先在工具调用账本里写入一条status pending的记录并生成一个幂等键。这个幂等键通常由任务 ID 步骤 ID 工具名 参数哈希组成。然后调用第三方接口时把幂等键作为请求头或者请求体字段一起传过去。凡是支持幂等键的服务端都会对相同幂等键的请求自动去重。async def execute_tool_with_idempotency(task_state, tool_call): key build_idempotency_key(task_state, tool_call) # 1. 先记账 record create_tool_call_record( task_idtask_state.task_id, step_idtool_call.step_id, tool_nametool_call.name, argumentstool_call.args, idempotency_keykey, statuspending ) # 2. 再执行 try: result await call_tool_api(tool_call, idempotency_keykey) mark_tool_call_success(record.id, result) return result except Exception as e: # 3. 失败时不能直接标失败要检查服务端状态 actual_status await probe_tool_execution_status(key) if actual_status success: # 实际已执行成功只是响应丢了返回缓存的成功结果 mark_tool_call_success(record.id, None) return retrieve_cached_result(key) else: mark_tool_call_failed(record.id, e) raise注意这里的probe_tool_execution_status它的作用是主动查询服务端确认这笔操作到底发生了没有。如果服务端提供查询接口这招最保险。如果查不了就只好把这种“未知状态”的调用交给下一节的人工确认流程。4.3 无法确认的工具调用标记为“未知”而不是“失败”很多第三方 API 根本不提供幂等键也不提供查询接口。这时我们要做的是诚实——把工具调用的状态标记为executed_unknown而不是直接标记为失败。executed_unknown状态在恢复算法里是个特殊分支。遇到这种分支我不自动重试也不直接跳过而是把这个异常情况抛给一个人工确认队列。操作人员看一遍调用参数和上下文手动确认这笔操作是否已生效然后决定是跳过还是补做还是回滚。这在自动化体系里看似笨拙但却是业务安全的关键一环。我宁可让人工确认一次模糊状态也不愿意让系统在无感知的情况下重复扣费。5. 不是所有断点都值得救恢复决策与人工介入机制做断点恢复做到后面你会遇到一个更深层的问题这个断点该不该恢复恢复的成本可能比重跑还高甚至恢复本身就是错的。5.1 用三个维度判断“是否值得从断点继续”我总结了一个简单的判断框架三个维度分别是失败类型、副作用风险、剩余工作量。失败类型决定了恢复策略的可行性。如果是限流、超时这类临时性故障恢复的把握很大。如果是模型上下文溢出、规划死循环这类逻辑性故障光恢复没用还得调整策略。如果是外部 API 返回结构彻底变化那就要先改代码再恢复。副作用风险决定了恢复是否需要额外确认。带资金、通知、写库性质的操作恢复前的确认成本很高纯读取类的工具调用随便重试。剩余工作量决定了恢复的性价比。如果已经执行了 80% 的步骤恢复是明智的。如果才跑到第二步就挂了直接整个任务重跑反而简单。我把这些规则做成了一张决策表每次恢复前自动过一遍。场景失败原因举例副作用风险建议动作模型调用限流429 或超时低重试当前步骤等待退避模型输出解析失败JSON 破损、字段缺失低截断重试或改用更宽松解析器工具调用超时第三方接口无响应高先查询状态真失败再重试上下文溢出context 超限中摘要历史后重试或切换规划策略规划死循环同一操作循环执行中中断并人工介入修改计划外部接口结构变更API schema 不匹配中人工介入升级适配层5.2 设置恢复上限别让断点续跑变成无限循环断点恢复最危险的情况是同一个步骤失败后反复恢复、反复执行形成一个看不见的循环。尤其当工具调用是幂等的、返回结果总是失败时这个循环会白白消耗大量 Token还会拖慢整个任务队列。我设置了两层上限。第一层是单步重试上限。同一步骤的连续失败次数达到上限后不再自动重试而是进入人工队列。第二层是任务级恢复上限。整个任务从断点恢复的总次数也设上限比如一个任务最多恢复 5 次超过之后强制进入人工处理。上层逻辑简单但极有效。我见过一个真实的线上事故某个数据处理 Agent 在调用日期解析工具时因为时区参数传错了每次恢复都得到一样的结果任务在几个小时内反复自动重试了一百多次。设置恢复上限之后这种问题最多浪费到第 5 次就会被人工发现。5.3 人工介入通道给恢复系统留一个“人肉出口”无论自动化做得多么完善总有一些断点是需要人来判断的。我把人工介入设计成恢复流程里的一等公民而不是最后兜底。具体做法是给每个“待人工确认”的任务生成一个结构化面板面板里包含目标描述、当前步骤、失败原因、最近几次工具调用的参数与结果、恢复建议选项重试/跳过/回滚/终止。操作者点一下就能选择后续动作。这里有个经验之谈人工介入面板的信息要少而精。当初我把大量日志全塞进面板操作者反而找不到重点。后来精简成“目标、断点位置、失败原因、推荐动作”四块信息处理效率高了很多。6. 生产环境里的隐藏细节上下文重建、反序列化与并发隔离前面几节已经把断点恢复的主体方案讲清楚了但真正投入生产后还会有三个细节问题每一个都能让你的恢复机制在关键时刻崩掉。6.1 上下文重建恢复时如何不把 Token 撑爆长任务的 Agent 执行到一半上下文里可能攒了几百条消息。恢复时如果把这些原封不动全塞回去有两个后果一是 Context Window 可能直接溢出二是模型注意力被大量历史噪音分散决策质量下降。我的做法是分层重建上下文核心层系统提示、用户原始目标、当前步骤描述、最近 5 轮关键交互。摘要层更早的历史消息压缩成一段结构化摘要包含已完成步骤、重要工具结果、关键决策。工具层最近一次工具调用原文确保模型能基于最新的观测结果继续推理。摘要的生成可以用模型来做也可以用规则抽取。规则抽取更可控模型摘要更自然我目前用的是“规则抽取 模型润色”的混合方式。6.2 反序列化的坑状态里别放模型实例和临时对象写检查点时状态对象里哪些字段会被序列化直接影响恢复的可靠性。我在早期犯过的错是把pandas.DataFrame、PIL.Image、requests.Session、不稳定的模型实例等对象直接放进了状态里。结果序列化时要么报错要么存了一个巨大的二进制块恢复时还得重新初始化。后来我定了一个规则状态里只允许放基本类型、JSON 可序列化的字典和列表。所有重对象一律在恢复后重建。比如数据库连接、HTTP 客户端、模型实例都由恢复函数重新创建。这条规则想起来容易执行时容易漏。建议在检查点保存函数里加一个校验序列化之前递归检查一遍发现不可序列化对象直接报错而不是等到恢复时才发现坏了。6.3 并发与文件锁多任务同时恢复时的隔离问题最后一个坑是并发恢复。当 Agent 框架部署成多副本多个任务同时崩溃、同时恢复时很容易出现两个恢复流程同时操作同一个任务的状态导致数据互相覆盖。我的解决方案是引入任务级锁。每个任务的恢复流程开始前先尝试获取分布式锁拿到锁的才能继续恢复拿不到锁的等待或者放弃。同时检查点事务要保证原子性读取和写入之间不能用非原子操作。实现锁的方式很多数据库唯一索引、Redis 锁、或者文件锁都可以。关键在于锁一定要在“读取检查点”之前获取否则你读到的可能正是另一个流程正在写入的中间状态。7. 我踩过几次坑之后的最终经验做完这套断点恢复机制最大的感悟是断点继续不是附加功能而是 Agent 系统的刚需。哪怕你现在的 Agent 任务很短、很稳定也建议从一开始就把状态持久化做上否则任务一旦变长你会被重跑成本和教育用户重新等待的时间拖住。几个实战建议供参考。第一保存时机宁可多不要少。模型调用前、工具调用前、工具调用后三步打点是底线多打几次不会错少打一次恢复时就可能乱。第二恢复时在系统提示词里明确告诉模型“这是一个从断点恢复的任务”。实测下来模型知道自己在续跑时会更多参考已完成步骤的信息减少重新规划的冲动。第三用故障注入测试恢复逻辑。人为制造模型超时、工具乱序返回、进程杀死的场景验证检查点和恢复链路是否真的可靠别等到线上出问题才后悔。这套方案上线之后我们的长任务成功率提升了一大截最有价值的地方还不是省 Token而是让运营和开发不再恐惧“长任务跑了一半失败”这种事故。要是你的 Agent 也在为同样的痛点头疼按这个思路落地一遍应该能少走不少弯路。 
长河君 · 2026/10/15 22:03:54 · 阅读 1.2k Agent断点续跑实战：从状态持久化到工具副作用处理的完整方案
Agent 跑到一半挂了是做 Agent 落地的人迟早要撞上的事。我维护某客服工单处理系统时一个多步骤 Agent 任务跑了半个多小时调用了二十多次模型结果倒数第二步因为第三方物流接口限流直接抛错。整个任务从头重跑Token 花了两倍用户还在那多等了十分钟。那之后我下定决心把“断点继续”做进 Agent 的底层框架这篇就讲我在实战里总结出来的完整方案失败到底长什么样、检查点怎么设计、工具调用的重复副作用怎么处理、什么断点值得救、恢复时有哪些暗坑。适合正在做 Agent 应用的人看尤其是那些被重跑成本、Token 浪费、任务不可恢复折磨过的同学。这篇不聊概念全是能落地的设计思路和代码结构。1. 先搞清楚失败长什么样Agent 中断的常见形态与根因做断点恢复之前必须先把你遇到的“失败”分类。我见过太多人一上来就写恢复逻辑结果恢复逻辑本身就是个脆弱的玩具因为连失败发生在哪个阶段都没搞清楚。1.1 进程级失败与逻辑级失败两种不同的恢复思路Agent 跑挂了从表象上看是“任务没完成”“报错了”但底层原因可以分成两大类。进程级失败是指运行环境出了问题内存溢出、容器被杀、部署重启、依赖服务崩溃、进程被 OOM Killer 干掉。这类失败的特点是Agent 的整个状态包括保存在内存里的聊天记录、任务队列、中间变量全部没了。逻辑级失败则是指 Agent 自身在“规划—执行—观察”循环中走入了死胡同上下文溢出、模型输出格式不符合解析要求、工具调用返回了意外结构、规划步骤形成了死循环或者某一步抛出了没有兜底的异常。这两类的恢复策略完全不同。进程级失败只要能拿回外部持久化的状态原地重建执行环境就可以续跑。逻辑级失败单纯续跑往往没用因为导致失败的条件还在你得先修正计划、截断上下文或者切换策略。我在最初设计恢复机制时犯过的一个错误就是把所有失败都当成“抛异常”处理。后来发现上下文溢出根本不会抛异常就是模型输出忽然变得乱七八糟解析器报错然后整个循环结束。这类失败如果只做“重试”只会把同样的错误再来一遍。1.2 按执行层拆解失败点模型、工具、编排三处最脆弱把 Agent 一次完整执行拆开看失败概率最高的就三处模型调用、工具调用、编排解析。模型调用这层的失败主要是超时、限流、服务不可用以及最要命的“输出不符合预期”。输出不符合预期包括JSON 格式破裂、字段缺失、意图偏移、废话连篇。这层失败的特征是失败点之前的状态往往还是干净的重试的代价也可控。工具调用这层的失败就复杂了。第三方 API 超时、返回 5xx、返回结构变化、限流限频都会导致 Agent 拿不到可用观测结果。更麻烦的是工具调用可能有副作用——扣费、发消息、写数据库、调外部系统。这类失败不能简单重试因为上一次调用可能已经在服务端执行成功了只是结果没传回来。编排层的失败则发生在我们自己写的 Agent 框架里。比如多步执行的状态管理冲突、步骤依赖关系断裂、上下文窗口被塞满、规划进入死循环。这类失败最隐蔽因为它不像模型调用那样有明确的错误码往往需要翻日志才能定位。有一个很反直觉的事实真正让 Agent 任务全盘崩溃的往往不是模型而是我们对工具返回值的处理太草率。模型偶尔偷个懒、格式飘一下只要解析层做了容错都能救回来。但工具调用一旦带着副作用失败后续所有步骤的状态就不可信了。1.3 一个真实的任务执行链路里状态到底存在哪要设计断点恢复你得先回答一个问题一个 Agent 任务在任意时刻状态的完整集合是什么我用过的最朴素但有效的模型是从四个维度记录状态。任务级元数据任务 ID、目标描述、创建时间、当前阶段、已重试次数。执行计划与进度规划出来的步骤列表哪些步骤已完成哪些正在执行。上下文消息历史和模型交互的完整消息列表包括系统提示、用户目标、历次助手回复、工具调用结果。工具调用的副作用账本哪些工具被调过、传了什么参数、返回了什么结果、是否确认成功。这四个维度缺一个恢复的时候就会出问题。比如只保存消息历史不保存步骤进度那恢复时就得从第一条消息重新推理虽然模型能“回忆”出之前干了什么但工具已经带副作用执行过了重推的时候很可能重复调用。我在实际项目里习惯把所有状态统一存在一个可持久化的状态对象里每个步骤执行前都序列化一次。这样崩溃之后我拿到的不是一段孤立的日志而是“这个任务在那一刻的完整照片”。2. 断点继续的底层思路把 Agent 执行当成一条可回放的日志很多人一听“断点继续”第一反应是“把模型实例存下来”。这是误区大模型服务本身是无状态的你根本存不下“模型的思考状态”。能存下的只有执行环境里那些可以被回放和重建的数据。2.1 核心认知Agent 是状态机不是函数我踩过最大的坑就是把 Agent 当成一个大函数觉得“调用它、等结果”就行了。实际上一个负责多步骤任务的 Agent 是一个状态机每执行完一步状态就向前推进一截每调用一次工具外部世界就产生了一处变化。状态机的好处是任何一步执行完只要把当前状态落盘就算后面全部崩溃也能回到落盘点重新往下走。坏处是状态机里每个步骤都不是纯粹的它夹着模型推理和工具副作用所以恢复起来比普通重试要复杂得多。用游戏存档来类比就很容易理解。你玩一个长流程游戏每过一个关卡系统帮你存档下次进入游戏读档你不需要把整个关卡重新打一遍。Agent 也一样每个“关卡”就是一次模型调用加一次工具执行存档就是状态快照。但 Agent 比游戏存档麻烦的地方在于游戏存档只需要记录角色位置、血量、物品栏而 Agent 要记录的不仅有“当前走到哪一步了”还有“之前调用过哪些工具、产生了什么结果、哪些副作用已经生效”。这些信息散落在代码里、数据库里、外部 API 里收集起来比想象中麻烦。2.2 事件溯源与状态快照两种持久化策略的取舍做状态持久化我实际尝试过两条路事件溯源和定期快照。事件溯源的做法是把每一步的执行过程追加写入一条不可变事件记录。比如“模型生成了计划”“工具 A 被调用参数是 X返回 Y”“步骤 2 完成”。恢复的时候从头把事件重放一遍就能把状态重建到最后一条事件对应的位置。定期快照的做法是每隔几个步骤或者每个步骤结束时把完整状态对象一次性序列化保存下来。恢复的时候直接加载最近的快照不需要重放。两条路各有适用场景。事件溯源的优点是粒度细、可审计、能精确恢复到最后一步缺点是重放成本高事件多了以后很慢。快照的优点是恢复快、实现简单缺点是丢失两次快照之间的状态变化而且如果状态对象里有不可序列化的内容快照就存不了。我在生产环境用的是混合方案每个步骤完成时打一个轻量快照同时把关键事件按日志形式追加。恢复时先加载最近的快照再用事件日志把进度推进到中断点之前的最后一个有效状态。这样既有兜底又有精度。2.3 保存时机不是每次调用都要存但不是每次都能偷懒什么时候落盘一次这个问题我见过很多种答案。有人只在任务开始时存一次有人等任务完成后存一次有人每一步都存。我的建议是模型调用发出去之前存一次工具调用发出之前存一次这两个时机是必须打点的。理由很简单模型调用之前存的状态是“这一步还没开始”的干净状态如果调用超时或模型输出无法解析从这个状态重试毫无压力。工具调用之前存的状态则是“副作用尚未发生”的状态一旦工具调用失败可以判断副作用到底产生了没有再决定是重试还是清理。至于工具返回之后、进入下一个步骤之前建议也存一次因为这时候工具的结果已经进入了上下文下一步要基于这个结果继续推理。错过这个点恢复后就得多一次推理才能重建同样的上下文。存太频繁也有代价。每一步都全量序列化遇到大上下文时序列化时间和存储开销都会上涨。我后来把序列化拆成了两层高频轻量层只存步骤 ID、步骤状态、关键变量低频全量层才存完整上下文。这样崩溃后先拿轻量层快速定位需要时再加载全量上下文。3. 检查点方案的落地设计状态结构、保存流程与恢复算法思路理清之后最重要的就是把检查点机制落进代码里。下面是一套我在实际项目里验证过的设计可以直接照搬微调。3.1 三类状态表结构任务、步骤、工具调用账本状态持久化用关系数据库或者文档数据库都行关键是表结构要能表达任务执行的层次关系。我设计过三张核心表结构如下。任务表记录任务的全局信息{ task_id: task_20250101_001, goal: 处理售后工单需要完成退换货流程, status: in_progress, current_step_id: step_7, plan: [step_1: 调用户订单接口, step_2: 校验售后条件, ...], attempt_count: 3, max_attempts: 5, created_at: 2025-01-01 10:00:00, updated_at: 2025-01-01 10:25:30 }步骤表记录每个步骤的执行状态{ step_id: step_7, task_id: task_20250101_001, step_desc: 调用物流接口获取最新轨迹, status: failed, depends_on: [step_6], retry_count: 1, input_snapshot: {\order_id\: \PO20250101\}, output_snapshot: null, error_info: api_rate_limit_exceeded, started_at: 2025-01-01 10:20:00, finished_at: null }工具调用账本表专门记录带副作用的调用{ call_id: toolcall_1042, task_id: task_20250101_001, step_id: step_7, tool_name: logistics_track, arguments: {\order_id\: \PO20250101\}, status: executed_unknown, idempotency_key: task_20250101_001_step_7_logistics_track, response_summary: null, created_at: 2025-01-01 10:20:05 }需要注意的关键字段是工具调用表里的idempotency_key它保证了即使在网络超时的情况下也能识别“这个调用我是不是已经发出过”后面讲副作用处理时再展开。3.2 保存流程每个关键节点都写一次“状态照片”检查点保存的代码逻辑我推荐写成一个装饰器或者执行器内部的回调函数而不是散落在业务代码里。伪代码如下。async def run_agent_step(task_state, step): # 1. 在模型调用前保存状态 checkpoint(task_state, phasebefore_model_call) # 2. 调用模型生成回复 response await call_model(task_state.messages) if not is_valid(response): # 模型输出无效从 before_model_call 检查点恢复 raise RecoverableCheckpointError(model output invalid) # 3. 如果模型要求调用工具则在调用前记录账本 if response.tool_calls: for tool_call in response.tool_calls: record_tool_call(task_state, tool_call) # 在工具调用发出前保存状态 checkpoint(task_state, phasebefore_tool_call) # 4. 执行工具调用 tool_results await execute_tool_calls(response.tool_calls) # 5. 把结果写回上下文并保存状态 task_state.messages.append(tool_result_message) checkpoint(task_state, phaseafter_tool_call) # 6. 更新步骤状态 mark_step_complete(task_state, step) checkpoint(task_state, phasestep_complete)这段代码看起来简单实际运行起来你会发现真正让恢复变得可靠的不是哪一次单独的保存而是“模型前、工具前、工具后、步骤后”这四个点的组合。3.3 恢复算法定位最后一个干净状态沿步骤续跑恢复算法不需要多高深核心就三条找到最近的干净检查点、确认哪些步骤已经完成、从失败步骤的下一个可执行步骤继续往下走。async def recover_task(task_id): # 1. 读取任务状态和检查点 task_state load_latest_checkpoint(task_id) # 2. 找出所有未完成且可执行的步骤 pending_steps get_pending_steps(task_state) # 3. 如果不依赖已完成步骤且不是重试陷阱就继续执行 for step in pending_steps: if step.status completed: continue if not dependencies_satisfied(task_state, step): continue task_state.current_step_id step.step_id step.retry_count 1 # 4. 如果该步骤已经产生过副作用先做幂等校验 if has_side_effect_record(step): side_effect check_side_effect_status(step) if side_effect confirmed_success: mark_step_complete(task_state, step) continue elif side_effect unknown: # 需要人工或自动确认 await confirm_or_cleanup(step) # 5. 重新执行当前步骤 await run_agent_step(task_state, step) # 6. 所有步骤完成后汇总输出 return task_state这里有个容易被忽略的细节恢复时的上下文消息列表不能简单地把所有历史消息全部塞回模型输入。因为 Agent 执行到一半失败时上下文里可能已经积累了很长一大段对话其中很多内容在规划决策中已经没有价值了。恢复时应该基于“最近 N 轮有效交互 任务初始目标 已完成步骤摘要”来重建上下文既节省 Token又让模型更快进入状态。4. 最难的坑工具调用的副作用怎么避免重复和漏处理如果说状态保存是断点继续的地基那工具调用的幂等性处理就是地基里最容易塌的那块砖。恢复做得再好只要工具被执行了两次业务上的账就乱了。4.1 为什么“执行失败”不等于“没有执行”最常见的场景是第三方 API 调用超时。你的 Agent 调用了支付接口请求发出去了但等待响应时连接断了代码这边认为调用失败。实际上服务端那边可能已经扣款成功、已经发了消息、已经改了订单状态。这种情况下如果你在恢复时直接重试这个工具调用就会导致重复扣款、重复发消息。更麻烦的是如果你不重试又可能错过真正还没执行的那个操作。这是分布式系统里经典的“at-least-once vs at-most-once”问题。对 Agent 来说大部分步骤我们都能接受“至少执行一次”但带财务性质、通知性质、写操作性质的工具调用必须做到“最多执行一次”或者“精确识别已执行”。4.2 幂等键与“先记账后执行”模式我的做法是规定所有可能产生副作用的工具调用在真正发出去之前先在工具调用账本里写入一条status pending的记录并生成一个幂等键。这个幂等键通常由任务 ID 步骤 ID 工具名 参数哈希组成。然后调用第三方接口时把幂等键作为请求头或者请求体字段一起传过去。凡是支持幂等键的服务端都会对相同幂等键的请求自动去重。async def execute_tool_with_idempotency(task_state, tool_call): key build_idempotency_key(task_state, tool_call) # 1. 先记账 record create_tool_call_record( task_idtask_state.task_id, step_idtool_call.step_id, tool_nametool_call.name, argumentstool_call.args, idempotency_keykey, statuspending ) # 2. 再执行 try: result await call_tool_api(tool_call, idempotency_keykey) mark_tool_call_success(record.id, result) return result except Exception as e: # 3. 失败时不能直接标失败要检查服务端状态 actual_status await probe_tool_execution_status(key) if actual_status success: # 实际已执行成功只是响应丢了返回缓存的成功结果 mark_tool_call_success(record.id, None) return retrieve_cached_result(key) else: mark_tool_call_failed(record.id, e) raise注意这里的probe_tool_execution_status它的作用是主动查询服务端确认这笔操作到底发生了没有。如果服务端提供查询接口这招最保险。如果查不了就只好把这种“未知状态”的调用交给下一节的人工确认流程。4.3 无法确认的工具调用标记为“未知”而不是“失败”很多第三方 API 根本不提供幂等键也不提供查询接口。这时我们要做的是诚实——把工具调用的状态标记为executed_unknown而不是直接标记为失败。executed_unknown状态在恢复算法里是个特殊分支。遇到这种分支我不自动重试也不直接跳过而是把这个异常情况抛给一个人工确认队列。操作人员看一遍调用参数和上下文手动确认这笔操作是否已生效然后决定是跳过还是补做还是回滚。这在自动化体系里看似笨拙但却是业务安全的关键一环。我宁可让人工确认一次模糊状态也不愿意让系统在无感知的情况下重复扣费。5. 不是所有断点都值得救恢复决策与人工介入机制做断点恢复做到后面你会遇到一个更深层的问题这个断点该不该恢复恢复的成本可能比重跑还高甚至恢复本身就是错的。5.1 用三个维度判断“是否值得从断点继续”我总结了一个简单的判断框架三个维度分别是失败类型、副作用风险、剩余工作量。失败类型决定了恢复策略的可行性。如果是限流、超时这类临时性故障恢复的把握很大。如果是模型上下文溢出、规划死循环这类逻辑性故障光恢复没用还得调整策略。如果是外部 API 返回结构彻底变化那就要先改代码再恢复。副作用风险决定了恢复是否需要额外确认。带资金、通知、写库性质的操作恢复前的确认成本很高纯读取类的工具调用随便重试。剩余工作量决定了恢复的性价比。如果已经执行了 80% 的步骤恢复是明智的。如果才跑到第二步就挂了直接整个任务重跑反而简单。我把这些规则做成了一张决策表每次恢复前自动过一遍。场景失败原因举例副作用风险建议动作模型调用限流429 或超时低重试当前步骤等待退避模型输出解析失败JSON 破损、字段缺失低截断重试或改用更宽松解析器工具调用超时第三方接口无响应高先查询状态真失败再重试上下文溢出context 超限中摘要历史后重试或切换规划策略规划死循环同一操作循环执行中中断并人工介入修改计划外部接口结构变更API schema 不匹配中人工介入升级适配层5.2 设置恢复上限别让断点续跑变成无限循环断点恢复最危险的情况是同一个步骤失败后反复恢复、反复执行形成一个看不见的循环。尤其当工具调用是幂等的、返回结果总是失败时这个循环会白白消耗大量 Token还会拖慢整个任务队列。我设置了两层上限。第一层是单步重试上限。同一步骤的连续失败次数达到上限后不再自动重试而是进入人工队列。第二层是任务级恢复上限。整个任务从断点恢复的总次数也设上限比如一个任务最多恢复 5 次超过之后强制进入人工处理。上层逻辑简单但极有效。我见过一个真实的线上事故某个数据处理 Agent 在调用日期解析工具时因为时区参数传错了每次恢复都得到一样的结果任务在几个小时内反复自动重试了一百多次。设置恢复上限之后这种问题最多浪费到第 5 次就会被人工发现。5.3 人工介入通道给恢复系统留一个“人肉出口”无论自动化做得多么完善总有一些断点是需要人来判断的。我把人工介入设计成恢复流程里的一等公民而不是最后兜底。具体做法是给每个“待人工确认”的任务生成一个结构化面板面板里包含目标描述、当前步骤、失败原因、最近几次工具调用的参数与结果、恢复建议选项重试/跳过/回滚/终止。操作者点一下就能选择后续动作。这里有个经验之谈人工介入面板的信息要少而精。当初我把大量日志全塞进面板操作者反而找不到重点。后来精简成“目标、断点位置、失败原因、推荐动作”四块信息处理效率高了很多。6. 生产环境里的隐藏细节上下文重建、反序列化与并发隔离前面几节已经把断点恢复的主体方案讲清楚了但真正投入生产后还会有三个细节问题每一个都能让你的恢复机制在关键时刻崩掉。6.1 上下文重建恢复时如何不把 Token 撑爆长任务的 Agent 执行到一半上下文里可能攒了几百条消息。恢复时如果把这些原封不动全塞回去有两个后果一是 Context Window 可能直接溢出二是模型注意力被大量历史噪音分散决策质量下降。我的做法是分层重建上下文核心层系统提示、用户原始目标、当前步骤描述、最近 5 轮关键交互。摘要层更早的历史消息压缩成一段结构化摘要包含已完成步骤、重要工具结果、关键决策。工具层最近一次工具调用原文确保模型能基于最新的观测结果继续推理。摘要的生成可以用模型来做也可以用规则抽取。规则抽取更可控模型摘要更自然我目前用的是“规则抽取 模型润色”的混合方式。6.2 反序列化的坑状态里别放模型实例和临时对象写检查点时状态对象里哪些字段会被序列化直接影响恢复的可靠性。我在早期犯过的错是把pandas.DataFrame、PIL.Image、requests.Session、不稳定的模型实例等对象直接放进了状态里。结果序列化时要么报错要么存了一个巨大的二进制块恢复时还得重新初始化。后来我定了一个规则状态里只允许放基本类型、JSON 可序列化的字典和列表。所有重对象一律在恢复后重建。比如数据库连接、HTTP 客户端、模型实例都由恢复函数重新创建。这条规则想起来容易执行时容易漏。建议在检查点保存函数里加一个校验序列化之前递归检查一遍发现不可序列化对象直接报错而不是等到恢复时才发现坏了。6.3 并发与文件锁多任务同时恢复时的隔离问题最后一个坑是并发恢复。当 Agent 框架部署成多副本多个任务同时崩溃、同时恢复时很容易出现两个恢复流程同时操作同一个任务的状态导致数据互相覆盖。我的解决方案是引入任务级锁。每个任务的恢复流程开始前先尝试获取分布式锁拿到锁的才能继续恢复拿不到锁的等待或者放弃。同时检查点事务要保证原子性读取和写入之间不能用非原子操作。实现锁的方式很多数据库唯一索引、Redis 锁、或者文件锁都可以。关键在于锁一定要在“读取检查点”之前获取否则你读到的可能正是另一个流程正在写入的中间状态。7. 我踩过几次坑之后的最终经验做完这套断点恢复机制最大的感悟是断点继续不是附加功能而是 Agent 系统的刚需。哪怕你现在的 Agent 任务很短、很稳定也建议从一开始就把状态持久化做上否则任务一旦变长你会被重跑成本和教育用户重新等待的时间拖住。几个实战建议供参考。第一保存时机宁可多不要少。模型调用前、工具调用前、工具调用后三步打点是底线多打几次不会错少打一次恢复时就可能乱。第二恢复时在系统提示词里明确告诉模型“这是一个从断点恢复的任务”。实测下来模型知道自己在续跑时会更多参考已完成步骤的信息减少重新规划的冲动。第三用故障注入测试恢复逻辑。人为制造模型超时、工具乱序返回、进程杀死的场景验证检查点和恢复链路是否真的可靠别等到线上出问题才后悔。这套方案上线之后我们的长任务成功率提升了一大截最有价值的地方还不是省 Token而是让运营和开发不再恐惧“长任务跑了一半失败”这种事故。要是你的 Agent 也在为同样的痛点头疼按这个思路落地一遍应该能少走不少弯路。