[!info] related notes

• 所属 MOC: Tool Calling Engineering MOC
• 相关: Tool Execution, Timeout Control

Tool Timeout

一句话定义

Tool Timeout 是工具执行的最大允许时间。数据库查询卡住、API 无响应、代码死循环——没有超时控制，一个工具就能阻塞整个 Agent。

核心原理

超时预算

按工具耗时和上游剩余预算设置超时，而不是为每次重试重新给完整时长：

run 剩余 8 秒
工具单次上限 30 秒
→ 本次最多使用 8 秒以内的预算，并预留返回与清理时间

搜索、数据库、外部 API 与代码执行应分别设置下游超时和资源限制。端到端传播规则见 Timeout Control。

asyncio 的边界

Tool Executor中的 wait_for 示例只适用于协作式异步 handler：

• 超时会请求取消并等待被调用协程处理取消；清理耗时会让实际返回晚于名义超时。
• handler 吞掉取消或阻塞事件循环时，不保证按时返回。
• 线程中的同步工作不会因取消等待而停止；外部 API 也可能已经生效。
• 硬性资源隔离需要 worker/进程及其终止协议，不能靠协程计时器替代。

超时后的处理

用结构化错误类别区分 deadline、下游超时和用户取消，不通过 error 字符串里是否含 timeout 判断。

读取可按剩余预算选择重试或兼容降级；写入超时先查询状态或按 幂等协议恢复。换一个工具重做同一写操作，同样可能造成重复副作用。取消不等于普通可重试错误。

常见坑

1. 不做超时: 工具卡死阻塞 Agent
2. 超时太短: 正常执行被误杀
3. 超时后不清理: 底层资源没有释放
4. 所有工具同一超时: 不同工具应该有不同超时

参考资料

• Timeout Control
• Tool Execution