Agent 工具调用总失败？函数调用的调试清单

做 Agent 开发，工具调用失败是最常见的坑。我的调试清单：

1. Schema 要严格：参数类型、必填项、枚举值定义清楚，模型才能正确填；
2. 描述要写人话：工具描述是给模型看的文档，别写开发者黑话；
3. 错误要可读：工具返回的错误信息要能让模型理解并重试；
4. 加幂等：Agent 会重试，有副作用的工具一定要幂等；
5. 记日志：完整记录调用链，出问题才能复现。

经验上，60% 的失败是 schema 定义不清晰导致的，不是模型能力问题。

大家还遇到过什么坑？

Agent 评测还要考虑「轨迹质量」——只看任务成功不够，还要看过程是否合理。有时候任务成功了但中间走了歪路，换个输入就失败。

成本指标建议按任务类型分开统计，长任务和短任务的 token 消耗差异巨大，混在一起的平均值没有指导意义。