1. 从一次线上事故说起：为什么超时和重试不是终点

给 AI Agent 加超时和重试，这件事听起来像是工程化的入门操作。我最初也是这么想的——Agent 调用外部工具、访问模型接口、读写数据库，任何一个环节都可能因为网络抖动或服务端限流而失败，加个timeout参数、套个retry装饰器，问题不就解决了吗？

结果上线第三天，监控告警炸了。一个负责自动整理文档的 Agent，在某个任务上连续重试了 7 次，每次都"成功"返回，但最终产出的文档里出现了 7 份重复的摘要段落，而且数据库里多出了 7 条本该只写一次的记录。更离谱的是，Agent 的状态机卡在了"处理中"，既没有推进到下一步，也没有回滚，后续所有依赖这个状态的任务全部阻塞。

那一刻我才意识到：超时和重试解决的是"调用能不能返回"的问题，但真正决定系统是否可靠的，是"返回之后状态对不对"的问题。这两件事完全不在一个层面上。

这篇内容我想聊的就是这个层面的事。它适合已经给 Agent 加过基础容错、但被状态不一致折磨过的开发者，也适合正在设计 Agent 架构、想提前避开这些坑的人。核心关键词就几个：AI Agent、超时、重试、状态清理、幂等。我会把踩坑的完整链路、根因分析、以及最后落地的方案都摊开讲，不讲空泛的理论，只讲能直接抄的做法。

先说结论，省得你看到一半才发现方向不对：超时和重试是"入口防护"，状态清理和幂等是"出口保障"。只做前者不做后者，等于给一个漏水的桶加了个更快的进水口——进得越快，漏得越狠。

2. 超时与重试到底在防什么，又防不住什么

2.1 超时机制的真实作用边界

很多人对超时的理解是"防止程序卡死"，这个说法对，但太浅了。超时真正的作用是给一次不确定的调用划定一个确定的时间窗口，让调用方能够在"我不知道对方到底做没做"的情况下，强行拿回控制权。

这里有个关键点容易被忽略：超时触发时，你并不知道远端到底执行了没有。可能请求还没到，可能请求到了正在处理，也可能处理完了但响应在回来的路上丢了。这三种情况对调用方来说长得一模一样——都是"超时"，但对系统状态的影响天差地别。

我见过太多代码是这样写的：

try: result = call_agent_tool(payload, timeout=30) except TimeoutError: logger.warning("调用超时，准备重试") retry()

这段代码的问题在于，它把"超时"当成了一个明确的失败信号。但超时从来不是一个明确的失败信号，它是一个不确定信号。基于不确定信号做重试决策，就是在赌远端没执行成功。赌赢了没事，赌输了就是重复执行。

2.2 重试放大的是问题，不是可靠性

重试的逻辑更微妙。表面上看，重试提高了成功率——第一次失败，第二次可能就成功了。但重试同时也在放大每一次调用的副作用。

假设一个 Agent 工具调用的失败率是 10%，你重试 3 次，那么单次任务的成功率确实从 90% 提升到了 99.9%。但代价是：原本 10% 的失败调用里，有一部分其实是"执行成功但响应丢失"，重试会让这部分操作被执行两次甚至三次。

用一个具体的数字感受一下。假设 1000 次调用中：

那 20 次"响应丢失"的调用，就是重复执行的来源。如果这些调用是"写数据库""发消息""扣额度"这类有副作用的操作，重复执行就是灾难。

提示：重试次数不是越多越好。每增加一次重试，你都在扩大副作用重复执行的概率窗口。业界常见的做法是重试 2 到 3 次，配合指数退避，而不是无脑重试 10 次。

2.3 一个被忽视的事实：超时和重试是"无状态"的

超时和重试机制本身不携带任何状态信息。它不知道这次调用是第几次、之前有没有成功过、当前 Agent 处于哪个阶段。它只是一个机械的"失败就再来一次"的循环。

这就是问题的根源。Agent 是有状态的，但容错机制是无状态的。一个无状态的机制去保护一个有状态的系统，中间必然出现状态断层。这个断层，就是后面所有坑的温床。

3. 状态清理：那个被所有人低估的环节

3.1 状态到底指什么

在 Agent 场景里，"状态"这个词涵盖的范围比很多人想的要广。它至少包括这几层：

