Agent 失败的真实原因：工具调用周围的工程问题

能够选对函数的 Agent 不再是难点。主流模型都能可靠地做到这一点。真正决定你的 Agent 能否在生产环境中存活下来的，是围绕调用展开的一切：函数的描述方式、模型发起请求到结果返回之间发生了什么、谁有权批准，以及模型在失败时看到了什么。

以下是失败真正集中的地方。

The Schema Is The Prompt

函数定义不是配置。它们是模型在每一轮都会读取的指令，会和上下文中的其余内容争夺注意力。

模糊的参数名和缺失的枚举值产生错误参数的频率，远比模型能力不足要高的多。date 就像抛硬币。start_date_iso8601 则不会。一个接受任意值的 status 字符串会被创造性地赋予各种值，而只有四个允许值的枚举则不会出现这种情况。

写每个参数描述的方式，就好比你为明天入职的新人写文档一样。只标记真正必需的内容，在集合封闭的地方使用枚举。大多数"模型持续调用错误工具"的 bug，本质上都是 Schema bug 穿上了马甲。

The Execution Lifecycle Is Yours, Not The Model's

模型返回一个结构化请求。它并不运行任何东西。你的代码决定是否执行、使用什么凭证、在什么超时条件下执行，以及返回什么结果。

这个间隙是整个系统中最有价值的地方，验证、速率限制、幂等性 key 和日志都属于这里。跳过这一步，就是你的 Agent 因为重试看起来像新请求而重复扣款的原因。

把每次工具调用当作一笔交易，有你控制的开始、有你控制的中段、有你记录的结束。

Write Errors For The Model To Read

原始的栈跟踪对模型没有任何可操作的信息，所以它做了唯一能做的事——猜测。

比较 "TypeError: cannot read property of undefined" 和 "invalid date format, expected YYYY-MM-DD, received 03/14/26"。后者会在下一轮产生正确的重试。"rate limited, retry after 30 seconds" 也比赤裸的 429 有用得多。

能够良好恢复的 Agent，几乎都是那些故意编写错误字符串的 Agent。这是性价比最高的可靠性工作，却也是团队最常跳过的部分。

Permissions Decide How Far You Can Let It Go

只读工具可以无人值守地整天运行。任何涉及花钱、发邮件或删除数据的操作，都需要一个作用域边界，通常还需要人工确认步骤。

一个有用的模式：将读和写拆分为独立的工具，而不是一个带 mode 参数的工具。mode 标志是模型选择的一个值。两个工具是你授予的权限——要么授予了，要么没有。

为每个工具提前决定这一点，日后才能在不需要重写整个系统的情况下扩大自主权。

Tool calling is the capability that turns a conversational model into a functional agent. But the capability is not the product. The schemas, the execution lifecycle, the permission model, and the error strings are the product, and they are all things you write rather than things the model provides.

If you want the longer version, this complete guide to AI tool calling covers function definitions and schemas, the execution lifecycle, calling patterns, security and permissions, error handling, and cost and performance in one place.

工具调用是将对话模型转变为功能性 Agent 的能力。但能力不等于产品。Schema、执行生命周期、权限模型和错误字符串才是产品，它们都是需要你来编写的东西，而不是模型提供的。

如果你想要更完整的版本，这份 AI 工具调用完整指南涵盖了函数定义和 Schema、执行生命周期、调用模式、安全和权限、错误处理以及成本和性能，一站式全覆盖。