现有API为人设计，阻碍AI集成。AI成功关键在于API就绪度，需关注合规性、体验、可用性、安全与可发现性，以提升AI产出及ROI。
译自：Why Most APIs Fail in AI Systems and How To Fix It
作者：Frank Kilcommins
在过去的几年里，我审查了初创公司、企业和全球平台上的数千个 API。几乎所有都发布了 OpenAPI 文档。从理论上讲，它们应该定义良好且可互操作。然而在实践中，当 AI 系统以可预测的方式消费它们时，大多数都会失败。它们是为人类读者设计的，而不是为需要推理、规划和安全执行操作的机器设计的。
当 API 模棱两可、不一致或结构上不可靠时，AI 系统就会举步维艰或彻底失败。结果是，组织期望 AI 做什么与其底层 API 生态能够实现什么之间存在越来越大的差距。
集成而非智能，才是真正的挑战
正如颇具影响力的创始人 Tim O’Reilly 最近所主张的，AI 价值实现中的真正挑战不在于让模型更智能，而在于将它们集成到现有系统和工作流中。智能正迅速商品化，集成才是护城河。
企业 AI 计划反复在这项现实面前搁浅。研究显示，公司热衷于尝试 AI，但只有一小部分试点项目能投入生产，在某些情况下，甚至低至 5%。
一个被忽视的解释是 AI 系统必须使用的 API 的状况。如果这些 API 不清晰、不安全或不完整，再强大的模型能力也无法弥补。
大规模审视 API 时我们看到了什么
为了了解 API 在被智能系统消费时的行为，我们分析了超过 1,500 个公共 API。每个 API 都必须以机器优先的方式进行解析、验证和解释，而不仅仅是作为人类文档进行浏览。
出现的模式令人警醒：
- 服务器通常缺失或具有误导性： 许多 OpenAPI 文档没有定义服务器。即使存在，第一个也常常是 QA 或沙盒环境，而非生产环境。
- 身份验证不明确或缺失： 身份验证在 OpenAPI 描述中经常缺失或未充分指定，导致安全自动化无法实现。
- 结构有效性问题： 缺失路径参数、未解析的引用和不连贯的模式——所有这些都阻碍了可靠的机器解析。
- 示例使用不足且不可信： 示例始终使用不足，且在存在的情况下，经常与模式相矛盾。
这些是公共 API，团队有充分的动力投资于质量。在内部、轻度治理的 API 的大型组织中，AI 就绪度几乎肯定更糟。
为什么有效的 OpenAPI 并不足够
对于许多团队而言，发布一个有效的 OpenAPI 文档被视为终点。如果文档能解析、正确渲染并通过 linter 检查，API 就被认为是“完成”了。对于 AI 系统来说，这是一个危险的假设。
一个语法有效的 OpenAPI 文档只保证符合规范的语法。Linters 专注于结构有效性和基本实践；它们不保证 API 清晰地表达意图、连贯地建模其领域，或者可以被机器安全地推理。我们反复看到技术上有效但操作上模棱两可或具有误导性的 API。
AI 系统根据明确声明的内容运行。当含义是隐式的、不一致的或缺失的，模型就会产生幻觉或失败。
结构有效性是基线，而非保证
有效性不保证安全性。一个 OpenAPI 文档可能完全有效，但却暴露出危险的模式：没有身份验证的敏感操作、隐藏在模糊命名后的破坏性操作、不一致的错误模型或滥用 HTTP 方法以掩盖意图。
以上述示例为例。AI 系统可能会将其解释为创建、替换或部分更新用户。不能保证每次代理遇到相同的歧义时都会做出相同的假设。对于敏感端点，这种歧义会带来真实的安全风险。
从人类友好的语法到机器丰富的语义
大多数 API 要求开发者“填补空白”。缺失的意图在散文文档中而非 OpenAPI 文档中解释。身份验证规则和环境/服务器详细信息存在于参考文档之外。示例通常稀疏或不正确。人类可以弥补这一点，机器则不能。
AI 系统高度依赖 OpenAPI 文档本身。当关键含义存在于其他地方时，模型要么猜测要么失败，导致自动化脆弱且执行不安全。
AI 系统需要 API 具备什么：
- 可解释性： 清晰表达意图
- 可组合性： 具有良好类型模式的清晰输入和输出
- 安全性： 明确的安全要求
- 可预测性： 错误模型、状态码、幂等性
- 弹性： 明确的成功和失败信号
- 可发现性： 与目标/用户意图匹配的分类
转向机器丰富的语义不仅能提高 AI 能力，还能改善开发者体验。但这要求将 OpenAPI 视为可执行的契约，而非文档工件。
这种“有效”与“可被智能系统使用”之间的差距促使我们定义了一个衡量 API AI 就绪度的框架。
API AI 就绪度的六个维度
我们需要一种系统评估 API 是否能被 AI 系统使用的方法——不仅是它是否有效，还包括它是否能被理解、推理、发现和安全执行。
该框架从六个不同的维度评估 API。每个维度衡量就绪度的一个不同属性。任何一个维度都不能弥补另一个维度的弱点。这确保了更高就绪度级别需要均衡的配置文件——一个语义丰富但结构损坏的 API 是不可用的；一个有效但不安全的 API 不能被代理信任。
这些维度共同代表了 AI 成熟度，从基础正确性走向语义清晰、可操作性、信任和可发现性。
基础合规性
此 API 结构是否健全、符合标准且没有关键规范或模式问题？此维度衡量结构有效性、引用解析、linting 质量和模式完整性。如果 API 在此得分较低，则不应暴露。
开发者体验 (DX) 和工具兼容性
这评估了对人类和自动化管道的可用性：文档清晰度、命名一致性、示例覆盖率和正确性、响应完整性以及 API 是否能被现代工具清晰地摄取。高分能降低开发者和 AI 系统的摩擦。
AI 就绪度和代理体验 (AX)
这衡量 API 的语义质量以及它是否清晰地向 AI 消费者传达意图和含义：描述性覆盖、模式表达性、操作命名质量、错误标准化以及帮助模型推断行为的元数据。
代理可用性
仅仅理解 API 是不够的。代理必须能够安全有效地使用它。此维度衡量操作复杂性、操作之间的语义重叠、导航模式、幂等性和安全特性，以及操作与 AI 工具调用模型的契合度。
安全性
此维度评估身份验证覆盖范围和强度、传输安全性、敏感数据处理和整体风险态势。它为灾难性故障（如硬编码凭据或未受保护的敏感操作）应用严格的门控规则。
AI 可发现性
API 必须能够被代理找到和分类。此维度衡量描述丰富性、面向意图的措辞、领域标签、工作流引用和机器可读的发现信号。重要的是，可发现性是风险感知的；不安全的 API 可见性较低，以防止意外滥用。随着越来越多的企业功能变得 AI 就绪，确保我们能够“即时”地向代理展示我们的能力对于减少和管理上下文膨胀至关重要。
不再猜测：评分如何改变对话
没有测量，AI 就绪度的讨论就会陷入主观臆断。这六个维度提供了一个具体的路线图。一旦自动化，团队就可以跟踪进度、衡量影响并防止回归。
显著改善 AI 成果的简单改变
大多数 AI 就绪度差距无需彻底重写。小而有针对性的改变就能为开发者和 AI 系统带来巨大的改进：
- 修复损坏的引用和结构模式缺陷： 未解析的引用 (
$ref)、相互矛盾的类型和格式错误的模式会悄无声息地破坏自动化并削弱信任。 - 正确且一致地使用示例： 有效、与模式一致的示例有助于人类和 AI 推断正确的请求和响应形状。在提高理解方面，它们通常是代码示例的两倍。
- 撰写意图明确的摘要和描述： 明确说明一个操作做什么、为什么存在以及返回什么，能显著改善机器推理和可发现性。此外，将 HTTP 方法的使用与意图匹配（例如，使用
DELETE来删除资源）。 - 明确且适当地应用身份验证： 即使是公共 API 也受益于明确定义的安全态势。敏感操作必须始终受到保护；非敏感操作应有意开放。
- 标准化错误和分页模式： 可预测的故障和导航使 API 自动化更安全，并更容易组合到工作流中。示例：使用适当的 HTTP 状态码来记录错误状态，并使用 RFC 9457 (问题详情) 来表达错误响应结构。
为 AI 改进所做的努力，几乎总能同时改善开发者体验。AI 就绪度并非一个独立的赛道——它是良好 API 设计的加速器。
如何让高管关注 AI 就绪度
高管们关心的是生产力、成本、合规性、风险和投资回报率 (ROI)——而不是 OpenAPI 的质量。AI 就绪度与此直接相关：API 是 AI 的执行层。每个代理行动和自动化决策都变成一系列 API 调用。当这些 API 模棱两可、不一致或不安全时，AI 项目就会停滞在试点阶段，在生产中无法预测地失败，或者造成可避免的合规性和安全风险。
将 AI 就绪度框架为减少失败的试点项目、提高生产力、降低成本和实现更安全的自动化，是让高管们关心的方式。它将“API 规范”从一个技术细节变成了实现 AI 投资回报率的杠杆。
前进之路
AI 的成功并非始于一个更好的模型；它始于机器能够理解、信任和安全使用的接口。这使得 API 的 AI 就绪度成为一个高管关注的问题，而不仅仅是一个工具细节。
如果您想观看关于如何使 API 对 AI 系统和代理更可用的视频演示，我在“Getting APIs to Work”频道的一次近期演讲中进一步探讨了这些想法。
