你的 Agent 悄然适应了的那次工具版本升级

一个下游搜索服务在周二下午发布了 v2.3.2 版本。发布说明提到重命名了一个状态字段，新增了一个可为空的 confidence 值，并重新排列了结果包中的数组。CHANGELOG 中没有任何内容被标记为破坏性变更。提供商自家的客户端库通过一个小版本更新消化了这些变化。你团队的 HTTP 集成通常会在一小时内记录下反序列化错误。但你的智能体——那个通过该搜索工具路由客户问题的智能体——并没有报错。它继续回答。问题依然得到解决。仪表盘依然是一片绿色。

六周后，有人注意到“缺货”回复在查询中的比例从 2% 攀升到了 11%。根本原因是 v2.3.2 的升级。重命名后的状态字符串从 in_stock 变为 available，而智能体——作为一个对文本进行灵活推理而非严格遵守模式（schema）的客户端——将旧令牌（token）的缺失解读为“无货”，然后将这一发现组织成乐于助人、语气自信但内容错误的客户消息。契约回归在消费者端被吸收了，而那里没有任何测试套件在监控。

这是传统的 API 规范（hygiene）从未被设计用来捕捉的故障模式。严格的客户端会大声报错。智能体则静默失效。你越是将智能体当作普通的 HTTP 消费者对待，这类 Bug 隐藏在看似正常的指标中的时间就越长。

软类型既是智能体的超能力，也是它的软肋

团队之所以选择智能体而非硬编码集成，核心原因在于智能体能容忍变化。字段被重新排序、键名被重命名、出现新的可选值——构建在固定反序列化器之上的确定性客户端会抛出异常。而智能体将响应视为文本读取，识别出语义上接近它所期望的内容，并生成通常仍然有用的输出。

这种容忍度正是你推销给产品团队的功能。但它也是导致契约偏移（contract drift）从原本设有警报的网络边界，转移到你毫无感知的模型推理内部的原因。400 响应会触发传呼报警。而一个细微翻译错误的字段只会导致回答质量悄然下降，这需要数周才能浮出水面，数月才能追溯原因。

这种不对称性至关重要，因为传统的 API 版本管理——语义化版本（semver）、弃用窗口、消费者-提供商边界的契约测试——都是基于“消费者是脆弱的”这一假设构建的。脆弱性就是信号。消费者失败，提供商收到反馈，版本被锁定，迁移被排期。当消费者是 LLM 时，信号消失了。模型将每一次微小的变动都转化为优雅的适应，而你只能通过滞后于回归数周的下游业务指标来了解偏移。

最近的行业数据印证了这一点。一项 2026 年关于智能体 API 集成的调查发现，41% 的 API 在契约捕获后的 30 天内发生了形状偏移，63% 在 90 天内发生偏移。如果你的智能体调用了多个工具，问题就不再是静默偏移是否正在发生，而是你是否有任何手段能观测到它。

你的智能体会吸收的三种偏移形式

并非所有的契约变更都是平等的。偏移模式可以分为三类，按软类型消费者捕捉它们的难度排序。

第一种是参数重命名 (parameter rename)。提供商将 query 改为 search_query。严格的客户端在序列化时就会失败。你的智能体——如果它控制出站参数的生成——可能会继续发送旧的键，服务器静默忽略它，默认值接管，结果你得到了一个空结果集，而模型将其合理化为一个自信的“未找到匹配项”。如果重命名发生在响应端而非请求端，模型只需将新字段映射到其先前的预期并继续。无论哪种情况，失败都是静默的。

第二种是类型转换 (type shift)。以前是字符串的字段现在变成了数字。以前是扁平的列表现在变成了嵌套结构。JSON Schema 验证器能捕捉到这一点；智能体则不然。模型会将新的形状强行转换为其先前的心理模型，有时正确，有时错误，且没有任何信号说明是哪种情况。这种模式最危险的版本是强制转换几乎正确——正确到用户察觉不到，但偏差大到足以损坏下游状态。

第三种是语义偏移 (semantic shift)，它是能击溃所有正式验证器的类型。Schema 在字节层面是完全一致的。字段名称、类型和顺序都匹配。改变的是含义。曾经表示“处理状态”的 status 枚举现在表示“计费状态”。曾经表示“仓库区域”的 region 字段现在表示“客户区域”。形状没问题，但语义反转了。JSON Schema 验证器看不出任何异常；智能体会根据错误的理解悄悄产生输出，直到系统之外的某人注意到差异。

前两种可以通过 Schema 强制执行来处理。第三种则会惩罚那些混淆了 Schema 验证与契约测试的团队。

为什么版本化 API 不再能保护你

加载中…