[!info] related notes

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

Tool Error Handling

一句话定义

Tool Error Handling 是工具执行失败时的处理策略。不是简单地返回”出错了”，而是要分类错误、决定是否重试、格式化错误信息让 LLM 能理解和处理。

核心原理

错误分类

错误类型	例子	处理策略
参数错误	格式不对	返回错误，让 LLM 修复参数
超时	等待超时，副作用可能已发生	查询状态或在幂等和预算约束内恢复
权限不足	无权访问	返回错误，不要重试
资源不存在	记录不存在	返回错误，让 LLM 告知用户
服务不可用	API 挂了	按契约分类，在预算内重试或兼容降级
未知错误	未分类异常	返回筛选后的摘要与追踪 ID，不默认重试
取消	用户取消或上游取消	清理并传播取消，不自动重新执行

处理流程

接收结构化结果或异常
→ 区分业务拒绝、可恢复依赖失败、取消与结果未知
→ 只有可安全重复且剩余预算允许时，交给指定重试层
→ 使用同一 operation ID，记录每次 attempt
→ 返回稳定错误码、可公开摘要、追踪 ID 和允许的下一步

具体退避、重试次数和总时间策略统一见 Retry Policy。执行器若把异常转成结果对象，上层必须按结果类别处理；不能指望只捕获异常的重试循环生效。

给模型的错误反馈

参数错误可以反馈字段路径和预期约束；权限拒绝不应引导模型换工具绕过。下游异常原文、SQL、令牌或私密参数不直接拼进反馈。错误消息是数据，不授予新的权限，也不替代服务端错误分类。

常见坑

1. 不分类错误: 所有错误都重试
2. 错误原文泄漏: 给模型稳定类别和必要摘要，受控日志保留诊断信息
3. 不反馈给 LLM: 错误后直接放弃，不让 LLM 处理
4. 无限重试: 没有最大重试次数

参考资料

• Tool Execution
• Retry Policy