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

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

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

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

大家还遇到过什么坑？

再加一条：工具的输入校验要在服务端做，别只依赖模型的参数格式正确。模型偶尔会生成看起来对但语义错的参数。

幂等这条太重要了。我们有个发邮件的工具没做幂等，Agent 重试导致用户收到三封邮件，非常尴尬。有副作用的工具一律要做去重键。