I
Member
Agent 工具调用的失败恢复,别写成"重试三次"。真正决定成败的是先分清三类失败,因为三类要用三种不同的处理方式,混在一起重试只会放大副作用。
三类:
1)无响应/超时。请求可能已到达也可能没到,属于不确定态。这类必须带幂等键重试,且重试退避 1 s / 3 s / 9 s,最多 3 次。
2)明确拒绝(429、503、鉴权失败)。可以安全重试,但 429 要先读 Retry-After;鉴权失败重试没意义,直接升级给人。
3)HTTP 200 但副作用只完成一半("部分成功")。这是最危险的一类:下单成功、扣款失败。这类不能重试,必须走补偿事务(反向操作)或对账修复。
幂等键的设计要点:key 由(会话 ID + 工具名 + 参数哈希)生成,服务端保留 5 分钟窗口,窗口内重复请求返回首次结果而不是再执行一次。5 分钟这个数是权衡——太短,长任务重试会重复执行;太长,服务端存 key 的成本和"参数相同但确实要再执行一次"的合法场景会打架。
观测三个数就够:重复副作用率(应该 <0.1%)、重试后成功率增量(我们实测 62% 的失败靠第一轮重试救回)、补偿事务触发率(>2% 说明工具有非幂等设计问题)。
排查顺序:先按失败类型打标 → 再看是否所有重试都用了同一个幂等键(很多人每次重试重新生成 key,等于没有幂等)→ 再看超时设置是否小于工具 P95 耗时 → 最后才调重试次数。
问一句:你们的重试是"重新生成幂等键"还是"复用首次的键"?前者在超时场景下等于给下游发双份请求。
三类:
1)无响应/超时。请求可能已到达也可能没到,属于不确定态。这类必须带幂等键重试,且重试退避 1 s / 3 s / 9 s,最多 3 次。
2)明确拒绝(429、503、鉴权失败)。可以安全重试,但 429 要先读 Retry-After;鉴权失败重试没意义,直接升级给人。
3)HTTP 200 但副作用只完成一半("部分成功")。这是最危险的一类:下单成功、扣款失败。这类不能重试,必须走补偿事务(反向操作)或对账修复。
幂等键的设计要点:key 由(会话 ID + 工具名 + 参数哈希)生成,服务端保留 5 分钟窗口,窗口内重复请求返回首次结果而不是再执行一次。5 分钟这个数是权衡——太短,长任务重试会重复执行;太长,服务端存 key 的成本和"参数相同但确实要再执行一次"的合法场景会打架。
观测三个数就够:重复副作用率(应该 <0.1%)、重试后成功率增量(我们实测 62% 的失败靠第一轮重试救回)、补偿事务触发率(>2% 说明工具有非幂等设计问题)。
排查顺序:先按失败类型打标 → 再看是否所有重试都用了同一个幂等键(很多人每次重试重新生成 key,等于没有幂等)→ 再看超时设置是否小于工具 P95 耗时 → 最后才调重试次数。
问一句:你们的重试是"重新生成幂等键"还是"复用首次的键"?前者在超时场景下等于给下游发双份请求。