• Agent 自身的执行状态：当前处于哪个步骤、下一步该做什么、有没有中间结果。
• 外部资源的占用状态：比如已经申请的内存、已经打开的文件句柄、已经锁定的数据库行。
• 业务数据的写入状态：已经写了一半的记录、已经发出的消息、已经扣减的额度。
• 幂等标记状态：这次操作有没有被记录过、去重键是什么。

超时和重试发生时，这四层状态可能处于任意组合的中间态。而大多数人的代码只处理了第一层——把 Agent 状态重置一下，然后重试。剩下三层原封不动地留在那里，等着在某个时刻爆雷。

3.2 状态清理为什么这么难

难就难在清理的时机和清理的范围。

先说时机。你什么时候清理？超时的那一刻清理？那如果远端其实还在执行呢，你清理了本地状态，远端执行完回来发现状态没了，又是一堆错。等重试成功后再清理？那重试期间的状态就是脏的，其他并发任务可能读到脏状态。

再说范围。清理多少？只清理本次调用的中间状态，还是把整个 Agent 的状态都重置？清理少了，残留状态会污染后续；清理多了，可能把不该动的状态也清了，导致任务无法恢复。

我踩过的一个典型坑是这样的：Agent 在调用一个"生成报告"的工具时超时了，我在except里把 Agent 状态重置为"待处理"，然后重试。结果重试成功生成了报告，但第一次超时的调用其实在远端也执行完了，也生成了一份报告。两份报告都写进了同一个目录，文件名还一样，后写的覆盖了先写的，但数据库里记录了两条生成日志。用户看到的是"生成了一次"，后台日志显示"生成了两次"，对账的时候怎么都对不上。

3.3 清理不是删除，是"收敛到一致状态"

这里要纠正一个认知：状态清理不等于把状态删掉。清理的目标是让系统收敛到一个一致的状态，而不是回到"什么都没发生"。

这两者的区别很关键。回到"什么都没发生"在分布式环境下几乎不可能，因为远端的执行你控制不了。你能做的是：让本地状态和远端状态达成一致，或者至少让本地状态能够正确地反映"可能发生了两次"这个事实。

所以状态清理的正确姿势是：

1. 识别本次调用可能产生的所有副作用。
2. 为每个副作用设计一个"可检测、可补偿"的机制。
3. 在超时或重试时，先检测副作用是否已经发生，再决定是补偿还是继续。

这套逻辑听起来复杂，但落到代码上其实就是几个判断。后面我会给出具体的实现。

4. 幂等：让重试变得安全的底层机制

4.1 幂等的本质是"去重键"

幂等这个词被讲烂了，但很多人对它的理解停留在"同一个请求执行多次结果一样"。这个定义没错，但它没告诉你怎么做到。

做到幂等的核心只有一个：给每一次逻辑操作分配一个全局唯一的标识，然后在执行前检查这个标识有没有被处理过。这个标识就是去重键，也叫幂等键。

在 Agent 场景里，幂等键的生成有几个层次：

• 任务级幂等键：整个 Agent 任务一个 ID，保证同一个任务不会被重复启动。
• 步骤级幂等键：任务 ID 加上步骤序号，保证同一步骤不会被重复执行。
• 调用级幂等键：步骤 ID 加上调用序号，保证同一次工具调用不会被重复触发。

层次越细，保护越精确，但管理成本也越高。我的经验是：至少做到步骤级，关键的有副作用的调用做到调用级。

4.2 幂等键放在哪里

幂等键的存储位置决定了它的可靠性。常见的选择有三种：

我现在的默认选择是数据库唯一索引 + 缓存加速。数据库的唯一索引是最后一道防线，保证即使缓存失效也不会重复写入；缓存用来扛住高频的重复检测，减少数据库压力。

具体做法是：在业务表上加一个idempotency_key字段，建唯一索引。执行前先INSERT一条记录，如果唯一索引冲突，说明已经执行过，直接返回上次的结果。

CREATE TABLE agent_operations ( id BIGINT PRIMARY KEY AUTO_INCREMENT, idempotency_key VARCHAR(128) NOT NULL, status VARCHAR(32) NOT NULL, result TEXT, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, UNIQUE KEY uk_idempotency (idempotency_key) );

