一位后端工程师重命名了一个字段。user_id 变成了 customer_id，因为团队终于在所有服务中统一了 “customer” 这个术语。他们还增加了一个参数 region，因为计费系统现在需要它。这次变更通过一个包含两个批准的普通拉取请求（pull request）发布。每一个调用该端点的下游服务都在同一个发布版本中进行了更新。集成测试全部通过。按照后端团队衡量的一切标准，这是一次常规且执行良好的 API 变更。
一周后，支持工单开始增加。负责下单的智能体偶尔会在没有关联客户的情况下下单，或者将其关联到错误的区域。没有人改动过智能体。没有人改动过提示词（prompt）。模型的版本与上个月完全相同。然而，智能体现在却出现了一种以前从未有过的错误。
原因既不是模型中的 Bug，也不是后端中的 Bug。而是工具 Schema（tool schema）有两个消费者，但在审查变更时，只有其中一个在场。
你从工具目录中注销了 lookup_account_v1，换上了 lookup_account_v2，并修改了系统提示词中的一个段落来指向新名称。测试通过了。三天后，支持工单开始提到助手“一直尝试调用不存在的东西”，或者——更令人不安的是——它用自信、看似合理的数字回答客户问题，却根本没有查询数据库。弃用并没有在通信层失败，它在规划器（planner）中失败了。
这是将工具弃用视为语法变更与将其视为行为迁移之间的差距。智能体不仅是在注册表中拥有你的函数；它还拥有数月的计划、多步配方（recipes）以及通过该函数作为检查点的 few-shot 示例。撤掉它更像是停用下游服务非正式硬编码的内部 API——只不过下游服务是一个你无法通过 grep 搜索其习惯的模型，而且当它偏好的工具消失时，它的兜底方案是编造一个。
工单上写着 “模型幻觉了一个用户 ID”。分拣标签是 model-quality。修复方案是在系统提示词中多加一句话。六周后，另一个工具开始幻觉日期格式，循环再次开启。一年后，提示词已经演变成一段针对整个后端的 4,000 token 的道歉信，而团队也坚信该模型在工具参数方面就是不可靠的。
模型并非不可靠。模型是一个合约一致性机器，它在阅读你提供给它的合约 —— 而你提供的合约一直在悄悄偏离线路另一端的合约。大多数生产环境中的 “参数幻觉” 并不是模型故障。它们是你的工具描述在默默失败的集成测试，之所以表现为模型输出，是因为这是技术栈中唯一能看到分歧的地方。
你智能体代码库中最昂贵的一行，就是从现有的 OpenAPI 规范中自动生成工具 Schema（tool schemas）的那一行。这看起来是一个利落的工程选择——单一事实来源、无重复、每次 API 变更时自动同步。但这也是为什么你的智能体在应该选择 searchUsersV3 时却选择了 searchUsersV2，因为你的规范示例中写了 limit=20 于是它就填了 20，并且悄无声息地丢掉了 tenant_id，因为它被埋在第七个参数槽位里。
单元测试中不会显现任何这类迹象。Schema 是有效的。端点（endpoint）是存在的。智能体的调用是格式正确的 JSON。然而，模型每次都会用错工具，且是以你的 QA 流水线永远察觉不到的方式，因为 QA 测试的是 API，而不是智能体对 API 的理解。
这个 Bug 是观念性的。OpenAPI 的设计初衷是向编写 SDK 代码的人类描述 API；而工具 Schema 则是作为 Prompt 的一部分，在每次调用时由 LLM 读取。将它们视为同一种产物，就好比根据数据库列名自动生成面向用户的文案一样，犯了同类型的错误。
工具描述不是文档。它是模型在每一轮对话中都会读取的 prompt，用于决定该工具是否触发以及如何触发。你不是在为对接该工具的开发者编写内容——开发者已经在 PR 中看到了 schema、类型和示例。你是在为一个从未见过这个代码库的随机读者编写内容，它在同一个上下文窗口中还拿着另外二十个工具描述，并且必须在下一次前向传播中选出一个。
大多数团队并没有意识到这一点。他们把 OpenAPI 摘要粘贴到 description 字段中，把 JSON Schema 贴在下面，然后就发布了。结果，agent 调用工具的次数过少，或者自信地调用了错误的邻近工具，又或者用了任何读过 schema 的人类都会觉得“显而易见”是错误的参数来调用正确的工具。团队责备模型，但模型读取的正是一字不差的你写的内容。
生产环境 Agent 中最危险的 Bug 不是那些会抛错的 Bug。而是这种：工具描述写着 returns user_id，但后端在两个 Sprint 前悄悄开始返回 account_id，而模型在后续推理中仍在愉快地凭空捏造 user_id —— 因为清单（manifest）是这么写的，Few-shot 历史加强了这一点，而且循环中没有任何环节去获取真实情况（ground truth）。
这就是清单漂移（manifest drift）：工具描述所声称的内容与端点实际行为之间缓慢且无声的分歧。它很少产生堆栈跟踪（stack traces）。它产生的是带有干净审计线索的错误决策 —— 这是 Agent 系统中最糟糕的一类 Bug。
你的智能体中杠杆率最高的 prompt 并不在你的系统 prompt（system prompt）中。它是你六个月前在某个工具定义下写的那句描述，它随实现代码一起提交，之后就再也没动过。模型在每一轮对话中都会读取它，以此决定是否调用该工具、绑定哪些参数，以及当响应不符合预期时如何恢复。工程师将其视为面向人类的 API 文档，而模型则将其视为一个 prompt。
这两种视角之间的鸿沟，正是最糟糕的工具使用（tool-use）类 bug 的温床：模型调用了正确的函数名，传入了正确的参数，发出了正确的 API 调用 —— 但原因却是错的，场景是错的，或者它放着旁边更合适的工具不用。没有任何异常抛出。你的评估套件依然通过。这种退化（regression）只会表现为衡量智能体是否真正起到帮助的指标在缓慢下降。
大多数工程师对待智能体工具的方式与编写 REST 接口或库函数如出一辙：清晰地暴露功能、记录参数、处理错误。这对人类来说是正确的直觉。但对于 AI 智能体（AI Agents）来说，这完全是错误的。
智能体使用的工具是以非确定性的方式被消耗的，它被逐个 Token 解析，并由一个对上周二使用过什么工具没有持久记忆的模型来选择。你编写的工具 Schema 并不是文档——它是运行时提示词（runtime prompt），在推理时被注入到模型的上下文中，塑造着智能体做出的每一个决策。每一个字段名称、每一段描述、每一个返回值的结构都是一个设计决策，具有可衡量的性能影响。这就是智能体-计算机接口（ACI，Agent-Computer Interface），它值得你像对待任何关键的面向用户的界面一样投入工程精力。
LLM 在生产环境中函数调用失败最令人惊讶的地方在于它们的来源。不是幻觉推理。也不是模型选错了工具。代理不稳定的首要原因在于参数构造：错误的类型、缺少必填字段、格式错误的 JSON、幻觉出的额外字段。模型本身没问题。你的 schema 才是问题所在。
这是个好消息，因为 schema 修复成本很低。
我是 Tian Pan，一名工程师型创始人，专注于智能体工程——构建自主 AI 系统并扩展工程团队。我撰写关于系统设计、技术领导力和 AI 智能体实战的实用指南。曾在 Uber、Brex 和 IoTeX 担任早期工程师。
