干过 Agent 工程的朋友应该都有这种经验单机脚本跑得好好的一放到线上、接上模型调用、加上并发任务问题就一个一个往外冒。其中最典型的就是超时和重试这两件事。最初我接手一个 AI Agent 项目的时候代码里写满了各种time.sleep()和.wait(),几乎每一条外部依赖的调用都是同步的。模型响应慢一点整个流程就卡死API 断一下任务直接失败收场。于是我按照传统后端服务的习惯给 Agent 的所有外部调用统一加了超时控制再补上重试机制。改完之后第一轮测试确实顺了不少任务失败率肉眼可见地降了下来。可当我真正把带着超时和重试的 Agent 放到线上压了一轮才发现问题远没有结束。加超时和重试只是治标真正的坑在于Agent 是有状态的而那些状态在我重试之前根本没有被清理。这篇文章不打算讲那种高大上的架构理论就围绕这个“加超时和重试”的实战过程说说我踩过的坑、排查过的诡异现象以及最后总结出来的状态清理方案。读完之后你至少能避开我这一个月里反复折腾才绕开的问题。1. 为什么超时和重试对 Agent 来说不是“加个参数”那么简单1.1 单体服务那套超时重试套路搬到 Agent 上为何失灵传统后端接口的超时重试核心是请求发出去了等了一段时间没响应直接重试。这套逻辑在无状态服务上几乎是完美的因为每个请求都是独立的重试无非是再执行一遍同样的操作。但 Agent 不一样。Agent 的每一次“请求”通常不是一个单一接口调用而是一连串的“推理-行动-观察”循环。它可能先去查一个数据库然后根据结果决定调用哪个模型再用模型输出调用某个工具最后把工具结果拼回去再次让模型判断。整个链路里任何一步都可能超时而“超时”发生时Agent 的中间产物——比如已经写了一半的临时文件、已经发给下游系统的半成品请求、已经调用过的工具返回值——并不会自动消失。如果你只是把每一步的timeout从 30 秒改成 60 秒再把失败后的retry加上表面上看请求是成功了但底层状态早就乱成了一锅粥。1.2 Agent 的运行模型有状态的多步工作流我习惯把 Agent 拆成三层来看第一层是Session 层也就是一次用户请求从进入到完成的全过程。这里保存了对话历史、上下文窗口、中间变量。第二层是Step 层是 Agent 内部的一次工具调用或一次模型推理。这是超时和重试最容易发生的地方。第三层是Side-effect 层是指 Agent 调用外部系统时留下的实际影响比如发送了邮件、创建了订单、写入了数据库。平时我们看到的教程和 Demo基本都在强调第一层的语义理解和第二层的模型调用但真正让 Agent 在生产环境里出问题的往往是第三层重试之后外部系统里多了一笔重复订单内部状态里残留着一个已过期但没被标记的上下文句柄。拿我自己做过的一个“智能取数”Agent 举例。它的流程是先理解用户问题然后查询元数据再生成取数 SQL最后执行 SQL 并总结结果。这个流程每一步都可能超时大语言模型LLM响应慢、元数据服务偶尔抖动、数据仓库执行大查询超时。我天真地给每一步都加了超时和重试结果有一天线上报了一个诡异的问题用户问“上个月销售额是多少”Agent 竟然返回了两条几乎一样但数值稍有差异的结果。我把日志翻出来一看原来是因为第二步“查询元数据”超时后重试但重试时 LLM 的上下文里已经塞进了一个旧的“查询返回结果”于是它在一个半更新的状态里继续执行最后生生跑出了两轮完整查询。1.3 一个朴素的“加超时”改动引发的连锁反应不夸张地说给第一步加了个 60 秒超时连锁反应能一路炸到第三步去第一步 LLM 调用超时重试第一次。重试时 LLM 可能已经给出来一个半成品的工具调用参数只是响应时间超出了设定阈值。这个参数被丢弃了吗取决于代码怎么写的。如果丢弃了那重试没问题但如果丢弃不及时它已经写进了上下文窗口。第二次LLM 基于更新过的上下文出了一个略微不同的 SQL。这个 SQL 其实是对的但因为第一次超时程序在第一次已经向数据仓库发过一条查询只是超时返回了。数据仓库这边查询其实执行了只是结果回传慢。于是第二次又跑了一遍同样的 SQL返回了两份结果。你看问题根本不在于“超时时间设成多少”而在于每次超时和重试之前Agent 的世界状态是不是干净如初。2. 给 AI Agent 加超时重试的正确姿势分层超时 按步骤重试2.1 超时不是单点而是一条链既然 Agent 是一个多步骤链那么超时必须分层而不是层层设同一个值。我最后用的分层方案是这样的单步工具调用超时默认 30 秒。这覆盖的是工具本身执行时间比如查数据库、调外部 API。单步 LLM 调用超时默认 60 秒。考虑到模型推理速度不稳定给的时间会长一些。单轮 Agent 总时长默认 120 秒。也就是从 Agent 接收一步输入到返回一步输出整个过程不能超过这个数。整次会话总时长默认 10 分钟。整个 Session 从开始到结束必须在这个时间内完成。为什么要这样设计因为不同环节的特征不一样。工具调用的超时本质上是“你有没有在预期时间内给我结果”LLM 调用的超时本质上是“这次生成太久了大概率已经不可用”而整轮超时控制的是 Agent 有没有陷入死循环、来回调用同一个工具却毫无进展。实际配置时我用的是一份 YAML把各层超时和对应重试次数写清楚方便调整agent: session_timeout_ms: 600000 step_timeout_ms: 120000 llm_timeout_ms: 60000 tool_timeout_ms: 30000 retry: llm_max_retries: 1 tool_max_retries: 2 session_max_retries: 0注意session_max_retries我设成了 0。整次会话一旦失败我不重试直接返回失败结果给用户宁可让用户重新发起一次也不要在半截状态上反复折腾。2.2 重试策略先问“这个步骤幂等吗”超时分层设好之后再来想重试。重试有一个前置条件只有幂等的步骤才允许直接重试。什么叫幂等就是执行一次和执行 N 次产生的结果都一样。比如读一个数据库表、调用一个不产生副作用的查询接口这类是天然幂等的超时后直接重试没有压力。不幂等的呢比如发送邮件、创建订单、写入日志、扣除余额。这些操作一旦执行外部系统就记住了重试一次等于多执行一次会造成严重的数据问题。所以我在给 Agent 编写重试逻辑时把每个工具都声明成一个带属性的对象标记idempotent是 true 还是 falseTOOL_REGISTRY { query_sales: {idempotent: True, timeout: 30}, send_email: {idempotent: False, timeout: 20}, create_order: {idempotent: False, timeout: 30, idempotency_key_required: True}, }在执行时重试逻辑大概长这样如果工具标记为幂等超时后直接重试重试次数按配置走。如果工具不幂等超时后不自动重试而是把当前状态标记为“interrupted”由上层策略决定是终止还是协商下一步。如果工具支持幂等键超时后带着同一个幂等键重试外部系统会基于该键去重。这个改动非常重要。加了幂等判断之后我线上因重复下单导致的脏数据明显少了很多。2.3 实操案例一个超时重试的具体实现纸上谈兵说得再多都不如一个能直接落地的代码骨架来得痛快。我用 Python 重写了一个简化版本把超时和重试封装在 Agent 的执行引擎里。import asyncio from dataclasses import dataclass, field from typing import Any, Callable, Optional dataclass class StepResult: status: str # success | timeout | error data: Any None attempts: int 0 error: Optional[str] None class AgentExecutor: def __init__(self, registry: dict, default_retries: int 2): self.registry registry self.default_retries default_retries async def execute_step(self, step_name: str, payload: dict, idempotency_key: Optional[str] None) - StepResult: tool self.registry.get(step_name) if not tool: return StepResult(statuserror, errorfunknown tool: {step_name}) max_retries tool.get(retries, self.default_retries) timeout tool.get(timeout, 30) is_idempotent tool.get(idempotent, False) for attempt in range(max_retries 1): try: result await asyncio.wait_for( tool[fn](payload, idempotency_keyidempotency_key), timeouttimeout ) return StepResult(statussuccess, dataresult, attemptsattempt 1) except asyncio.TimeoutError: if not is_idempotent: return StepResult( statustimeout, attemptsattempt 1, errornon-idempotent tool timed out; refusing to retry ) # 幂等工具继续重试 continue except Exception as exc: if attempt max_retries: return StepResult(statuserror, attemptsattempt 1, errorstr(exc)) return StepResult(statustimeout, attemptsmax_retries 1) # 重试耗尽核心点在于is_idempotent的判断。一旦一个非幂等步骤超时代码立即返回 timeout 状态而不是傻乎乎地重试。这样虽然会让个别任务失败但至少不会把“一次操作重复执行 N 次”的脏数据带进系统。那用户侧怎么办2024 年后我基本统一采用“幂等键 唯一资源 ID”的方案。具体做法是每个用户会话生成一个全局唯一的session_id每次需要写外部系统时把session_id和一个步进序号拼成一个idempotency_key随请求传给下游。下游如果支持幂等键比如支付接口、订单接口基本都支持就按这个键去重不支持的话至少我们在日志里能查到同一个键对应了哪些重复调用方便人工介入清理。3. 真正的坑状态清理我在这里摔得最狠3.1 状态残留导致的各种诡异问题如果说超时和重试只是“皮外伤”那状态残留就是“内伤”。最让我崩溃的一个线上事故至今记忆犹新。背景还是那个取数 Agent。它内部维护了一个execution_context里面存着当前步骤的编号、已经调用过的工具列表、正在使用的数据源连接、临时文件路径等。某一天某一步工具调用超时重试成功但我在日志里看到Agent 回答用户的最终结果里混进了一段上一个会话的历史数据。排查过程异常痛苦。我以为是上下文窗口清理没做干净改了之后还是复现。最后一行一行追代码才发现原来是这样的Agent 的执行引擎里有一个state变量它在执行第一步时把“从用户问题中解析出的查询条件”写进了state。第二步超时后重试重试逻辑只重新执行了第二步的函数但state里第一步的结果并没有被清掉而由于重试时上下文被更新state又追加了一个新的查询条件。于是 Agent 在最终生成 SQL 时把两个条件都拼进去了自然查出来的结果和预期完全不一样。这就是最典型的状态残留超时重试只重置了“当前函数的局部变量”却忘了重置“Agent 自身的会话状态”。3.2 给状态分域什么该留什么该清我后来反思旧代码之所以出事是因为所有状态都集中在同一个execution_context大字典里没有域的概念。哪部分是用户在对话中累积的“事实”哪部分是单次工具调用的“临时产物”哪部分是会话级别的“全局句柄”全部混在一起。一旦重试不会有人知道该把哪块清掉。后来我把状态拆成了三个独立的层次session_state会话级持久状态例如用户身份、对话历史摘要、业务上下文。这个状态只在会话开始和结束的时候更新中途不清理。step_state当前步骤的临时状态例如本步读取到的参数、临时变量、工具调用输入输出。每个新步骤开始时必须重新初始化。external_handles外部资源的句柄例如数据库连接、临时文件路径、缓存 key。这些句柄在步骤结束后必须显式释放。重试时规则就简单多了只重置step_state保留session_stateexternal_handles在超时后先回收。3.3 一个真实的清理策略Checkpoint 恢复状态清理不只是在“重试前”把step_state清空那么简单。如果清理时机不对你会把没问题的上下文也一起误删导致 Agent 在重试时失去了之前对话的记忆。我采用的是Checkpoint Repaint 策略。所谓 Checkpoint就是在每个步骤开始前把当前完整状态打一个快照存到内存中的一个栈里。一旦某个步骤超时触发重试先把状态恢复到该步骤开始前的快照再重新执行这一步。这样既清掉了半截状态下产生的脏数据又保住了之前所有步骤的成果。伪代码长这样class AgentWithCheckpoint: def __init__(self): self.snapshot_stack [] self.step_state {} self.session_state {} async def run_step(self, step_name: str, payload: dict): # step 开始前保存快照 snapshot { session_state: deepcopy(self.session_state), step_state: deepcopy(self.step_state), external_handles: list(self.external_handles), } self.snapshot_stack.append(snapshot) try: result await self.executor.execute_step(step_name, payload) except Exception: # 恢复快照回收句柄 self.restore_snapshot() raise def restore_snapshot(self): snap self.snapshot_stack.pop() self.session_state snap[session_state] self.step_state {} # 关闭所有旧句柄 for h in snap[external_handles]: h.close() self.external_handles.clear()每次重试前不再是一个“清空所有状态”的粗暴动作而是“回到上一步结束时的状态”这个语义非常容易理解也容易测试。后来我把这套逻辑封装成了一个StateManager配合 Agent 的每个 action 自动执行终于再没出现过“重试后结果里混进了旧数据”的问题。3.4 会话级状态清理定时回收 显式释放除了步骤级的状态清理会话级的状态管理同样麻烦。Agent 的 Session 是有生命周期的用户开启一个会话可能聊几轮就断了下次再发起如果 Session 还存在Agent 就要恢复上下文。但如果 Session 超时且标记为失败就必须把它占用的资源全部释放关闭数据库连接、删除临时文件、解除锁、清空消息队列的消息等。我用 Cron 加一个定期扫描任务每 5 分钟扫一次所有活跃 Session判断是否符合清理条件async def cleanup_expired_sessions(): async for session in db.iter_sessions(statusactive): if session.stale_before(datetime.now() - timedelta(minutes30)): await session.release_all_external_handles() await session.mark_failed(session timeout, state cleaned)这里有几个细节stale_before的判断逻辑是如果 Session 距今超过 30 分钟没有任何新活动且还有未完成的步骤直接标记为失败并清理。清理顺序是先释放外部句柄再清理内存状态最后落库标记状态。不能反过来否则万一释放句柄的时候报错数据库里还是“active”状态下次扫描又会重复清理。释放句柄要尽量幂等。数据库连接关闭两次会报错所以每个句柄都带一个is_closed标记关闭之前先判断。这些看起来是零碎的小细节但恰恰是生产环境稳定性的分水岭。没有这套清理机制前我线上跑了两周Redis 连接数直接打满加了定时清理之后资源占用非常平稳。4. 常见问题与排查技巧实录4.1 我以为的重试成功实际上是在重复犯同一个错有一段时间我发现某个 Agent 的总失败率降下来了但下游客户反馈说经常收到两条一模一样的数据通知。查了半天才发现我设的“成功”判定标准错了。当时代码如下只要 Agent 最后一步返回结果没有抛异常就判定为成功。但问题是重试发生在第 2 步重试成功后第 3 步也执行成功而第 1 步的半成品副作用也就是那条数据通知已经发出去了。于是最终结果是第 1 步的重复通知 第 2 步的成功结果 一次任务的“成功”。这种场景判断成功不能只看“返回了结果”还要校验起始步骤完成后是否真的产生了预期效果。最简单的做法是在 Agent 结束时对关键事件做一个side_effect校验对比“预期应该发生的事件”和“实际发生的事件”不一致的宁可判定失败。4.2 清理了状态结果把外部副作用也“恢复”掉了这个坑是我在实施 Checkpoint 策略之后踩的。恢复快照从代码角度是把session_state恢复到上一步外部句柄全部关闭。但外部系统的副作用不会随着快照恢复而消失——邮件发出去了就是发出去了不会因为状态回滚而撤回。有一次我恢复快照后旧的连接句柄被关闭但新连接又建立起一个新的事务恰好新事务里需要读取“某个外部系统已写入的数据”然而那个数据是在出错的步骤里刚写入但未提交的。由于快照恢复会丢弃未提交的外部信息Agent 就以为“外部数据不存在”结果走了完全不同的逻辑分支。这个问题的解法是状态清理的目标是 Agent 视图的一致性而不是外部副作用的一致性。对外部系统的副作用需要额外的回滚或补偿机制。我会在session_state里维护一个side_effect_log每次调用非幂等工具前先记录“预期副作用”一旦需要回滚就按这个日志反向操作。比如发送邮件回滚就是发一封“撤销”通知创建订单回滚就是标记订单作废。4.3 超时重试之后上下文窗口里的内容不一致比较隐蔽的问题是程序层面的状态清理干净了但 LLM 的上下文窗口里还留着上一轮超时时丢弃的半截信息。这类问题不像前两种那么好排查因为它不在我们的日志里而是在模型的“记忆”里。排查时最直接的方式是做一次“上下文快照对比”把超时前后的 prompt 完整打印出来手动比对中间是否多出了不属于当前步骤的内容。我通常会在每次调用 LLM 前把 prompt 写入一个 trace 日志文件字段包括step_name、step_id、prompt_hash、prompt_content。出问题时按step_id过滤看同一 ID 下的 prompt 变了没有。2025 年入局 Agent 开发的人越来越多很多人喜欢直接用框架自带的prompt_cache或者上下文管理机制。我个人建议任何重要的 Agent 任务不要过度依赖框架的上下文管理最好自己维护一个context_builder每一步都显式地定义“应该给模型什么信息”。只有这样才能保证超时重试前后模型看到的世界是连贯且干净。下面是我那段时间整理的常见问题速查表放这里方便各位直接参考现象根因处理办法重试后返回结果包含旧数据步骤级状态未重置引入 snapshots 机制重试前恢复上一步状态重试后用户收到两条相同通知非幂等工具被重复执行标记非幂等工具超时后拒绝自动重试会话结束但连接数持续上涨Session 清理不完整定时扫描释放外部句柄后再落库超时后语境错乱回答答非所问上下文窗口残留旧步骤信息每次调用 LLM 前显式构建上下文不依赖框架缓存重试后走过完全不同的逻辑分支快照恢复丢失了外部副作用记录维护 side_effect_log需要时做补偿操作明明重试成功了任务还是失败成功判定标准写得太宽松增加关键事件校验起始步骤副作用验证4.4 排查工具怎么选日志、追踪、模拟注入最后聊两句排查工具。光是加日志已经不够用了Agent 链路太长一步超时后面所有步骤的上下文全变单看日志很难定位真正的脏数据源头。我现在的主力方案是结构化日志所有步骤的出入参、耗时、状态变更全部打 JSON 日志方便按session_id或step_id聚合。请求追踪 ID每个 Agent 任务都生成一个trace_id贯穿所有外部调用。配合 OpenTelemetry 之类的工具能看到整个链路的调用树超时发生在哪一层、重试了几次、每次用了多少时间一目了然。故障注入本地测试时专门加一个“混沌模式”随机给每个工具调用注入 1~5 秒延迟或者直接让某个工具 50% 概率抛超时。实测下来很多在正常路径上发现不了的状态清理问题在故障注入模式下会很快暴露。我最后一次把一个“隐藏已久”的状态残留问题揪出来靠的就是故障注入。把故障注入打开跑了一个小时直接复现了那个“结果里混进旧查询条件”的 bug定位效率比在线上靠用户反馈高太多了。5. 一些实用建议按优先级排序如果你正在或者准备做 AI Agent 生产化以下几个建议我是按照踩坑收益从高到低排的可以直接抄作业第一一定要给外部调用分层设超时别一口吃成胖子。整轮超时统一 120 秒是没意义的因为内部可能包含一个数据库查询和一个 LLM 推理它们的耗时方差天差地别。分层的意义在于你能精准知道到底哪一环拖慢了整体并针对性地调整重试策略。第二重试之前先把状态快照好。每次执行新步骤前做一次快照不只是“以防万一”更是为了让你有信心做重试。没有快照的重试本质上就是碰运气。第三非幂等操作宁可不重试也不要错重试。重试的目标是“提高成功率”但如果重试会把一个操作执行两次那它带来的危害比直接失败更大。用户收到一条超时错误最多抱怨一下用户收到两条重复订单那就是事故了。第四状态清理要分域、分层。会话级状态、步骤级状态、外部句柄三者务必分开管理别用一个 dict 一把抓。清理的顺序也很重要先外部句柄再内存状态最后落库标记缺一步都会留尾巴。第五别把 LLM 的上下文当“不变量”。程序里的状态你管得住LLM 的上下文你自己也得管。每次调用前显式构建 prompt把旧步骤的半截信息挡在门外这是很多人容易忽略又最容易出问题的一环。6. 我对这套方案的实际体会这套“分层超时 幂等重试 分域状态清理”的方案上线后Agent 的线上错误率降了差不多一个数量级。最有体感的改变反而不是错误率本身而是排查问题的速度变快了以前一个脏数据问题要在日志里翻半天现在通过 state snapshot、side_effect_log 和 trace_id基本能在十分钟内定位到是哪个步骤哪个状态没有清干净。最后分享一个小技巧。如果你也遇到了“重试后跟没重试一个样”的情况别只盯着重试代码看先把你的restore函数测试一遍写一个专门的单测故意让某一步超时然后断言重试后step_state里确实没有上一轮的残留字段。我当时写这个单测时一口气测出了三个隐藏的清理死角——有个旧代码里把一个本该在步骤结束时释放的连接池还挂在全局单例上不测根本发现不了。Agent 的稳定性不是靠一个魔法参数解决的超时、重试、状态清理这三件套任何一个环节偷懒最终都会以更难看的方式在线上还回来。