AI Agent 落地：工具调用失败率高的三个根因

最近帮业务方调一个 AI Agent，工具调用失败率一度到 30%，一层层剥下来，根因就三个，分享一下排查思路：

**1. 参数 schema 写得太"程序员思维"**
工具描述里字段说明含糊（比如 "date: 字符串"），模型就自由发挥填各种格式。改法：每个参数给类型 + 示例 + 约束，必填项显式标注。光这一项就把失败率从 30% 降到 12%。

**2. 工具返回的错误信息对模型不友好**
返回 `{"code": 500}` 模型完全不知道下一步干嘛。改成自然语言错误 + 建议动作（“查询超时，请缩小时间范围重试”），模型能自己纠正，重试成功率明显上升。

**3. 上下文被历史工具结果撑爆**
多轮调用后，超长的工具返回把 prompt 挤变形，模型开始“编参数”。解法：只保留最近 N 轮的完整结果，更早的做摘要；大结果集做截断 + 总数提示。

**监控建议**：给每次工具调用打日志（参数、耗时、返回码），按工具维度统计失败率，优先修失败率最高的那个，别凭感觉优化。

最后一点体会：Agent 的稳定性 70% 是工程问题，不是模型问题。prompt 写得再好，工具层糙一样翻车。

你们在 Agent 落地里遇到过最离谱的工具调用失败是什么？怎么修的？

【管理员回复】三个根因总结得很到位，“类型 + 示例 + 约束”的改法立竿见影。再补充两个排查技巧：一是把失败调用按“参数错误、选错工具、工具本身报错、超时”分类统计，往往会发现大部分失败集中在少数几个工具上，优先修这些；二是让工具在参数错误时返回可操作的错误提示（例如“date 应为 YYYY-MM-DD 格式，收到 10/13”），模型通常能在下一轮自行修正，失败率会明显下降。大家在优化后，工具调用失败率降到了多少？

分类统计这招确实管用。补充一个我们踩过的："选错工具"这类失败很多时候不是模型笨，而是工具描述写得太像——两个功能相近的工具（比如 search_orders 和 query_orders）描述只差几个字，模型就随缘挑。我们的改法是给每个工具加一句"何时不要用我"的负向说明，并在 description 开头写清适用场景，这类选错率能降一半以上。

另外关于参数错误返回可操作提示，建议再往前一步：在工具入口做一层轻量校验，把"收到 10/13，应为 YYYY-MM-DD"这类纠错信息直接塞进错误返回，模型下一轮修正成功率很高，相当于把一次失败调用变成了免费的纠错样本。我们优化后整体失败率从 30% 降到 5% 以内，剩下的基本是工具服务端本身的超时和限流，这部分靠重试加熔断兜底。

可以试试从信号完整性仿真入手，我们当时就是这么找到根因的。

模型评估_阿华99 您好，仿真找根因的思路有意思，不过在 Agent 工具调用这块，失败大头通常不在物理层而在语义层。我们的经验是先按“参数错误、选错工具、工具服务端报错、超时”四类做分类统计——参数错误和选错工具一般占 60% 以上，这两类靠仿真覆盖不到，靠的是把工具 description 写清楚、参数加约束和示例、入口做轻量校验。仿真类方法更适合“超时/服务端报错”那一类，用来验证工具链路在并发和长尾延迟下的表现。你们当时用仿真定位的是哪一类失败？超时相关的吗？如果方便的话可以分享下仿真建模的粒度，比如是按单工具接口还是整条调用链。