def execute_with_idempotency(key, operation): try: # 尝试占位，唯一索引保证只有一个能成功 db.insert("agent_operations", {"idempotency_key": key, "status": "running"}) except DuplicateKeyError: # 已经执行过，查询状态 record = db.query_one("agent_operations", {"idempotency_key": key}) if record["status"] == "done": return record["result"] elif record["status"] == "running": # 正在执行中，等待或返回进行中 raise OperationInProgress(key) result = operation() db.update("agent_operations", {"idempotency_key": key}, {"status": "done", "result": result}) return result

这段代码的关键在于那个INSERT。它利用了数据库唯一索引的原子性，把"检查是否重复"和"标记为执行中"合并成了一个原子操作。这是避免并发重复执行的标准做法。

4.3 幂等和状态清理的配合

幂等解决的是"重复执行"的问题，状态清理解决的是"残留状态"的问题。两者配合起来，才能形成完整的闭环。

配合的逻辑是这样的：

1. 调用前，用幂等键占位。
2. 调用超时，不立即重试，而是先查询幂等键的状态。
3. 如果状态是"执行中"，说明可能还在跑，等待或查询远端。
4. 如果状态是"已完成"，直接取结果，不重试。
5. 如果状态是"失败"或不存在，才执行清理并重试。

这套流程把"不确定的超时"转化成了"可查询的状态"，重试决策从"赌"变成了"查"。这是整个方案的核心转变。

5. 一套可落地的 Agent 容错方案

5.1 整体架构

我把这套方案拆成四层，从外到内依次是：

• 超时层：给每次调用设定时间窗口，超时即中断等待。
• 幂等层：用幂等键保证同一操作只执行一次。
• 状态层：记录每次操作的状态，支持查询和恢复。
• 清理层：在重试前检测并补偿残留副作用。

这四层不是独立的，而是层层递进。超时触发后进入幂等检查，幂等检查依赖状态记录，状态记录指导清理动作。

5.2 关键代码结构

class AgentExecutor: def __init__(self, db, cache): self.db = db self.cache = cache def execute_step(self, task_id, step_no, operation, timeout=30): key = f"{task_id}:{step_no}" # 第一层：幂等检查 existing = self._check_idempotency(key) if existing and existing["status"] == "done": return existing["result"] # 第二层：占位 if not existing: self._reserve(key) # 第三层：带超时执行 try: result = self._run_with_timeout(operation, timeout) self._mark_done(key, result) return result except TimeoutError: # 第四层：超时后不立即重试，先查状态 return self._handle_timeout(key, operation, timeout) def _handle_timeout(self, key, operation, timeout): # 查询远端实际状态 remote_status = self._query_remote_status(key) if remote_status == "completed": # 远端已完成，取结果 result = self._fetch_remote_result(key) self._mark_done(key, result) return result elif remote_status == "running": # 远端还在跑，等待 return self._wait_and_fetch(key, timeout) else: # 远端确实没执行，清理后重试 self._cleanup(key) return self.execute_step(*self._parse_key(key), operation, timeout)

这段代码里最关键的是_handle_timeout方法。它没有在超时后直接重试，而是先查询远端状态，根据状态决定下一步。这就是"从赌到查"的转变。

5.3 状态清理的具体实现

清理动作要根据副作用的类型来设计。我总结了几种常见的副作用和对应的清理策略：

清理的核心原则是：每个副作用都要有对应的补偿动作，补偿动作本身也要幂等。否则清理过程又会产生新的不一致。

5.4 超时时间的设定

超时时间设多少，这个问题没有标准答案，但有几个参考维度：

• P99 响应时间：超时时间至少是 P99 的 1.5 到 2 倍，避免正常慢请求被误杀。
• 业务容忍度：用户能等多久，超时就不能超过这个时间。
• 重试预算：如果计划重试 3 次，单次超时乘以 4 不能超过总预算。

我一般会先设一个保守值，然后根据监控数据调整。比如模型调用先设 60 秒，观察一周后如果 P99 是 20 秒，就调到 40 秒。超时时间不是拍脑袋定的，是看数据调的。

6. 那些只有踩过才知道的细节

6.1 重试的退避策略比次数更重要

