你的智能体读不懂的弃用通知

当你为人类开发人员弃用一个 API 时，你会为此举行一整套“仪式”。你提升版本号，在 OpenAPI 规范中添加 deprecated: true，发送 Sunset HTTP 响应头，向开发人员邮件列表发送邮件，发布变更日志，并给人们六个月的时间进行迁移。信号到达阅读它的开发人员，他们提交工单，并在旧路径消失之前更新他们的客户端。

现在，将同样的弃用通知指向一个智能体。调用你工具的模型不会阅读你的变更日志，它不会订阅你的邮件列表。它永远看不到 Sunset 响应头，除非你刻意将其放在模型会查看的地方，即便如此，它也没有可靠的习惯去据此行动。你精心编写的弃用通知落入了一个没有读者的信箱。智能体会一直调用工具的旧形式，直到该形式彻底消失，然后它就会失败——通常是静默失败，通常是在生产环境中，通常是在凌晨 2 点。

这就是为智能体而非人类构建工具时所存在的隐性不对称。我们在 API 演进的二十年里建立的每一项准则，都假设在弃用和迁移之间坐着一个人类。把人类拿掉，整个机制就会失效。

这并非理论上的风险。对生产环境中智能体事故的从业者调查总会得出同样一个令人不安的数据：很大一部分智能体故障——有些团队认为高达 60%——可以追溯到工具和 Schema 的更改，而不是模型本身。模型没问题，是工具变动了，但没有人告诉模型。

为什么模型真的无法阅读通知

在“智能体无法阅读弃用通知”这一现象之下，隐藏着两种独立的失败，需要将它们理清，因为它们需要不同的解决方案。

第一种是训练截止（training-cutoff）问题。模型的权重编码了截止到某个日期的世界快照。如果你在该日期之后弃用一个函数、重命名一个参数或更改字段的含义，模型对此没有事后知识。一项关于 LLM 针对不断演进的库生成代码的实证研究发现，模型会自信地发出已弃用的 API 调用，恰恰是因为这些弃用的版本在它们的训练数据中占主导地位。模型并不是在忽略你的通知——它从未包含过你的通知，而且它对旧的处理方式有着强烈的先验偏好。

第二种失败是上下文问题，这也是你真正能控制的问题。即使一个模型在上下文窗口中拥有完美的当前工具 Schema，它也没有跨会话的持久记忆，也没有本能像工程师对待编译器警告那样对待 deprecated 注解。你可以交给模型一个在元数据字段中显示 deprecated: true 的工具定义，除非该弃用信息出现在模型被迫考虑的地方——例如描述文本、工具结果、明确的指令——否则它会欣然继续调用该工具。模型从未将其转化为推理过程的标志，就是不存在的标志。

将这两者结合起来，你就得到了核心的设计约束：针对智能体的弃用必须通过“带内”（in-band）传输，即在模型实际处理的有效负载内部，而不是在人类会参考的响应头、文档或仪表盘中“带外”传输。 通知必须成为对话的一部分，否则它根本就不是通知。

工具 Schema 是公共 API 合约——请像对待合约一样对待它

这是一个能修复大部分损害的认知重构。你的智能体看到的接口——函数名称、描述性文字、输入的 JSON Schema 以及输出有效负载的形式——就是一个公共 API 合约。其中的每一个字都至关重要，因为每一个字都会制约模型的行为。

REST 和 gRPC 团队在过去十年中通过惨痛的教训学到了这一点：你永远不要在不更改字段名称或提升合约版本的情况下更改字段的含义。增加式的变更是安全的。添加一个新的端点、一个新的可选参数、一个新的响应字段——这些都不会破坏现有的调用者。删除一个字段、重命名一个参数、更改一个类型或悄悄更改字段的含义：这些都是破坏性变更，一旦接触就会引发爆炸。

加载中…