1. 一个执行失败就重试为什么说这是初级做法Multi-Agent 系统跑起来之后最让人头疼的不是模型能力不够而是某个 Agent 执行到一半突然挂了。日志里一行红字任务卡死整条链路停摆。很多人的第一反应是加个try-catch然后retry三次觉得这就叫容错了。我刚开始搭 Agent 编排的时候也是这么干的直到线上跑了一个多步骤的调研任务第三个 Agent 在调用外部接口时超时重试了三次全部失败前面两个 Agent 已经消耗掉的 token、已经写入的中间结果、已经产生的副作用全部变成了脏数据。那一刻我才意识到重试只是容错的最低配真正难的是让失败可恢复、可回滚、可续跑。这篇文章想聊的就是这件事当一个 Multi-Agent 系统里的某个执行环节失败时除了无脑重试一个合格的 Agent 开发者还应该掌握哪些手段。核心会围绕四个关键词展开——Checkpoint检查点、幂等Idempotency、状态机编排、失败分类。这些词你可能在分布式系统里见过但搬到 Agent 场景下它们的含义和落地方式有很不一样的地方。因为 Agent 的执行单元不是纯函数它带着上下文、带着记忆、带着对外部世界的副作用这让恢复这件事变得比传统服务复杂得多。适合谁看如果你正在用 LangGraph、AutoGen、CrewAI 或者自己手搓 Agent 编排框架已经跑通了 demo 但一上真实任务就各种翻车那这篇就是写给你的。如果你还停留在单 Agent 调 API的阶段也可以先收藏等你的系统里出现第二个 Agent 的时候这些问题会一个不落地找上门。下面我会从设计思路讲到具体实现把每个决策背后的为什么说清楚也会给出可以直接抄的参数和代码骨架。2. Multi-Agent 失败的本质不是 bug是分布式状态问题2.1 为什么 Agent 失败比普通服务失败更难处理普通微服务挂了重启一下请求重放只要接口幂等世界就恢复了。Agent 不行。一个 Agent 的一次执行往往包含了好几层状态对话历史context、工具调用产生的中间结果、对外部系统的写入操作、以及它自己维护的记忆。这四层状态里任何一层在失败时处于半完成状态都会让简单的重试变成灾难。举个我踩过的真实例子。一个负责抓取网页并总结的 Agent流程是调用搜索工具拿到 URL 列表 → 逐个抓取正文 → 调用 LLM 总结 → 把总结写入向量库。某次抓取到第 5 个 URL 时网络抖动失败了。如果直接重试整个 Agent前面 4 个 URL 的总结会被重复写入向量库产生重复条目如果只重试抓取那一步但 Agent 的 context 里已经记录了已完成 4 个状态就对不上了。你看问题根本不在要不要重试而在重试的粒度是什么、重试时状态从哪恢复。2.2 把 Agent 执行看成一次可持久化的事务我的做法是把每个 Agent 的一次执行当成一个带检查点的事务来设计。事务的边界不是整个任务而是一个不可分割的副作用单元。比如写入向量库是一个事务单元调用一次 LLM是一个事务单元但抓取 10 个网页不是——它应该被拆成 10 个可独立提交的小单元。这样设计之后失败发生时我们面对的不再是整个 Agent 挂了而是第 5 个单元没提交成功。恢复的时候只需要从第 5 个单元的检查点重新开始前面 4 个已经提交的结果原封不动。这就是 Checkpoint 机制的核心价值把长流程切成可恢复的短片段让失败的影响范围可控。2.3 失败分类先搞清楚是哪种失败再决定怎么处理无脑重试最大的问题是不区分失败类型。我把 Agent 执行中的失败分成四类处理策略完全不同失败类型典型场景是否可重试推荐策略瞬时故障网络抖动、限流 429、超时是指数退避重试2-3 次逻辑错误参数错误、工具返回格式不符否修正后从检查点续跑资源耗尽token 超限、上下文溢出部分压缩上下文或降级模型外部依赖失败第三方 API 宕机、权限失效视情况熔断 降级 人工介入我见过太多系统把四类失败一视同仁地重试结果逻辑错误重试一百次还是错白白烧钱。正确的顺序是先分类再决定重试、续跑还是熔断。这个判断逻辑本身应该写进编排层而不是散落在每个 Agent 的代码里。3. Checkpoint 机制让 Agent 从断点而不是起点恢复3.1 Checkpoint 到底存什么很多人以为 Checkpoint 就是存个执行到第几步了这远远不够。一个能真正支撑恢复的检查点至少要包含四样东西执行位置哪个节点、哪一步、上下文快照当时的 messages 和变量、已产生的副作用记录哪些外部写入已完成、以及幂等键用于判断恢复时是否重复执行。我通常用一个 JSON 结构来存落到 Redis 或者数据库里checkpoint { task_id: task_20240115_001, agent_id: summarizer, step_index: 5, node_name: fetch_and_summarize, context_snapshot: { messages: [...], # 截断后的对话历史 variables: {...}, # 关键中间变量 }, side_effects: [ {type: vector_write, key: doc_001, status: committed}, {type: vector_write, key: doc_002, status: committed}, ], idempotency_key: task_20240115_001_step5, created_at: 1705300000, }这里有个关键取舍context_snapshot 要不要存全量对话历史。存全量最安全但体积大、恢复慢只存摘要省空间但可能丢失细节导致恢复后行为不一致。我的经验是对于步骤数少于 20 的流程存全量超过 20 步的存最近 5 轮完整对话 更早的摘要。这个阈值不是拍脑袋是因为大多数 Agent 的有效决策只依赖最近几轮上下文更早的信息用摘要足够。3.2 检查点的粒度怎么定粒度太粗恢复时重复劳动多粒度太细写检查点的开销又太大。我的一般原则是在有副作用和跨 Agent 边界这两个位置必须打检查点其他位置按需。具体来说下面这几个位置是必打的调用外部工具之前因为工具调用可能产生副作用也可能失败打点后可以判断这个工具到底执行了没有。写入外部存储之后确认副作用已提交恢复时跳过。Agent 之间传递控制权时A Agent 把任务交给 B Agent这个交接点必须持久化否则 B 挂了 A 不知道。LLM 调用返回后LLM 调用贵且慢结果必须存下来恢复时直接复用不要重新调。至于纯计算、纯格式转换这类无副作用的步骤可以不打点恢复时重算一遍成本很低。3.3 恢复流程从检查点续跑的正确姿势恢复不是简单地从第 5 步继续。正确的流程是这样的加载最近的检查点拿到 step_index 和 context_snapshot。校验副作用状态遍历 side_effects确认哪些已提交、哪些未提交。对于未提交的需要判断是根本没执行还是执行了但没记录——这就是幂等键发挥作用的地方。重建上下文把 context_snapshot 反序列化恢复到 Agent 的记忆里。从下一个未完成步骤开始执行而不是从检查点那一步重跑。注意第 4 步是最容易出错的。很多人恢复时从检查点那一步重跑结果那一步的副作用被执行了两次。正确做法是检查点记录的是这一步已完成恢复时从 step_index 1 开始。我实测下来这套机制能把一个 15 步流程的失败恢复时间从重跑整个流程的 3 分钟压缩到续跑剩余步骤的 20 秒而且副作用零重复。这个收益在长流程、高成本任务上非常明显。4. 幂等设计让重复执行不产生重复副作用4.1 为什么 Agent 场景的幂等比普通接口更难普通接口的幂等通常靠一个请求 ID 去重就够了。Agent 场景复杂得多因为同一个逻辑操作可能通过不同的路径触发。比如把总结写入向量库这个操作可能来自正常流程也可能来自恢复流程还可能来自人工手动触发。如果只用请求 ID 去重这三条路径的 ID 不一样去重就失效了。我的解法是引入业务幂等键而不是请求幂等键。业务幂等键由任务 ID 逻辑操作标识组成跟触发路径无关。比如task_001_summarize_doc_005不管从哪条路径来只要这个键已经处理过就直接跳过。4.2 幂等键的生成规则幂等键的生成要满足两个条件确定性同样的逻辑操作永远生成同样的键和唯一性不同的逻辑操作生成不同的键。我常用的规则是idempotency_key hash(task_id operation_type operation_target)其中 operation_target 是操作的对象标识比如文档 ID、用户 ID。这样即使同一个任务里对同一个文档操作两次键也一样第二次会被识别为重复。有个坑要注意不要把时间戳、随机数放进幂等键。我见过有人用task_id timestamp做键结果每次重试时间戳都变幂等完全失效。幂等键必须是纯确定性的。4.3 幂等性检查用 DB 还是 Redis这是热词里被问得最多的问题之一。我的答案是看你的副作用落在哪里以及你对一致性的要求。维度Redis数据库写入速度极快内存较慢磁盘持久性可能丢取决于配置强持久原子性SETNX 天然原子需要唯一索引或事务适用场景短周期、可容忍偶发重复长周期、强一致要求过期策略可设 TTL 自动清理需手动清理我的实际选择是两者结合用 Redis 做第一层快速去重SETNX TTL用数据库的唯一索引做第二层兜底。因为 Redis 可能因为重启丢数据如果只靠它极端情况下会重复执行数据库唯一索引虽然慢一点但能保证最终不重复。两层配合既快又稳。具体实现上Redis 那层用SET key value NX EX 86400数据库那层在副作用表上建UNIQUE(idempotency_key)索引。执行前先查 Redis命中就跳过未命中则尝试写数据库如果唯一索引冲突说明是重复也跳过。4.4 副作用的幂等改造有些副作用天然不幂等比如给账户余额加 10 元。这种操作必须改造成幂等形式。常见手法有三种状态覆盖代替增量把加 10 元改成设置余额为 X 元其中 X 是计算好的目标值。这样重复执行结果一样。操作日志 去重记录每次操作的幂等键执行前先查日志。版本号控制给资源加版本号更新时带上版本号版本不匹配就拒绝。在 Agent 场景里我推荐第一种因为它最简单不需要额外的存储。但前提是你能算出目标状态而不是只知道增量。5. 编排层设计把容错逻辑从 Agent 里抽出来5.1 为什么容错不该写在 Agent 内部我早期犯的错是把重试、检查点逻辑写在每个 Agent 的代码里。结果是每个 Agent 都要重复实现一遍逻辑还不一致改一个策略要改十几个地方测试起来极其痛苦。后来我把这些逻辑全部上移到编排层Agent 只负责干活编排层负责什么时候干、失败了怎么办。这个分层的价值在于关注点分离。Agent 开发者只需要关心业务逻辑容错策略由编排层统一管理。而且编排层可以做成配置驱动不同任务用不同的重试策略、不同的检查点粒度不用改代码。5.2 用状态机描述 Agent 流程编排层的核心是一个状态机。每个 Agent 的执行被建模成状态转移失败被建模成转移失败恢复被建模成从某个状态重新进入。用状态机的好处是所有可能的失败路径都是显式的不会出现没想到这种情况的意外。一个简化的状态机定义大概长这样from enum import Enum class State(Enum): PENDING pending RUNNING running CHECKPOINTED checkpointed FAILED failed RECOVERING recovering COMPLETED completed transitions { State.PENDING: [State.RUNNING], State.RUNNING: [State.CHECKPOINTED, State.FAILED, State.COMPLETED], State.CHECKPOINTED: [State.RUNNING, State.FAILED], State.FAILED: [State.RECOVERING], State.RECOVERING: [State.RUNNING, State.FAILED], State.COMPLETED: [], }每个转移都对应一个动作失败时根据失败类型决定走哪条边。这套东西用 LangGraph 的StateGraph或者自己写都不难关键是把状态和转移显式化。5.3 重试策略的配置化重试不是重试 3 次这么简单。我通常配置这几个参数最大重试次数瞬时故障 3 次逻辑错误 0 次直接进恢复流程。退避策略指数退避基数 1 秒倍数 2加随机抖动避免惊群。重试超时总重试时间不超过 30 秒超过就放弃转人工。重试条件只对特定异常类型重试其他直接抛出。这些参数放在配置文件里不同任务可以覆盖。比如一个实时性要求高的任务重试次数降到 1 次快速失败一个离线批处理任务重试次数可以到 5 次容忍更长的恢复时间。提示退避策略里的随机抖动jitter非常重要。多个 Agent 同时失败时如果退避时间一样会在同一时刻一起重试把下游打垮。加个 ±20% 的随机抖动能有效分散压力。6. 实操从零搭一个带检查点和幂等的 Agent 编排6.1 整体架构我搭的这套东西分四层Agent 层干活、编排层调度和容错、存储层检查点和幂等记录、监控层观测和告警。下面重点讲编排层和存储层的实现因为这是容错的核心。存储层用 Redis 存检查点快用 PostgreSQL 存幂等记录和副作用日志稳。编排层用一个状态机驱动每个 Agent 执行前先查检查点执行后写检查点。6.2 检查点的读写实现写检查点的时机是每个有副作用的步骤完成后。实现上用一个装饰器包住 Agent 的执行方法import json import redis r redis.Redis(hostlocalhost, port6379, db0) def with_checkpoint(step_name): def decorator(func): def wrapper(task_id, context, *args, **kwargs): cp_key fcheckpoint:{task_id}:{step_name} # 先查是否已有检查点 existing r.get(cp_key) if existing: cp json.loads(existing) if cp[status] committed: return cp[result] # 已完成直接返回 # 执行 result func(task_id, context, *args, **kwargs) # 写检查点 cp { step_name: step_name, status: committed, result: result, context_snapshot: context.snapshot(), created_at: int(time.time()), } r.set(cp_key, json.dumps(cp), ex86400) return result return wrapper return decorator这个装饰器的关键点是执行前先查检查点如果已完成就直接返回缓存结果不重复执行。这就是幂等和检查点的结合点。6.3 幂等写入的实现对于写向量库这类副作用用幂等键去重def idempotent_write(task_id, operation, target, data): key f{task_id}:{operation}:{target} # 第一层Redis 快速去重 if not r.set(fidem:{key}, 1, nxTrue, ex86400): return duplicate_skipped # 第二层数据库唯一索引兜底 try: db.execute( INSERT INTO side_effects (idempotency_key, data) VALUES (%s, %s), (key, json.dumps(data)) ) except UniqueViolation: return duplicate_skipped # 真正执行副作用 vector_store.upsert(target, data) return committed注意这里的顺序先去重再执行副作用。如果先去重失败Redis 挂了还有数据库兜底如果数据库也挂了那说明整个存储层有问题应该直接失败而不是继续执行。6.4 恢复流程的完整实现恢复的入口是一个函数接收 task_id从最近的检查点续跑def recover_task(task_id): # 找到最新的检查点 cp_keys r.keys(fcheckpoint:{task_id}:*) if not cp_keys: return start_fresh(task_id) # 按时间排序取最新的 checkpoints [json.loads(r.get(k)) for k in cp_keys] latest max(checkpoints, keylambda c: c[created_at]) # 重建上下文 context Context.from_snapshot(latest[context_snapshot]) # 从下一个步骤开始 next_step get_next_step(latest[step_name]) return run_from_step(task_id, next_step, context)这里有个细节怎么知道下一个步骤是哪个。我的做法是在流程定义里维护一个步骤顺序表每个步骤知道自己的前驱和后继。这样从任意检查点都能找到下一步。6.5 监控和告警容错机制本身也需要被监控。我关注这几个指标检查点写入成功率低于 99% 说明存储层有问题。恢复次数某个任务频繁恢复说明流程设计有问题。幂等命中率命中率过高说明重复执行太多需要排查。平均恢复时间这个指标直接反映容错机制的效果。这些指标用 Prometheus 采集Grafana 展示。告警阈值我一般设成恢复次数超过 3 次/小时就告警因为正常任务不应该频繁失败。7. 常见问题与排查技巧实录7.1 恢复后行为不一致怎么办这是最常见的问题。恢复后 Agent 的行为跟第一次执行不一样导致结果不可预测。原因通常是上下文重建不完整。排查思路对比恢复前后的 context_snapshot看哪些字段丢了。常见的是 messages 被截断了、变量没存全、或者工具调用的中间结果没记录。我的解法是在检查点里存决策依据而不只是决策结果。比如 Agent 决定调用某个工具检查点里要记录为什么调这个工具当时的推理而不只是调了哪个工具。这样恢复后 Agent 能理解当时的意图行为更一致。7.2 幂等键冲突导致正常操作被跳过有时候两个不同的逻辑操作生成了相同的幂等键导致第二个被误判为重复。这通常是键生成规则太粗糙。排查方法把冲突的两个操作的键打出来对比看是哪部分重复了。修复就是细化键的组成比如加上操作对象的更细粒度标识。7.3 检查点写入成为性能瓶颈如果每个步骤都同步写检查点高频任务下 Redis 会成为瓶颈。优化手段批量写 异步写。把多个步骤的检查点攒一批一次性写入或者用异步队列写检查点不阻塞主流程。但要注意异步写有丢失风险对于关键步骤还是要同步写。7.4 常见问题速查表问题现象可能原因排查方向解决方案恢复后重复执行副作用幂等键失效或未检查查幂等记录表修复键生成规则加数据库兜底恢复后上下文丢失快照不完整对比快照字段补全快照内容检查点写入慢同步写、单点看 Redis 延迟批量写、异步写、加缓存重试风暴无退避或退避无抖动看重试时间分布加指数退避和随机抖动恢复后卡在同一处检查点未更新看检查点时间戳确认写入逻辑加写入校验7.5 几个我踩过的坑第一个坑检查点存了但没校验。有次 Redis 返回了损坏的 JSON恢复时直接崩了。后来我加了校验反序列化失败就降级到上一个检查点。第二个坑幂等键用了随机数。前面提过这里再强调一遍幂等键必须确定性生成任何随机成分都会让它失效。第三个坑恢复流程没有超时。有次恢复时又失败了然后触发恢复又失败无限循环。后来加了恢复次数上限超过 3 次就转人工。第四个坑检查点 TTL 设太短。设了 1 小时结果一个长任务跑了 2 小时中间检查点过期了恢复时找不到。现在我的 TTL 至少是任务预期时长的 3 倍。8. 进阶让容错机制自己进化8.1 基于失败历史的策略自适应固定的重试策略不够聪明。我后来加了一层记录每个步骤的历史失败率和失败类型动态调整重试策略。比如某个步骤历史上 90% 的失败是瞬时故障那就多给几次重试如果 80% 是逻辑错误那就直接进恢复流程别浪费时间重试。这个自适应的实现不复杂就是维护一个统计表每次失败更新计数策略选择时查表。但效果很明显能省下大量无效重试。8.2 检查点的智能压缩长任务的检查点会越积越多存储成本上升。我的做法是定期合并检查点把连续的、无副作用的步骤检查点合并成一个只保留有副作用的关键检查点。这样既省空间恢复时也不影响正确性。8.3 跨 Agent 的分布式检查点当多个 Agent 分布在不同机器上时检查点需要跨节点共享。这时候 Redis 单点就不够了要用 Redis Cluster 或者 etcd。一致性用 Raft 保证写入用 quorum 确认。这块复杂度上来了但如果你的 Agent 规模到了几十个这是必须面对的。我在实际项目里的体会是容错机制不是一次设计到位的而是随着失败案例的积累不断演进的。每遇到一次新的失败模式就补一条策略。半年下来这套机制覆盖了绝大多数场景线上任务的自动恢复率从最初的 40% 提到了 95% 以上。剩下 5% 需要人工介入的基本都是外部依赖彻底不可用的情况这种本来也不该指望自动恢复。最后分享一个小技巧给每个检查点加一个恢复提示字段记录如果从这里恢复应该注意什么。比如注意此步骤后向量库可能有不一致恢复时先校验。这个字段在人工排查时特别有用能省下大量翻日志的时间。