Tool Calling 失败分类：不要把所有失败都归因于模型不够聪明

当 Agent 调用工具失败时，“模型幻觉了”是最省事也最无用的结论。它把完全不同的故障混在一起：模型选错工具、schema 允许了错误参数、用户没有权限、下游 API 超时、写操作需要确认但系统没有拦截。没有统一分类，团队只能不断换 prompt，无法判断真正应该修的是模型、工具还是业务流程。

六类必须区分的失败

第一类是工具选择失败：本应调用查询工具却调用写工具，或者调用了过期工具。第二类是参数失败：工具正确，但资源 ID、枚举值、时间范围或分页参数错误。第三类是授权失败：请求本来不该被执行，系统是否明确拒绝比“最终有没有结果”更重要。

第四类是依赖失败，包括限流、超时、连接错误和第三方返回异常。第五类是状态失败，例如创建请求已成功但响应丢失，Agent 又重复创建。第六类是交互失败：用户确认缺失、澄清问题没有被问出，或者 Agent 在信息不足时仍然做了不可逆操作。

这六类可以进一步标记责任边界。参数错误不一定是模型问题，可能是 schema 把日期格式描述得不清楚；授权拒绝也不必算失败，如果系统正确阻止了越权行为。指标必须区分“预期拒绝”和“意外拒绝”。

为一次失败保留最小证据

每次工具调用至少记录工具名、候选工具集合、输入是否通过 schema、授权结果、下游状态码、重试次数、幂等键状态和最终用户可见结果。不要记录完整敏感参数，但要记录足以重放脱敏场景的结构化摘要。

例如，参数失败可记录 missing_required_field、invalid_enum 或 resource_not_in_context；依赖失败可记录 dependency_timeout 和耗时阶段。稳定 code 让离线评测和线上监控使用同一语言，而不是依赖日志里的自然语言错误信息。

用分类驱动修复，而不是只看总成功率

假设总工具调用成功率从 88% 提升到 91%，如果新增成功全部来自低风险查询，而支付写入仍有 4% 重复执行，系统实际风险没有降低。应该按工具风险、失败类别和用户影响设优先级。高风险写操作的状态失败可能只占千分之一，却应先于低风险摘要的措辞问题解决。

每次修复也要写入评测集。改进工具描述后，重跑选择失败样本；增加幂等键后，注入响应丢失并确认状态失败下降；调整权限后，验证越权请求仍被拒绝。这样分类不是事故报告模板，而是持续降低故障率的闭环。

让产品也看得懂

对非工程角色，展示“Agent 需要人工接管的任务比例”“被正确拒绝的高风险请求数”“平均恢复时间”等业务语言。不要只报告模型分数。用户关心的是事情是否办成、是否误操作、失败时是否能知道下一步，而不是某个 benchmark 的抽象提升。

当失败被稳定分类后，团队就不必靠猜测优化 Agent。模型、工具、策略和依赖服务各自都有可验证的改进目标，投入才会落在真正影响可靠性的地方。

从分类到可执行的值班流程

失败 code 需要有明确的归属团队和第一响应动作。invalid_enum 可能归工具 contract 负责人，dependency_timeout 归平台或外部依赖负责人，confirmation_missing 归产品策略负责人。没有归属的分类只会让报表变漂亮，值班人员仍然不知道应该升级给谁。

对每类失败定义一个判断问题。例如状态失败先问“下游是否已经产生副作用”，授权失败先问“拒绝是否符合策略”，选择失败先问“候选工具描述是否存在重叠”。这些问题让故障处理从翻日志变成固定排查路径，也方便把重复问题聚合成一个 backlog，而不是每次开新工单。

每周审查分类分布的变化。某个模型升级后参数失败突然上升，可能是输出格式变化；某次工具发布后资源不存在错误上升，可能是 ID 解析或上下文注入出现回归。分类趋势比一次单独报错更早揭示系统性问题。

延伸阅读

• MCP 工具 Schema 设计
• 自动化 Agent 评测
• MCP 工具超时、重试与幂等