接到一个跑在生成式模型接口上的智能助理经常出现用户在提问之后等很久没反应甚至整个会话直接崩溃的情况。一开始我的第一反应是“这还不简单给调用加超时、加重试不就完了”。可真动手做出来之后我被坑得够呛真正让系统不可用的根本不是模型响应慢而是超时和重试触发了之后Agent 内部状态已经散成一锅粥下一个请求进来直接拿脏数据继续推理。这个问题如果不处理加什么超时和重试都是在给事故埋雷。这篇文章我把整个排查和改造过程完整记录下来包括超时该加在哪一层、重试策略怎么做才不放大故障以及最容易被忽略的 Agent 状态清理到底该怎么设计。适合正在自己搭 Agent 应用、或者已经在生产环境被“卡死”问题折磨过的人这套方法论比盲目抄几个装饰器有用得多。1. 超时重试之前先搞清楚 Agent 为什么会卡死1.1 从一次线上事故说起一个“卡住”的 Agent 背后的真相我们有一个基于大模型 API 的客服助理用户问一个问题Agent 内部会经历“理解意图 — 调用工具 — 再生成回答”的循环。某天线上反馈说客服机器人偶尔会“装死”日志里没有任何报错就是一直不回复。刚开始我怀疑是模型 API 超时于是给请求加了 10 秒超时。结果第二天更离谱超时倒是生效了但用户看到的是“请求失败请重试”而且重试之后不仅没变好反而开始答非所问。查了半天才发现问题出在 Agent 的记忆模块和工具调用记录上上一次请求虽然超时中断了但中间产生的“工具调用结果”“临时推理步骤”被原样保留了下来新的请求进来以后Agent 把这些残留数据当成当前上下文的一部分等于带着上一轮的“半成品答案”继续干活。这个事故让我意识到一件事Agent 的运行模型和普通 HTTP 接口有本质区别。普通接口无状态超时重试只要保证请求本身正确就行但 Agent 是有状态的执行流它的“执行现场”包括上下文窗口、工具调用栈、状态机当前节点、甚至外部系统里已经产生的副作用。你只是简单粗暴地掐断请求现场残留的垃圾数据不会自己消失下一次运行就会把这些垃圾当燃料。1.2 Agent 的“状态”到底指什么上下文、会话、工具调用栈在继续聊方案之前必须先定义清楚我们说的“状态”是什么。我做 Agent 时会把状态拆成四层缺一层都可能在超时重试之后出问题。第一层是对话上下文也就是喂给模型的那一串历史消息。这一层最容易理解也最容易出问题超时发生的时候上下文里可能已经塞了一条“正在调用某某工具”的中间消息但实际上这个工具根本没调用成功。第二层是工具调用栈包括当前正在执行的工具名称、入参、执行进度。一个 Agent 在单次任务里可能连续调用多个工具假设它先查了订单表又调了物流接口结果在调物流接口时超时了那么“查订单表”得到的中间结果算谁的如果不清理重试时会拿着旧的订单数据去匹配新的物流请求结果可想而知。第三层是状态机和节点流转信息这在用 LangGraph 这类框架时尤其明显。Agent 内部被编排成一张图每个节点表示一个处理步骤节点之间有状态传递。超时发生时可能某个节点已经标记为“完成”但实际上它的输出没有成功写入下游节点这时候状态机和真实执行结果已经不一致了。第四层是外部副作用比如已经扣减的库存、已经发送的消息、已经创建的工单。这一层最危险因为超时重试不会自动回滚外部系统你必须自己设计补偿逻辑。把这些状态拆清楚之后再回头看“给 Agent 加超时和重试”你会发现这根本不是网络层的问题而是一个分布式事务问题如何让一次可能被中断的 Agent 执行流程在重试之后依然保持正确性。2. 超时机制设计Timeout 不是拍脑袋定一个数2.1 超时应该加在哪几个环节很多人只会给“调用大模型 API”那一个地方加超时这是典型的新手做法。实际上一个 Agent 执行链路过超时的环节至少有四个。第一个环节是用户请求整体超时也就是整个 Agent 任务最多跑多久。比如你可以在 API 网关或者外层调度器设置“单个用户请求最长处理时间 30 秒”超过 30 秒直接返回失败用户不用无限等。第二个环节是单次模型推理超时。这个要区分“首 Token 时间”和“总生成时间”大模型接口现在一般支持 stream 模式如果长时间没有任何 Token 返回说明模型侧出问题了这类超时要单独设。有的模型接口还区分“连接超时”“读超时”和“总响应超时”我们实际用下来读超时比连接超时重要得多因为很多模型服务端是“连接秒开生成半天不出货”。第三个环节是单次工具调用超时。Agent 调用第三方 API 时绝对不能跟着第三方接口自己的节奏走。我见过有些业务方把外部 HTTP 客户端的默认超时留成 30 秒而 Agent 总超时才 15 秒这样会出现总超时先触发工具调用却被丢弃在后台继续执行产生一系列后续问题。第四个环节是 Agent 内部循环的步超时。Agent 是一个“多轮推理 多轮工具调用”的过程比如最多允许循环 5 步每一步单独计时而不是只给整个任务设定总计时。否则就会出现“单步非常慢但总时间没超整个任务被拖死”的情况。2.2 超时参数的设置思路与计算公式超时参数的设定不能凭空拍脑袋。我的做法是先做压测再按分位数来定。假设你对模型接口做了 1000 次调用统计出 p50 响应时间是 2 秒p95 是 6 秒p99 是 12 秒。那单次模型推理超时不要直接定 12 秒而是定在 p95 到 p99 之间比如 10 秒左右再配合重试机制。为什么不定 p99因为让极端慢的请求直接失败比重试等一个已经明显异常的请求更合理。外层整体超时则要根据 Agent 平均步数和每步超时来倒推假设平均要跑 4 步每步最大 10 秒加上中间的编排开销和网络消耗整体超时建议设为 4×10×1.5也就是 60 秒左右。这个 1.5 是一个经验系数给编排框架、排队时间、Token 解析留余地。工具调用超时就更好算了直接看被调用服务的性能。如果是内部 RPC一般 3 到 5 秒足够如果是外部 HTTP 接口8 到 10 秒比较合理如果涉及文件上传下载那就分阶段设置连接阶段 5 秒传输阶段按文件大小估算。总之每一层超时都要比“下一层”更宽松形成递进关系单次模型推理 10 秒 单次工具调用 15 秒 Agent 单步 20 秒 整个任务 60 秒。2.3 实际代码实现给 LLM 调用和工具调用分别加超时我实际用的是 Python 的 async 环境下面这套思路可以平移到任何语言。先不要急着重试让超时先精确地作用到每一个环节。import asyncio from contextlib import asynccontextmanager asynccontextmanager async def timeout_ctx(seconds: float, label: str): 统一超时上下文超时后记录现场快照 try: async with asyncio.timeout(seconds): yield except TimeoutError: print(f[timeout] {label} exceeded {seconds}s) # 这里一定要做状态快照后续会解释为什么 snapshot capture_agent_snapshot() # 记录到日志用于离线排查 raise AgentTimeoutError(labellabel, snapshotsnapshot) async def call_llm_with_timeout(prompt: str, timeout: float 10.0): async def _do_call(): # 以 OpenAI SDK 为例streamFalse 时它内部负责连接 # 我们只关心总体耗时 return await llm_client.chat.completions.create( modelyour-model, messagesprompt, ) async with timeout_ctx(timeout, llm_inference): return await _do_call() async def call_tool_with_timeout(tool_name: str, args: dict, timeout: float 15.0): async def _do_call(): # 这里换成真实工具调用逻辑 return await tool_registry.invoke(tool_name, args) async with timeout_ctx(timeout, ftool_{tool_name}): return await _do_call()这个实现的核心在于timeout_ctx内部在超时发生时调用capture_agent_snapshot()。这一步看似多余实际上是你后续做状态清理和原因排查的唯一抓手。没有这个快照超时发生之后你根本不知道 Agent 执行到哪一步想恢复现场都不知道从哪恢复。3. 重试机制设计指数退避不是万能的3.1 重试要区分“可重试错误”和“不可重试错误”超时加上之后紧接着要处理重试。但重试有个大前提不是所有错误都能重试。如果错误是因为参数校验失败、业务规则拒绝、或者模型内容安全过滤导致的你重试 100 次也没用只会浪费资源和算力。我一般把错误先分类。可重试的包括网络连接超时、读超时、HTTP 5xx、限流429、以及大模型服务端返回的“临时性错误”。不可重试的包括HTTP 4xx尤其是 400、422、输入格式错误、工具依赖的业务数据不存在等。这个分类非常重要因为 Agent 场景和普通微服务不一样普通微服务重试失败大不了再报一次错但 Agent 重试意味着要重新整理上下文、重新进入推理状态机一旦对不可重试的错误也傻乎乎重试就会出现“同一个错误触发三次工具调用、三次失败、然后又往上下文里塞三份错误日志”的连锁反应。3.2 幂等设计为什么重试之前必须确认工具是幂等的重试最怕的还不是超时而是“明明第一次已经执行成功了但因为响应丢失你又执行了一遍”。比如一个“创建订单”的工具第一次调用成功生成了订单号但是网络延迟导致系统以为失败了重试时又创建了一个新订单。这不是状态清理能解决的问题这是幂等设计缺失。在设计工具接口时需要尽量做到两件事一是支持幂等键每一轮 Agent 的请求都带一个唯一的trace_id或request_id工具侧根据这个 ID 判断是否已经处理过如果处理过就直接返回第一次的结果不重复执行二是把“读操作”和“写操作”分开查询、检索类工具天然幂等重试无压力但扣减库存、发送短信、创建工单这类写操作必须设计成“先提交意图再确认执行”的模式或者用预扣 确认 回滚的流程。在重试层面我用了一个非常简单的策略重试时把同一个工具调用请求体原封不动地带着并显式标注“这是重试请求”。工具侧会优先检查业务幂等表表里命中就直接返回原有结果。这个策略虽然牺牲了一点性能但换来了整个系统最大的安全保障。3.3 重试代码实现指数退避 抖动重试的节奏也要讲究不能一失败就立刻重试更不能无脑指数退避到很大。我用的公式是base_delay * 2^attempt random_jitter。具体实现如下。import random import asyncio async def run_with_retry(agent_step, retries: int 3): delay 0.5 # 初始退避 0.5 秒 for attempt in range(retries): try: result await agent_step() return result except AgentTimeoutError: if attempt retries - 1: raise jitter random.uniform(0, delay) await asyncio.sleep(delay jitter) delay * 2 except AgentNonRetryableError: # 不可重试错误直接抛出去不要浪费重试次数 raise except AgentServiceUnavailableError: # 服务不可用说明整个 Agent 状态可能处于加载中 # 这种情况重试前需要重置状态机到安全节点 reset_agent_state_to_safe_node() if attempt retries - 1: raise jitter random.uniform(0, delay) await asyncio.sleep(delay jitter) delay * 2这里想强调的是reset_agent_state_to_safe_node()这个函数。我当时加这个函数的契机是服务端 503 时会清理一个内部缓存但清理之后 Agent 的上下文引用的是旧缓存里的对象导致重试时模型引用了不存在的会话信息。重新从“安全节点”加载状态之后才算真正干净的失败恢复。重试次数也不建议太多常规外部依赖重试 3 次如果 Agent 内部是多步执行建议对单步重试 2 次、对整个任务不再重试而是直接进入降级方案。降级方案可以是“返回模糊答案 提示稍后再问”也可以是“将这个任务转人工”。对用户体验来说一个诚实的失败提示远好过让用户看着转圈等他重试成功。4. 真正的坑状态清理4.1 超时/重试后Agent 的残留状态会导致什么这一节才是整篇文章的重点。前面所有超时和重试机制在状态清理失效时全部会反噬。我举几个真实的残留状态案例第一个案例上下文里堆积“半成品消息”。Agent 在调用工具前会生成一条类似“我正在为您查询订单请稍等”的中间消息。如果这个请求超时中断重试时新的执行流又生成一条同样的消息。如果清理机制不工作模型拿到的历史消息里会有两条甚至三条重复的中间提示。表面上无伤大雅但模型会认为系统出现了异常反而在生成回答时自我怀疑输出质量明显下降。第二个案例状态机走到了非法节点。在 LangGraph 里每一步执行都会返回一个AgentState里面记录了已经访问过的节点列表。如果第一次执行已经完成了“查询订单”节点并写入状态但没来得及进入“生成回答”节点就超时了重试时整个执行流从头开始那“查询订单”节点会被执行两次。如果你没有对外部副作用做幂等保护等于同一个订单被查询两次没大事但同一个“扣款”节点执行两次就是灾难。第三个案例最隐蔽工具调用栈的残留入参。我遇到过这样的情况一次超时发生在“发送邮件”工具调用后但响应没有写到状态里。重试时 Agent 认为这个工具还没调用于是再次调用。第二次调用成功生成了新邮件。两个邮件都发出去了用户收到了重复邮件。这个场景里问题既不是超时代码写得不对也不是重试策略不对而是状态清理根本没有意识到“第一次调用已经产生了副作用”。4.2 状态快照、恢复与回滚状态清理不是简单地把状态对象清空重来而是要在正确的时间点做三件事快照、恢复、回滚。快照就是我在超时上下文里提到的capture_agent_snapshot()。它要保存的内容包括当前上下文消息列表的长度和最后一条消息的 ID当前状态机节点和数据流转记录当前正在执行的工具名和入参一个单调递增的执行序号。有了这些信息当超时发生时你至少能回答“Agent 死在哪里、死了之后给谁留下了什么”。恢复有两种策略一种是从快照继续执行适合那种“前一步成功、后一步失败”的幂等场景另一种是回退到上一个安全检查点适合那种“中间步可能已经产生副作用”的场景。我刚上线时选择了“永远从检查点重新执行”结果吃了个大亏一个工具明明已经执行成功且副作用不可取消我从检查点重跑又执行了一遍。后来我改成“根据快照判断是否已经产生副作用如果产生了就跳过该工具直接进入下一节点”。4.3 清理工具调用栈和已执行副作用状态清理的核心动作是“对账”而不是“删除”。不要一上来就把工具调用栈清空而是先做一遍“哪些已经执行、哪些未执行、哪些可能部分执行”的审计。我设计了一个简单的执行记录表存到 Redis 里{ task_id: task_abc123, step_id: step_004, tool_name: payment.deduct, request_id: req_001, status: SUCCESS_OR_UNKNOWN, effect_applied: False, retry_count: 1, created_at: 1700000000 }每次工具调用前先写入一条PENDING记录成功后改成SUCCESS失败后改成FAILED如果超时导致结果未知就保持SUCCESS_OR_UNKNOWN。重试时如果发现某条SUCCESS_OR_UNKNOWN记录对应的工具不是幂等的就必须用另一个“补偿工具”去检查外部系统里到底有没有产生效果。比如“创建工单”工具超时了就先调“查询工单是否已创建”接口去确认确认已创建就直接复用结果确认未创建再重试。这个“先对账再重试”的模式是 Agent 状态清理和普通缓存清理之间最大的区别你的清理动作必须尊重外部系统的真实状态而不是只盯着内存里的对象。4.4 实现状态清理的代码骨架我给出一个精简但可以直接落地的状态清理逻辑。这里我用的是内存里的状态对象生产环境建议换成 Redis 或数据库但骨架不变。from enum import Enum from typing import Optional, Dict from dataclasses import dataclass, field class ToolStatus(str, Enum): PENDING pending SUCCESS success FAILED failed UNKNOWN unknown # 超时未确认 dataclass class ToolExecutionRecord: tool_name: str request_id: str status: ToolStatus ToolStatus.PENDING result: Optional[Dict] None effect_confirmed: bool False # 是否已对外部副作用做过确认 dataclass class AgentState: task_id: str context_messages: list field(default_factorylist) tool_records: Dict[str, ToolExecutionRecord] field(default_factorydict) current_node: str start visited_nodes: list field(default_factorylist) def cleanup_agent_state_for_retry(state: AgentState): 重试前最关键的状态清理。这一步做不好重试就是在放大错误。 for tool_name, record in state.tool_records.items(): if record.status is ToolStatus.UNKNOWN: confirm_result confirm_external_effect(record) if confirm_result.confirmed: record.status ToolStatus.SUCCESS record.effect_confirmed True else: record.status ToolStatus.FAILED # 对已经成功的工具保留结果防止重试时重复执行 # 对失败的如果不可重试就直接删掉记录 state.context_messages prune_half_thought_messages(state.context_messages) state.current_node find_last_safe_node(state.visited_nodes) state.visited_nodes state.visited_nodes[: state.current_node_index 1]这套逻辑的关键有两点一是confirm_external_effect用它来判断外部副作用状态二是prune_half_thought_messages把上下文里那些“我正在调用工具”的中途消息去掉只保留真实的用户输入和已完成工具的最终结果。我最早没有写confirm_external_effect导致重试场景下脏数据率没降下来后来补上之后异常恢复准确率有了非常明显的提升。5. 常见问题排查与避坑实录5.1 常见问题速查表在实际落地过程中我把典型问题和解决方案整理成了一个表团队新同学来了直接看这个表就能排查大部分故障。症状根因排查方向解决方案超时后重试回答内容明显重复上下文里堆积了“正在处理”之类的中间消息检查context_messages是否有多条未完成消息清理中间消息只保留已完成步骤的最终结果工具被重复执行出现重复订单或重复消息幂等键缺失或状态清理未做外部副作用确认查看 Redis 执行记录里同名工具的 status 是否从 UNKNOWN 变 SUCCESS补幂等键重试前调用查询接口确认副作用是否已生效重试后模型引用了一个不存在的会话对象状态机节点流转没有清理visited_nodes 指向了非法节点查看current_node和visited_nodes的对应关系重试前回退到上一个安全节点而不是从 start 重启外部接口 503 后重试一直失败状态对象引用了过期的缓存检查状态里是否持有了外部缓存引用在捕获服务不可用异常时清空相关缓存引用并重置状态单步重试成功但整体最终超时每步重试次数太多累计耗时超标查看链路日志里每步耗时减少重试次数或对整体任务加熔断直接降级重试过程中模型不断自我纠正回答失去重点上下文里塞入了大量错误类型的历史消息检查之前重试失败的错误消息是否被写入上下文写入上下文前过滤错误或者对同一个执行流做上下文隔离这个表里最值钱的不是前三行而是最后两行。“单步重试成功但整体最终超时”是我们上了完整机制之后才遇到的问题因为每步单独重试 3 次遇到连续两个工具都超时整体时间就彻底失控了。后来我把“单工具重试”和“整个 Agent 任务熔断”分开设置一旦整个任务已经消耗了总预算的 80%就不再发起新的工具重试直接走降级。5.2 实操心得我踩过的几个真实坑第一个坑给重试加完抖动之后忘了加“全局去重”。有一次我同时发起两个重试任务因为之前有个请求的 Agent 执行流被打断但没有标记为“已完成”调度器又把它捞起来重跑同一个任务出现两个并发副本。后来我在每轮任务开始前检查 Redis 里的任务锁锁没拿到就直接丢弃新请求避免同一task_id被并发执行。第二个坑清理状态时把“成功的工具结果”也一起清掉了。一开始我的清理逻辑很简单直接清空tool_records结果重试时 Agent 把第一个工具又调用了一遍。虽然不是写操作还好但浪费了几百毫秒而且可能造成数据不一致。正确做法是保留成功记录只清理“未完成的中间状态”和“可能产生副作用的未知状态”。第三个坑对错误类型分类时把“工具业务异常”也当成了可重试。有一次工具返回“订单不存在”我傻乎乎地重试了 3 次每次都是同样的错误还多产生了几条日志。后来我在工具异常里加了business_error标记凡是业务规则类错误直接结束本轮重试让 Agent 向用户解释错误原因。第四个坑值得单独说状态清理的顺序不能反。先确认外部副作用再清理上下文。我一开始反过来了先清了上下文再去做副作用对账结果对账函数需要读取上下文里的request_id而我已经把它删了。后来把这套流程改成了“先冻结现场 — 确认副作用 — 更新执行记录 — 最后裁剪上下文”的顺序稳定了很多。第五个坑是关于日志的超时发生时打印的现场信息一定要完整尤其是request_id、tool_name、step_index、上下文里最后一条消息的内容。我早期日志打得不够全每次一出问题就要靠猜后来把所有关键快照用结构化日志输出排查时间从“几小时”压缩到了“看一条日志就能定位”。5.3 最后再分享一个关于清理时机的小技巧状态清理不一定要等到“超时发生后”再做更好的做法是在“每步工具调用前”就预留一个清理点。具体来说Agent 每完成一个工具调用就执行一次“增量检查”把已经确认成功的记录从待清理列表中移除把还挂着 UNKNOWN 的记录单独标记。这样当真的发生超时时需要清理的数据量会非常小恢复速度也更快。我是在一次压测中验证了这个思路不预清理时超时恢复平均耗时 800 毫秒预清理之后恢复耗时降到 200 毫秒以内。原因很简单预清理让每次重试面对的脏数据窗口更窄而窗口越窄状态不一致的概率越低。如果你也在做 Agent 应用我真心建议不要只在网络层做文章。超时和重试只是入口状态清理才是那个决定你在生产环境活得好不好的关键点。先把状态模型画清楚再动手写超时时间这个顺序别搞反了。
接到一个跑在生成式模型接口上的智能助理经常出现用户在提问之后等很久没反应甚至整个会话直接崩溃的情况。一开始我的第一反应是“这还不简单给调用加超时、加重试不就完了”。可真动手做出来之后我被坑得够呛真正让系统不可用的根本不是模型响应慢而是超时和重试触发了之后Agent 内部状态已经散成一锅粥下一个请求进来直接拿脏数据继续推理。这个问题如果不处理加什么超时和重试都是在给事故埋雷。这篇文章我把整个排查和改造过程完整记录下来包括超时该加在哪一层、重试策略怎么做才不放大故障以及最容易被忽略的 Agent 状态清理到底该怎么设计。适合正在自己搭 Agent 应用、或者已经在生产环境被“卡死”问题折磨过的人这套方法论比盲目抄几个装饰器有用得多。1. 超时重试之前先搞清楚 Agent 为什么会卡死1.1 从一次线上事故说起一个“卡住”的 Agent 背后的真相我们有一个基于大模型 API 的客服助理用户问一个问题Agent 内部会经历“理解意图 — 调用工具 — 再生成回答”的循环。某天线上反馈说客服机器人偶尔会“装死”日志里没有任何报错就是一直不回复。刚开始我怀疑是模型 API 超时于是给请求加了 10 秒超时。结果第二天更离谱超时倒是生效了但用户看到的是“请求失败请重试”而且重试之后不仅没变好反而开始答非所问。查了半天才发现问题出在 Agent 的记忆模块和工具调用记录上上一次请求虽然超时中断了但中间产生的“工具调用结果”“临时推理步骤”被原样保留了下来新的请求进来以后Agent 把这些残留数据当成当前上下文的一部分等于带着上一轮的“半成品答案”继续干活。这个事故让我意识到一件事Agent 的运行模型和普通 HTTP 接口有本质区别。普通接口无状态超时重试只要保证请求本身正确就行但 Agent 是有状态的执行流它的“执行现场”包括上下文窗口、工具调用栈、状态机当前节点、甚至外部系统里已经产生的副作用。你只是简单粗暴地掐断请求现场残留的垃圾数据不会自己消失下一次运行就会把这些垃圾当燃料。1.2 Agent 的“状态”到底指什么上下文、会话、工具调用栈在继续聊方案之前必须先定义清楚我们说的“状态”是什么。我做 Agent 时会把状态拆成四层缺一层都可能在超时重试之后出问题。第一层是对话上下文也就是喂给模型的那一串历史消息。这一层最容易理解也最容易出问题超时发生的时候上下文里可能已经塞了一条“正在调用某某工具”的中间消息但实际上这个工具根本没调用成功。第二层是工具调用栈包括当前正在执行的工具名称、入参、执行进度。一个 Agent 在单次任务里可能连续调用多个工具假设它先查了订单表又调了物流接口结果在调物流接口时超时了那么“查订单表”得到的中间结果算谁的如果不清理重试时会拿着旧的订单数据去匹配新的物流请求结果可想而知。第三层是状态机和节点流转信息这在用 LangGraph 这类框架时尤其明显。Agent 内部被编排成一张图每个节点表示一个处理步骤节点之间有状态传递。超时发生时可能某个节点已经标记为“完成”但实际上它的输出没有成功写入下游节点这时候状态机和真实执行结果已经不一致了。第四层是外部副作用比如已经扣减的库存、已经发送的消息、已经创建的工单。这一层最危险因为超时重试不会自动回滚外部系统你必须自己设计补偿逻辑。把这些状态拆清楚之后再回头看“给 Agent 加超时和重试”你会发现这根本不是网络层的问题而是一个分布式事务问题如何让一次可能被中断的 Agent 执行流程在重试之后依然保持正确性。2. 超时机制设计Timeout 不是拍脑袋定一个数2.1 超时应该加在哪几个环节很多人只会给“调用大模型 API”那一个地方加超时这是典型的新手做法。实际上一个 Agent 执行链路过超时的环节至少有四个。第一个环节是用户请求整体超时也就是整个 Agent 任务最多跑多久。比如你可以在 API 网关或者外层调度器设置“单个用户请求最长处理时间 30 秒”超过 30 秒直接返回失败用户不用无限等。第二个环节是单次模型推理超时。这个要区分“首 Token 时间”和“总生成时间”大模型接口现在一般支持 stream 模式如果长时间没有任何 Token 返回说明模型侧出问题了这类超时要单独设。有的模型接口还区分“连接超时”“读超时”和“总响应超时”我们实际用下来读超时比连接超时重要得多因为很多模型服务端是“连接秒开生成半天不出货”。第三个环节是单次工具调用超时。Agent 调用第三方 API 时绝对不能跟着第三方接口自己的节奏走。我见过有些业务方把外部 HTTP 客户端的默认超时留成 30 秒而 Agent 总超时才 15 秒这样会出现总超时先触发工具调用却被丢弃在后台继续执行产生一系列后续问题。第四个环节是 Agent 内部循环的步超时。Agent 是一个“多轮推理 多轮工具调用”的过程比如最多允许循环 5 步每一步单独计时而不是只给整个任务设定总计时。否则就会出现“单步非常慢但总时间没超整个任务被拖死”的情况。2.2 超时参数的设置思路与计算公式超时参数的设定不能凭空拍脑袋。我的做法是先做压测再按分位数来定。假设你对模型接口做了 1000 次调用统计出 p50 响应时间是 2 秒p95 是 6 秒p99 是 12 秒。那单次模型推理超时不要直接定 12 秒而是定在 p95 到 p99 之间比如 10 秒左右再配合重试机制。为什么不定 p99因为让极端慢的请求直接失败比重试等一个已经明显异常的请求更合理。外层整体超时则要根据 Agent 平均步数和每步超时来倒推假设平均要跑 4 步每步最大 10 秒加上中间的编排开销和网络消耗整体超时建议设为 4×10×1.5也就是 60 秒左右。这个 1.5 是一个经验系数给编排框架、排队时间、Token 解析留余地。工具调用超时就更好算了直接看被调用服务的性能。如果是内部 RPC一般 3 到 5 秒足够如果是外部 HTTP 接口8 到 10 秒比较合理如果涉及文件上传下载那就分阶段设置连接阶段 5 秒传输阶段按文件大小估算。总之每一层超时都要比“下一层”更宽松形成递进关系单次模型推理 10 秒 单次工具调用 15 秒 Agent 单步 20 秒 整个任务 60 秒。2.3 实际代码实现给 LLM 调用和工具调用分别加超时我实际用的是 Python 的 async 环境下面这套思路可以平移到任何语言。先不要急着重试让超时先精确地作用到每一个环节。import asyncio from contextlib import asynccontextmanager asynccontextmanager async def timeout_ctx(seconds: float, label: str): 统一超时上下文超时后记录现场快照 try: async with asyncio.timeout(seconds): yield except TimeoutError: print(f[timeout] {label} exceeded {seconds}s) # 这里一定要做状态快照后续会解释为什么 snapshot capture_agent_snapshot() # 记录到日志用于离线排查 raise AgentTimeoutError(labellabel, snapshotsnapshot) async def call_llm_with_timeout(prompt: str, timeout: float 10.0): async def _do_call(): # 以 OpenAI SDK 为例streamFalse 时它内部负责连接 # 我们只关心总体耗时 return await llm_client.chat.completions.create( modelyour-model, messagesprompt, ) async with timeout_ctx(timeout, llm_inference): return await _do_call() async def call_tool_with_timeout(tool_name: str, args: dict, timeout: float 15.0): async def _do_call(): # 这里换成真实工具调用逻辑 return await tool_registry.invoke(tool_name, args) async with timeout_ctx(timeout, ftool_{tool_name}): return await _do_call()这个实现的核心在于timeout_ctx内部在超时发生时调用capture_agent_snapshot()。这一步看似多余实际上是你后续做状态清理和原因排查的唯一抓手。没有这个快照超时发生之后你根本不知道 Agent 执行到哪一步想恢复现场都不知道从哪恢复。3. 重试机制设计指数退避不是万能的3.1 重试要区分“可重试错误”和“不可重试错误”超时加上之后紧接着要处理重试。但重试有个大前提不是所有错误都能重试。如果错误是因为参数校验失败、业务规则拒绝、或者模型内容安全过滤导致的你重试 100 次也没用只会浪费资源和算力。我一般把错误先分类。可重试的包括网络连接超时、读超时、HTTP 5xx、限流429、以及大模型服务端返回的“临时性错误”。不可重试的包括HTTP 4xx尤其是 400、422、输入格式错误、工具依赖的业务数据不存在等。这个分类非常重要因为 Agent 场景和普通微服务不一样普通微服务重试失败大不了再报一次错但 Agent 重试意味着要重新整理上下文、重新进入推理状态机一旦对不可重试的错误也傻乎乎重试就会出现“同一个错误触发三次工具调用、三次失败、然后又往上下文里塞三份错误日志”的连锁反应。3.2 幂等设计为什么重试之前必须确认工具是幂等的重试最怕的还不是超时而是“明明第一次已经执行成功了但因为响应丢失你又执行了一遍”。比如一个“创建订单”的工具第一次调用成功生成了订单号但是网络延迟导致系统以为失败了重试时又创建了一个新订单。这不是状态清理能解决的问题这是幂等设计缺失。在设计工具接口时需要尽量做到两件事一是支持幂等键每一轮 Agent 的请求都带一个唯一的trace_id或request_id工具侧根据这个 ID 判断是否已经处理过如果处理过就直接返回第一次的结果不重复执行二是把“读操作”和“写操作”分开查询、检索类工具天然幂等重试无压力但扣减库存、发送短信、创建工单这类写操作必须设计成“先提交意图再确认执行”的模式或者用预扣 确认 回滚的流程。在重试层面我用了一个非常简单的策略重试时把同一个工具调用请求体原封不动地带着并显式标注“这是重试请求”。工具侧会优先检查业务幂等表表里命中就直接返回原有结果。这个策略虽然牺牲了一点性能但换来了整个系统最大的安全保障。3.3 重试代码实现指数退避 抖动重试的节奏也要讲究不能一失败就立刻重试更不能无脑指数退避到很大。我用的公式是base_delay * 2^attempt random_jitter。具体实现如下。import random import asyncio async def run_with_retry(agent_step, retries: int 3): delay 0.5 # 初始退避 0.5 秒 for attempt in range(retries): try: result await agent_step() return result except AgentTimeoutError: if attempt retries - 1: raise jitter random.uniform(0, delay) await asyncio.sleep(delay jitter) delay * 2 except AgentNonRetryableError: # 不可重试错误直接抛出去不要浪费重试次数 raise except AgentServiceUnavailableError: # 服务不可用说明整个 Agent 状态可能处于加载中 # 这种情况重试前需要重置状态机到安全节点 reset_agent_state_to_safe_node() if attempt retries - 1: raise jitter random.uniform(0, delay) await asyncio.sleep(delay jitter) delay * 2这里想强调的是reset_agent_state_to_safe_node()这个函数。我当时加这个函数的契机是服务端 503 时会清理一个内部缓存但清理之后 Agent 的上下文引用的是旧缓存里的对象导致重试时模型引用了不存在的会话信息。重新从“安全节点”加载状态之后才算真正干净的失败恢复。重试次数也不建议太多常规外部依赖重试 3 次如果 Agent 内部是多步执行建议对单步重试 2 次、对整个任务不再重试而是直接进入降级方案。降级方案可以是“返回模糊答案 提示稍后再问”也可以是“将这个任务转人工”。对用户体验来说一个诚实的失败提示远好过让用户看着转圈等他重试成功。4. 真正的坑状态清理4.1 超时/重试后Agent 的残留状态会导致什么这一节才是整篇文章的重点。前面所有超时和重试机制在状态清理失效时全部会反噬。我举几个真实的残留状态案例第一个案例上下文里堆积“半成品消息”。Agent 在调用工具前会生成一条类似“我正在为您查询订单请稍等”的中间消息。如果这个请求超时中断重试时新的执行流又生成一条同样的消息。如果清理机制不工作模型拿到的历史消息里会有两条甚至三条重复的中间提示。表面上无伤大雅但模型会认为系统出现了异常反而在生成回答时自我怀疑输出质量明显下降。第二个案例状态机走到了非法节点。在 LangGraph 里每一步执行都会返回一个AgentState里面记录了已经访问过的节点列表。如果第一次执行已经完成了“查询订单”节点并写入状态但没来得及进入“生成回答”节点就超时了重试时整个执行流从头开始那“查询订单”节点会被执行两次。如果你没有对外部副作用做幂等保护等于同一个订单被查询两次没大事但同一个“扣款”节点执行两次就是灾难。第三个案例最隐蔽工具调用栈的残留入参。我遇到过这样的情况一次超时发生在“发送邮件”工具调用后但响应没有写到状态里。重试时 Agent 认为这个工具还没调用于是再次调用。第二次调用成功生成了新邮件。两个邮件都发出去了用户收到了重复邮件。这个场景里问题既不是超时代码写得不对也不是重试策略不对而是状态清理根本没有意识到“第一次调用已经产生了副作用”。4.2 状态快照、恢复与回滚状态清理不是简单地把状态对象清空重来而是要在正确的时间点做三件事快照、恢复、回滚。快照就是我在超时上下文里提到的capture_agent_snapshot()。它要保存的内容包括当前上下文消息列表的长度和最后一条消息的 ID当前状态机节点和数据流转记录当前正在执行的工具名和入参一个单调递增的执行序号。有了这些信息当超时发生时你至少能回答“Agent 死在哪里、死了之后给谁留下了什么”。恢复有两种策略一种是从快照继续执行适合那种“前一步成功、后一步失败”的幂等场景另一种是回退到上一个安全检查点适合那种“中间步可能已经产生副作用”的场景。我刚上线时选择了“永远从检查点重新执行”结果吃了个大亏一个工具明明已经执行成功且副作用不可取消我从检查点重跑又执行了一遍。后来我改成“根据快照判断是否已经产生副作用如果产生了就跳过该工具直接进入下一节点”。4.3 清理工具调用栈和已执行副作用状态清理的核心动作是“对账”而不是“删除”。不要一上来就把工具调用栈清空而是先做一遍“哪些已经执行、哪些未执行、哪些可能部分执行”的审计。我设计了一个简单的执行记录表存到 Redis 里{ task_id: task_abc123, step_id: step_004, tool_name: payment.deduct, request_id: req_001, status: SUCCESS_OR_UNKNOWN, effect_applied: False, retry_count: 1, created_at: 1700000000 }每次工具调用前先写入一条PENDING记录成功后改成SUCCESS失败后改成FAILED如果超时导致结果未知就保持SUCCESS_OR_UNKNOWN。重试时如果发现某条SUCCESS_OR_UNKNOWN记录对应的工具不是幂等的就必须用另一个“补偿工具”去检查外部系统里到底有没有产生效果。比如“创建工单”工具超时了就先调“查询工单是否已创建”接口去确认确认已创建就直接复用结果确认未创建再重试。这个“先对账再重试”的模式是 Agent 状态清理和普通缓存清理之间最大的区别你的清理动作必须尊重外部系统的真实状态而不是只盯着内存里的对象。4.4 实现状态清理的代码骨架我给出一个精简但可以直接落地的状态清理逻辑。这里我用的是内存里的状态对象生产环境建议换成 Redis 或数据库但骨架不变。from enum import Enum from typing import Optional, Dict from dataclasses import dataclass, field class ToolStatus(str, Enum): PENDING pending SUCCESS success FAILED failed UNKNOWN unknown # 超时未确认 dataclass class ToolExecutionRecord: tool_name: str request_id: str status: ToolStatus ToolStatus.PENDING result: Optional[Dict] None effect_confirmed: bool False # 是否已对外部副作用做过确认 dataclass class AgentState: task_id: str context_messages: list field(default_factorylist) tool_records: Dict[str, ToolExecutionRecord] field(default_factorydict) current_node: str start visited_nodes: list field(default_factorylist) def cleanup_agent_state_for_retry(state: AgentState): 重试前最关键的状态清理。这一步做不好重试就是在放大错误。 for tool_name, record in state.tool_records.items(): if record.status is ToolStatus.UNKNOWN: confirm_result confirm_external_effect(record) if confirm_result.confirmed: record.status ToolStatus.SUCCESS record.effect_confirmed True else: record.status ToolStatus.FAILED # 对已经成功的工具保留结果防止重试时重复执行 # 对失败的如果不可重试就直接删掉记录 state.context_messages prune_half_thought_messages(state.context_messages) state.current_node find_last_safe_node(state.visited_nodes) state.visited_nodes state.visited_nodes[: state.current_node_index 1]这套逻辑的关键有两点一是confirm_external_effect用它来判断外部副作用状态二是prune_half_thought_messages把上下文里那些“我正在调用工具”的中途消息去掉只保留真实的用户输入和已完成工具的最终结果。我最早没有写confirm_external_effect导致重试场景下脏数据率没降下来后来补上之后异常恢复准确率有了非常明显的提升。5. 常见问题排查与避坑实录5.1 常见问题速查表在实际落地过程中我把典型问题和解决方案整理成了一个表团队新同学来了直接看这个表就能排查大部分故障。症状根因排查方向解决方案超时后重试回答内容明显重复上下文里堆积了“正在处理”之类的中间消息检查context_messages是否有多条未完成消息清理中间消息只保留已完成步骤的最终结果工具被重复执行出现重复订单或重复消息幂等键缺失或状态清理未做外部副作用确认查看 Redis 执行记录里同名工具的 status 是否从 UNKNOWN 变 SUCCESS补幂等键重试前调用查询接口确认副作用是否已生效重试后模型引用了一个不存在的会话对象状态机节点流转没有清理visited_nodes 指向了非法节点查看current_node和visited_nodes的对应关系重试前回退到上一个安全节点而不是从 start 重启外部接口 503 后重试一直失败状态对象引用了过期的缓存检查状态里是否持有了外部缓存引用在捕获服务不可用异常时清空相关缓存引用并重置状态单步重试成功但整体最终超时每步重试次数太多累计耗时超标查看链路日志里每步耗时减少重试次数或对整体任务加熔断直接降级重试过程中模型不断自我纠正回答失去重点上下文里塞入了大量错误类型的历史消息检查之前重试失败的错误消息是否被写入上下文写入上下文前过滤错误或者对同一个执行流做上下文隔离这个表里最值钱的不是前三行而是最后两行。“单步重试成功但整体最终超时”是我们上了完整机制之后才遇到的问题因为每步单独重试 3 次遇到连续两个工具都超时整体时间就彻底失控了。后来我把“单工具重试”和“整个 Agent 任务熔断”分开设置一旦整个任务已经消耗了总预算的 80%就不再发起新的工具重试直接走降级。5.2 实操心得我踩过的几个真实坑第一个坑给重试加完抖动之后忘了加“全局去重”。有一次我同时发起两个重试任务因为之前有个请求的 Agent 执行流被打断但没有标记为“已完成”调度器又把它捞起来重跑同一个任务出现两个并发副本。后来我在每轮任务开始前检查 Redis 里的任务锁锁没拿到就直接丢弃新请求避免同一task_id被并发执行。第二个坑清理状态时把“成功的工具结果”也一起清掉了。一开始我的清理逻辑很简单直接清空tool_records结果重试时 Agent 把第一个工具又调用了一遍。虽然不是写操作还好但浪费了几百毫秒而且可能造成数据不一致。正确做法是保留成功记录只清理“未完成的中间状态”和“可能产生副作用的未知状态”。第三个坑对错误类型分类时把“工具业务异常”也当成了可重试。有一次工具返回“订单不存在”我傻乎乎地重试了 3 次每次都是同样的错误还多产生了几条日志。后来我在工具异常里加了business_error标记凡是业务规则类错误直接结束本轮重试让 Agent 向用户解释错误原因。第四个坑值得单独说状态清理的顺序不能反。先确认外部副作用再清理上下文。我一开始反过来了先清了上下文再去做副作用对账结果对账函数需要读取上下文里的request_id而我已经把它删了。后来把这套流程改成了“先冻结现场 — 确认副作用 — 更新执行记录 — 最后裁剪上下文”的顺序稳定了很多。第五个坑是关于日志的超时发生时打印的现场信息一定要完整尤其是request_id、tool_name、step_index、上下文里最后一条消息的内容。我早期日志打得不够全每次一出问题就要靠猜后来把所有关键快照用结构化日志输出排查时间从“几小时”压缩到了“看一条日志就能定位”。5.3 最后再分享一个关于清理时机的小技巧状态清理不一定要等到“超时发生后”再做更好的做法是在“每步工具调用前”就预留一个清理点。具体来说Agent 每完成一个工具调用就执行一次“增量检查”把已经确认成功的记录从待清理列表中移除把还挂着 UNKNOWN 的记录单独标记。这样当真的发生超时时需要清理的数据量会非常小恢复速度也更快。我是在一次压测中验证了这个思路不预清理时超时恢复平均耗时 800 毫秒预清理之后恢复耗时降到 200 毫秒以内。原因很简单预清理让每次重试面对的脏数据窗口更窄而窗口越窄状态不一致的概率越低。如果你也在做 Agent 应用我真心建议不要只在网络层做文章。超时和重试只是入口状态清理才是那个决定你在生产环境活得好不好的关键点。先把状态模型画清楚再动手写超时时间这个顺序别搞反了。
