AgentFunction Calling超时可靠性工程化
工具调用超时治理：时间预算、降级与兜底，让 Agent 不中断
工具调用的超时不是“偶发错误”，而是系统设计问题：你必须把时间当作预算来分配，把失败当作一类可建模的结果。本文从 time budget、超时分级、重试与幂等、并行与取消、fallback 策略、以及如何把超时写进评测与可观测，给出一套能在生产跑起来的工具调用治理方案。
2026年3月4日
Synthly 团队
预计阅读 15 分钟
📷 Photo by panumas nikhomkhai via Pexels
0. 先说结论：超时治理是“预算 + 协议 + 控制面”
把工具超时当成异常处理，会让你不断补丁； 把工具超时当成系统设计，才能可控。
你需要三件事：
- 预算：端到端的 time budget 如何分配
- 协议：工具返回的成功/失败/部分成功如何表达
- 控制面：重试、并行、取消、熔断、降级如何统一调度
一、把端到端时间拆成预算：每一步都要“可花、可省、可停”
设端到端预算为 $T$（例如 6s），不要把它全部给一个工具。
常见分配方式：
- 规划与路由：0.5s
- 检索/数据库：2s
- 外部 API：2s
- 合成与校验：1.5s
关键点：
- 每个工具调用都必须带 timeout
- 所有重试都必须从同一个预算池里扣
- 一旦预算不足，必须触发 fallback
二、超时要分级：软超时 vs 硬超时
不要只有一个 deadline。
- 软超时（soft timeout）：到点了就准备降级，但允许“如果结果已经快来了”再等一点
- 硬超时（hard timeout）：到点必须取消，释放资源
工程上建议：
- soft timeout 用于触发“备选方案并行启动”
- hard timeout 用于明确取消（尤其是昂贵工具）
三、重试的前提：幂等 + 去重 + 可观测
重试策略常见误区：
- 同一个请求在多个层级各重试一次 → 直接 retry storm
- 不做幂等键 → 重试导致重复写入/重复扣费
落地建议：
- 幂等键（idempotency key）
- 由用户请求 ID + 工具名 + 关键参数 hash 组成
- 去重（dedupe）
- 相同 key 的并发请求合并成一次工具调用
- 退避（backoff）
- 指数退避 + 抖动（jitter）
- 预算约束
- 重试次数不是常量，是预算函数：$retries = f(remaining_budget)$
四、并行与取消：让“慢”不再拖垮全局
在 Agent 场景里，很多工具调用是可并行的：
- 主数据源 + 备数据源
- 检索 + 用户画像
- 结构化校验 + 补全
策略：
- 先并行：减少平均延迟
- 后取消：一旦主结果足够好，立刻取消其他调用
取消不是可选项：
- 不取消会让你的系统在高并发下被尾延迟拖死
五、Fallback 不是“随便编”：要有明确层级
建议把 fallback 写成链路（从强到弱）：
- 主工具（最准确）
- 备工具（更稳/更快）
- 缓存（可能旧，但稳定）
- 规则/模板回答（可解释、可控）
- 向用户追问/提示稍后重试
关键是：每一级都要声明信息缺口。
这跟结构化输出的“合同”是同一件事：
六、把超时写进评测：否则你会只优化“正确率”
如果你的评测只看 answer correctness，你会自然地做出：
- 更长 prompt
- 更多工具调用
- 更长超时
最后线上体验变差。
建议把以下指标纳入评测：
- 工具超时率（按工具分桶）
- fallback 触发率（按链路层级）
- 端到端 p95/p99
- 单请求成本（token + 工具费用）
评测体系搭建可参考：
七、落地清单：一周内能做完的超时治理 MVP
- 为每个工具调用定义
timeoutMs - 统一
timeBudget上下文（贯穿整个 Agent run） - 工具返回统一结果类型：success / partial / timeout / error
- 只在“幂等 + 有预算”时允许重试
- 支持并行调用 + 取消
- 明确 fallback 链路，并记录触发原因
- 加上基础指标：timeout rate、fallback rate、p95
做到这些，Agent 就不会因为一个工具慢了 1 秒而“整段崩掉”。