工具持续超时时应该如何处理？

核心回答

工具持续超时，我会先停止无效重复调用，确认超时发生在哪、工具是否已经执行，以及它是不是任务必需步骤，再决定重试、替代、异步等待或结束任务。

短暂网络问题可以在剩余预算内限次重试，配合退避、抖动和并发限制；长期不可用则熔断或暂时摘除。辅助工具可以降级并说明缺失，关键证据或必需业务步骤不能直接跳过，更不能让模型编造结果。涉及下单等写操作，超时不代表没有成功，优先查执行状态，重试要沿用同一业务意图的幂等键。

如果工具本来就需要很久，应改成提交任务、返回任务标识、查询或接收结果的流程。这样能释放同步等待资源，但仍需遵守任务总时限和取消规则，不能用“异步”掩盖任务没有完成。

展开说明

1. 先区分故障与正常慢任务

沿一次工具调用检查连接、服务排队、实际执行和响应传输的耗时，核对工具参数、请求范围、下游负载与最近版本变化。也要检查超时是否发生在 Agent 外层、工具客户端或业务服务，避免内层还在运行、外层已经重复发起。

返回给调度器的状态应区分超时、执行中、明确失败、结果未知和正常空数据，并携带调用或任务标识、是否有副作用及可采取的下一步。空数据可能是有效业务结果，超时也不能简单包装成“没有找到”。结构化反馈有助于模型换策略，但重试预算和执行状态应由程序控制。

2. 重试要有收益与边界

只有错误可能恢复、操作允许重放且预算足够时才重试。按工具契约判断可重试错误，设置最大尝试、单次超时和任务总 deadline；每次等待与重试都要占用剩余预算。SDK、工具执行器和 Agent 不宜各自独立重试同一请求，避免层层放大。

持续失败时停止新增尝试，并对故障依赖限制并发或熔断，恢复后用少量探测验证。调大超时只适合原阈值不合理且任务允许等待的情况，不能修复下游死锁、过载或错误参数。

有外部写入时，先按业务请求号查询是否完成；确认未执行后才安全重试，结果未知时进入核对或人工处理。换一个支付或下单工具，也可能重复产生业务效果，不能把换工具当作绕开幂等问题。

3. 根据工具职责决定能否降级

例如一份分析报告同时需要销售数据和可选的行业新闻：新闻工具超时，可以交付已有分析并说明背景资料暂缺；销售数据是结论依据，取不到就应暂停相关结论、给出部分结果或结束这部分任务。

替代工具必须具备相应数据范围、时效、权限和结果语义，不能只因名称相似就替换。使用缓存也要验证版本、权限和新鲜度，并向用户说明必要限制。跳过自家工具同样要看它承担的业务职责，工具归属不改变依赖关系。

4. 工具要 100 秒，Agent 只允许 50 秒怎么办？

先明确 50 秒是什么限制。如果只是一次 HTTP 请求的等待时间，而业务允许后台任务继续，可先返回“已受理”和 task_id，让 Worker 执行，前端查询进度或订阅事件，完成后恢复对应任务。任务状态应可持久查询，不能只把工作放在可能随进程退出而丢失的后台变量中。

如果 50 秒是业务要求的完成期限，就不能承诺 100 秒后仍算按时完成；应优化任务、缩小范围、选择合适替代或明确失败。进度和心跳用于告知存活与推进，不应自动延长绝对 deadline。

取消时尽可能取消下游任务；不支持取消时，记录仍可能运行，并阻止迟到结果覆盖已经更新的任务状态。结果回调需要核对任务、版本和处理状态，重复事件不能重复推进；已经发生的外部写入则另行核对或补偿。

5. 处理之后怎样验证？

对照工具与任务的成功率、平均和 P95 耗时、超时位置、尝试次数、排队与恢复情况，同时检查是否出现重复副作用。验证应覆盖服务慢、持续不可用、响应丢失但业务已成功、取消后迟到及重复回调等场景。

交付时说明已完成内容、仍缺哪项以及是否还有后台任务。不能把“已经停止等待”写成“工具已停止执行”，也不能把缺少关键依据的答案标为完整成功。

常见追问

直接把超时时间调大不行吗？

若工具正常耗时超过原阈值，且任务预算允许，可以调整。若原因是排队、死锁或持续故障，调大只会占用更多资源；应先定位耗时与超时层次。

工具已经熔断，模型还在调用怎么办？

执行器应在进入工具前检查可用性和预算，返回明确的不可用状态；可以更新当前可选能力并提供替代路径。不能仅在提示词里写“不要再调用”，也不应把同样失败无限追加到循环中。

重试次数限制等于超时控制吗？

不等于。次数控制防止重复行动，超时限制一次或整项任务能等多久；取消、幂等和降级分别处理资源、外部效果和业务可用性，需要配合设计。

对应教程

参考资料