Agent 工具调用超时与重试：可落地的模式

Wed, 21 Oct 2026 18:19:00 +0800

超时重试不是「失败了再喊一次」，而是先分清错误类型，再与幂等键一起设计。 可重试的通常是网络抖动与限流；不可盲目重试的是业务拒绝、校验失败与已成功但响应丢失的不确定性——后者更依赖幂等。

决策顺序

为每次工具调用设明确超时。
对超时与 5xx / 限流：有限次退避重试。
对 4xx 业务错误：不要空转重试，返回给规划层改参数。
所有具有副作用的调用带幂等键（见相关幂等文）。
记录每次尝试的错误码与耗时，便于调参。

示意伪代码（虚构示意）

for attempt in 1..N:
 result = call_tool(args, idempotency_key=K, timeout=T)
 if success: return result
 if not retryable(error): raise
 sleep(backoff(attempt))
escalate_to_human_or_planner()

提示词（设计评审用）

请审查我的工具重试策略：哪些错误可重试、最大次数、退避、是否与幂等键绑定、超时如何设置。
指出可能导致重复副作用的路径。不要编造基准数字。
【策略描述】<<<>>>

实践提醒

把重试参数做成可配置项，并在仪表盘统计重试率与最终失败率。若某工具重试率突然升高，先查下游健康再调大次数。人工升级路径要在提示或工作流里写清，避免智能体空转耗尽配额。

Agent 工具超时处理：截止、取消与用户可见降级

Mon, 19 Oct 2026 18:08:00 +0800

超时策略是产品体验，也是正确性。 工具调用卡住时，Agent 若只会「再试一次」，可能把支付、发信等副作用打成双份。

分层设置

层	建议
单次工具 HTTP	明确 timeout + 可取消
Agent 步级	单步墙钟上限
整任务	全局预算，到点总结已得结果

处理剧本

可安全重试（只读查询）：有限次退避，参见重试退避清单。
有副作用：超时后先查幂等键/状态，勿盲重放；见幂等工具调用。
对用户：说清「哪一步超时、已保留什么、可选改走手工」。

提示/策略片段

若工具在 {{N}}s 内未返回：
- 停止等待该调用
- 记录 tool_name、timeout、是否已知副作用
- 若只读：可按退避重试至多 {{K}} 次
- 若写操作：改为 status_check 工具，禁止重复 submit
- 向用户输出降级说明，不要假装成功

与结果截断

超时和「返回过长被截断」不同，后者见工具结果截断。

超时 on AI 观察