当你最大的客户端是 Prompt 时，如何弃用 API

你完美地执行了弃用指南。提前六个月发布公告邮件。包含四种语言代码示例的迁移指南。在每个 v1 响应中添加了 Sunset 响应头。开发者仪表板上的横幅。两封提醒邮件。然后你关闭了 v1 —— 但结果并非指南所承诺的安静切换，你的错误率直线飙升并维持在高位。流量没有迁移。它只是不断涌入、失败并重试，且容量比以前更高，因为每一次失败都触发了另一次尝试。

指南之所以失败，并不是因为你执行得不好。它的失败是因为它假设另一端是一个人类 —— 一个会阅读邮件、浏览变更日志并在截止日期前提交 Jira 任务进行迁移的人。你很大一部分流量背后已经没有这样的人了。它来自智能体 (Agent)，它们对你 API 的认知被冻结在系统提示词、工具 schema 以及散布在成千上万个你看不见也永远无法触达的代码库中的模型训练数据里。你的停用通知是写给读者看的。而你的最大客户端是一个 Prompt。

弃用指南假设有人在听

标准 API 生命周期的每一步都依赖于在正确时刻出现的人眼。如果有人阅读收件箱，弃用邮件就起作用。如果开发者打开迁移指南，它就起作用。如果有人登录仪表板，横幅就起作用。甚至 Sunset 响应头 —— 工具箱中最具机器可读性的工具 —— 之所以奏效，也主要是因为监控库将其暴露给人类，然后由人类安排迁移。

这个假设已经悄然失效。到 2026 年中，Web 上的自动化请求首次超过了人类流量 —— Cloudflare 的雷达数据显示机器人流量占 HTML 流量的 57% 以上 —— 而智能体部分是增长最快的部分，仅在 2025 年，AI 智能体流量就增长了几千个百分点。API 本身就已经占据了 Web 流量的大部分；现在，这些 API 调用中越来越多的一部分不再是由开发者根据你当前的文档编写的代码组成的，而是由模型在推理时决定你的 API 可能长什么样。

这种区别比原始流量更重要。手写的 SDK 集成虽然陈旧但清晰：在某人编写它时它是正确的，并且有一个代码库可以让开发者去更新。而智能体的集成在三层维度上同时过时，且其中两层根本没有代码库。

智能体对你 API 的认知究竟存在于何处

当智能体调用你的 API 时，它对你端点的认知来自于三种来源的混合，且每种来源的衰减周期都不同：

• 模型训练数据。 模型在训练时记住了存在于博客文章、Stack Overflow 答案和开源代码中的 API —— 这个快照在模型进入广泛生产使用时通常已经过时一年或更久。更糟糕的是，训练数据是权重偏向热度的：如果旧端点出现在一万个代码库中，而新端点只出现在两百个中，模型会自信地输出旧的那个。这与模型倾向于使用已弃用库的机制相同 —— 已弃用的模式在权重中具有更大的引力。
• 系统提示词和工具 schema。 某人在某处将你的端点文档粘贴到了系统提示词中，或者编写了一个封装你 API 的 MCP 工具定义。这些文本现在存在于他们的代码库、智能体平台或向量数据库中。它永远不会收到你的弃用邮件。只有当它坏到一定程度以至于需要人类介入调查时，它才会更新 —— 而这恰恰是弃用流程本该防止的故障模式。
• 检索库中缓存的文档。 那些确实将智能体建立在你文档基础上的团队，通常是通过爬虫构建的 RAG 索引来实现的。如果爬虫频率是每季度一次，你六个月的弃用窗口期仅相当于两次索引刷新 —— 前提是流水线仍在运行且有人重新嵌入了更改后的页面。

注意这三点中缺少了什么：你的变更日志。一份从未进入上下文窗口的弃用通知等同于不存在。模型不知道它没有检索到的信息，而所有的标准弃用渠道 —— 邮件、博客文章、仪表板 —— 都不会向任何地方的上下文窗口提供输入。

关闭 v1 不会引发迁移 —— 它会引发重试风暴

这是打破旧思维模式的行为差异。当手写代码集成命中一个已失效的端点时，它会抛出异常，触发报警，然后由人类修复。失败是响亮的、归因明确的且终结性的。当智能体命中一个已失效的端点时，它会做智能体天生擅长的事：应对。

它会重试。它会重新组织请求。它会幻觉出一个看起来合理的备用端点并尝试。它可能会认为错误是暂时的并退避，然后再次尝试原始请求。将这种循环放大到每一个持有你 API 过时认知的智能体实例上，关闭 v1 并不会减少 v1 流量 —— 而是放大了它，将每一次本该发生的请求转化成一连串的失败、格式错误的猜测和重试。你的基础设施为这场风暴买单，智能体的运营商为浪费的 token 买单，而最终用户得到的是一个被静默降级的结果，且没有人会将其记录为“供应商弃用了 API”。

MCP 生态系统已经给这种故障模式起了一个名字：静默损坏 (silent breakage)。重命名的参数或删除的工具不会像损坏的 SDK 构建那样产生清晰的验证错误 —— 它会产生一个误解指令并以错误方式绕过问题的智能体，且没有人会注意到。协议本身的版本控制很清晰，但单个工具仍然没有标准化的版本控制层，因此 schema 漂移会演变成行为漂移，而不是构建失败。开放 Web 上的弃用在更大规模上也面临同样的问题：消费者不会崩溃，它会虚构 (confabulates)。

加载中…