你的内部平台的新首要客户是 AI Agent

你的平台团队通过开发者采纳度来衡量成功。内部 API 的月活跃工程师数量。新服务的首次调用时间（Time-to-first-call）。季度 DX 调研中的净推荐值 (NPS)。每一个指标都假设请求的另一端是一个人类——一个阅读入门指南、复制 curl 示例、并在错误消息毫无帮助时在 Slack 中抱怨的人。

这种假设正悄然变得不再成立。你内部 API 增长最快的消费者不是人，而是一个智能体 (Agent)：一个正在解决工单的编码助手，一个在夜间核对发票的工作流，或者一个为了回答一个问题而调用六个服务的支持机器人。这些调用者不会浏览你的文档——它们会将你的工具模式 (tool schemas) 摄取到上下文窗口中。当错误提示模糊不清时，它们不会提交 bug——它们会默默地重试、消耗 token，然后放弃。而且它们的数量即将超过人类。

数据已经揭示了这一差距。在 2025 年的 API 现状调查中，只有 24% 的开发者表示他们在设计 API 时会主动考虑 AI 智能体，而 51% 的人将未经授权的智能体访问列为首要安全担忧。我们对智能体访问我们的 API 感到焦虑，但在很大程度上并没有针对它们进行设计。这种错位是未来两年平台工程的全部故事：占主导地位的消费者到来的速度，快于接口适应并服务于它的速度。

智能体失败的方式与人类不同​

本能的反应是“API 就是 API——如果它对人类脚本有效，它就对智能体有效”。这种本能是错误的，而且失败模式非常特定。

人类开发者阅读一次你的端点，建立一个心理模型，并编写代码来永久记录这种理解。理解的成本只需支付一次。而智能体在每次调用时，都会根据你放在它面前的任何内容——工具名称、参数描述、响应的形状——重新推导其理解。这里没有持久的心理模型。接口就是文档，并且每次调用都会被重新阅读。

这改变了“好”的定义。考虑三个具体的差异：

• 人类能容忍响应中的 UUID；智能体则为此付费。 当你的端点返回 {"owner_id": "a3f9...", "project_id": "b7c2..."} 时，人类脚本会不加思索地在后续调用中传递这些 ID。智能体则必须要么进行另一次往返调用，将每个 ID 解析为有意义的内容，要么对它们所指代的对象产生幻觉。在返回原始 ID 的同时（或代替原始 ID）返回 owner_name 和 project_name 可以消除一整类浪费的调用。

• 人类看到 404 会推断修复方法；智能体需要明确指出修复方法。 HTTP 400: invalid_argument 告诉人类去检查文档。它没给智能体提供任何可操作的信息，因此它会重试同样的错误调用或放弃任务。如果错误提示是 "start_date 必须符合 ISO-8601 标准；你发送的是 06/20/2026，请尝试 2026-06-20"，就能将死胡同变成成功的第二次尝试。

• 人类会忽略不需要的字段；智能体则对所有字段支付注意力税。 你返回的每个字段都会进入上下文窗口，并竞争模型的注意力。当任务只需要 4 个字段时，返回一个包含 40 个字段的响应不仅是浪费，还会通过稀释信号来主动降低智能体的推理能力。

这三者背后的模式是：人类拥有免费、持久、带外 (out-of-band) 的理解力。智能体则拥有昂贵、短暂、带内 (in-band) 的理解力。忽略这一点的设计所交付的接口，在技术上可行，但在运行上会失败。

上下文窗口是你的新频率限制​

这是几乎还没有内部平台团队意识到的约束：智能体在调用你的工具之前必须知道它的存在，而“知道它的存在”是需要消耗 token 的。

数据令人清醒。加载到智能体中的七个典型 MCP 服务器会消耗大约 67,300 个 token 的工具定义——大约是 200k 上下文窗口的三分之一——这还是在用户输入任何单词之前。一个暴露 400 个工具的大型企业级 MCP 服务器可能仅为了描述自身就消耗超过 400,000 个 token，这甚至无法放入窗口中。你那精美且全面的内部工具包，如果被直接暴露，可能会因为太大而导致智能体根本无法加载。

对于平台团队来说，这是一个全新的失败模式。从历史上看，在 API 中添加第 401 个端点是免费的——没有人会一次性加载所有端点。人类只阅读他们需要的那一页。但智能体发现工具的默认方式是预先加载每一个定义，因此你添加的每一个工具都会对每一个智能体会话征税，无论该工具是否被调用。

在 2025 年底到 2026 年间出现的行业响应都针对这同一堵墙发起了攻击：

• 渐进式披露 / 工具搜索。 智能体不再将所有 schema 丢进 prompt，而是仅搜索并加载当前任务所需的工具。Anthropic 的工具搜索工具（Tool Search Tool）报告称，仅这一模式就减少了 85% 的 token 使用量。
• 代码执行优于 MCP。 与其将每个操作作为单独的工具调用公开，不如将你的服务呈现为智能体可编写代码的 API。它只导入需要的内容，并在执行环境中处理中间数据，而不是通过上下文窗口往返传输每个结果。Anthropic 测量发现，通过从工具调用编排转向代码执行，一个工作流的消耗从 150,000 个 token 下降到了 2,000 个——节省了 98.7%。
• 基于 Token 的计量和网关。 API 网关（如 Kong、AWS 和 Zuplo）增加了 token 计量和身份原语，以区分人类、服务和智能体，因为现在必须以 token 而非仅仅以请求来衡量计费和配额。