很多人重试就是for i in range(3): try: ...，中间不加延迟。这在服务端限流的场景下是灾难——你越急着重试，越容易被限流，越容易失败。

正确的做法是指数退避加随机抖动：

import random import time def retry_with_backoff(func, max_retries=3, base_delay=1): for attempt in range(max_retries): try: return func() except RetryableError: if attempt == max_retries - 1: raise delay = base_delay * (2 ** attempt) + random.uniform(0, 1) time.sleep(delay)

那个random.uniform(0, 1)是抖动，作用是打散多个客户端的重试时间，避免它们同时重试造成新的峰值。这个细节很小，但在高并发下效果显著。

6.2 不是所有错误都该重试

重试的前提是错误是瞬时的、可恢复的。以下几类错误重试没有意义，反而浪费资源：

• 参数错误（400 类）：重试多少次都是错的。
• 权限错误（401、403）：重试不会让权限变对。
• 资源不存在（404）：除非你确定资源会很快创建。
• 业务逻辑错误：比如余额不足，重试也不会变够。

我的做法是给错误分类，只对"网络超时""服务端 5xx""限流 429"这几类做重试，其他直接失败并上报。

6.3 状态清理的时机要精确到"重试之前"

我见过有人在超时的except里直接清理，然后重试。这是错的。因为超时的那一刻，远端可能还在执行，你清理了本地状态，远端执行完回来发现状态没了，又是一堆错。

正确的时机是：先查询远端状态，确认远端没有在执行或已经执行完毕后，再清理。清理的前提是"确定"，不是"猜测"。

6.4 日志要能还原整个决策链路

状态清理和重试的调试难度很高，因为涉及多次调用和多个状态。如果日志不完整，出了问题根本查不出来。

我的日志会记录这几个关键点：

• 每次调用的幂等键、开始时间、结束时间、结果状态。
• 每次超时时的远端状态查询结果。
• 每次清理动作的类型、影响范围、执行结果。
• 每次重试的触发原因和重试次数。

这些日志看起来啰嗦，但出事的时候能救命。我曾经靠一条"远端状态查询返回 running"的日志，定位到一个远端服务卡死的问题，否则会一直以为是本地重试逻辑的 bug。

6.5 并发场景下的状态竞争

如果同一个 Agent 任务可能被并发触发（比如用户重复点击、定时任务重叠），状态清理会变得非常复杂。两个执行流同时清理同一个状态，可能互相干扰。

解决办法是在状态记录上加锁，或者用乐观锁的版本号机制。我倾向于用数据库的行锁：

SELECT * FROM agent_operations WHERE idempotency_key = ? FOR UPDATE;

这行 SQL 会锁住对应的记录，保证同一时刻只有一个执行流能操作它。配合幂等键的唯一索引，基本能杜绝并发重复执行。

7. 从"能跑"到"可靠"的认知转变

回头看这次踩坑，最大的收获不是某个具体的技术方案，而是认知上的转变。

第一个转变：容错不是加个 try-catch 就完事。容错是一个系统工程，涉及超时、重试、幂等、状态管理、清理补偿多个环节，缺一不可。只做其中一两个，系统看起来能跑，但一遇到真实故障就原形毕露。

第二个转变：可靠性来自"可查询"，不是"可重试"。重试是盲目的，查询是确定的。把不确定的操作转化成可查询的状态，是提升可靠性的关键。这也是为什么幂等键和状态记录这么重要——它们让"重试"这个动作有了依据。

第三个转变：状态清理不是收尾工作，是核心设计。我最初把状态清理当成"出错了才做的事"，后来发现它应该是设计阶段就要考虑的事。每个有副作用的操作，在设计时就要想好"如果它执行了两次怎么办""如果它执行了一半怎么办"。这些问题想清楚了，代码自然就健壮了。

现在我的 Agent 项目里，每个工具调用都必须回答三个问题：幂等键是什么、状态记在哪里、清理动作是什么。回答不上来的，不允许上线。这个规矩看起来很严，但它帮我挡掉了后面无数个深夜告警。

如果你正在给 Agent 加超时和重试，我的建议是：先把状态清理和幂等设计好，再加超时和重试。顺序反了，你会在坑里待很久。顺序对了，超时和重试就是锦上添花，而不是雪上加霜。