AI 应用与 API：为何互不理解？
在瞬息万变的数字环境中，人工智能驱动的机器人正越来越多地遍历互联网，努力寻找并尝试与应用程序编程接口（API）进行交互。虽然其中一些自动化探索者怀有恶意意图，但越来越多且数量庞大的机器人是善意的消费者，他们努力发现、利用并从现有 API 中获益。这些请求通常源自模型上下文协议（MCP）驱动的平台，旨在使自主软件能够直接与网络 API 交互。
尽管其本质复杂，但这些 AI 客户端在许多方面都在苦苦挣扎。最新统计数据显示了一幅充满挑战的画面：多步骤 AI 驱动的 API 工作流成功率仅徘徊在 30% 左右。更糟糕的是，这些持续的客户端在初次失败后往往不会停止。相反，它们会继续尝试，产生过多的流量，同时降低目标 API 的整体价值主张。这引发了一个关键问题：为什么这些先进的 AI 客户端无法有效利用当今的 API，以及如何扭转这一趋势？
事实证明，答案并非新鲜事。AI 驱动的 API 消费者对基本要求与人类开发者相同：它们需要清晰度、上下文信息和有意义的结构才能成功交互。然而，许多组织历来忽视这些原则，似乎忘记了 2017 年里程碑式论文《Attention Is All You Need》中的深刻见解。这项关键研究向 AI 世界引入了“Transformer”的概念——根据词语在周围内容中的关系对其进行数学评分的模型。这种被称为“注意力”的评分机制使像 ChatGPT 这样的程序能够生成极其连贯且类似人类的响应。
Transformer 驱动的生成式 AI 工具的出现，要求我们彻底重新评估 API 的设计、文档和实现方式。虽然 ChatGPT、Claude、Gemini 和 Copilot 等平台擅长“关注”API 设计——识别 URL、HTTP 方法、输入、模式和预期输出——但它们本质上缺乏真正的理解或推理能力。它们可以识别 API “是什么”样子，但无法理解“为什么”应该使用它或返回数据“意味着什么”。本质上，今天的 AI 机器人是快速、灵活的 API 消费者，但在决策和解释意义方面存在困难。好消息是，通过利用它们在模式匹配和上下文关联方面的优势，我们可以增强 API 设计，以弥补其当前的局限性，从而使 API “AI 就绪”。
为了平衡竞争环境，有四项关键实践长期以来对人类开发者有益，对 AI 驱动的客户端也同样至关重要。首先，要明确。与人类不同，机器不是直观的探索者。虽然它们擅长解析文本，但无法进行直观的飞跃。它们需要明确的线索来了解可以完成什么、如何完成以及为什么。像 GET /customers/ 这样简洁的操作列表对人类来说可能很清楚，他们会寻找进一步的文档来获取详细信息。然而，对于机器来说，这种简洁会导致统计性猜测。提供明确的指令，例如“要检索客户记录列表，请使用 GET /customers/”或“要创建新的客户记录，请使用带有 createCustomer 模式的 POST /customers/”，通过消除歧义显著提高了成功率。
其次，告诉它们原因。AI 模型擅长识别 API “如何”使用，但在确定“为什么”使用方面则较弱。用上下文解释丰富文档可以弥补这一差距。诸如“使用 PriorityAccounts 端点根据市场规模识别前十名客户”或“在员工申请流程中所有其他步骤完成后，使用 submitApplication 端点”之类的短语提供了宝贵的提示。AI 驱动的客户端，特别是那些由大型语言模型（LLM）支持的客户端，擅长识别此类文本并将其与相关的 API 端点关联起来。
第三，保持一致性和可预测性。基于 LLM 的应用程序的巨大力量源于它们所训练的海量代码和文档数据集。这些积累的历史模式使 AI 客户端能够与新的 API 交互。因此，一个与训练数据中常见模式和约定相符的 API 将促进更顺畅的交互。偏离独特的元素、意外的响应或非传统地使用标准协议（例如，当 POST 更常见时，仅使用 HTTP PUT 进行创建，或在 JSON 普遍时依赖 XML 模式）将不可避免地使 AI 驱动的应用程序更难成功。
最后，使错误响应具有可操作性。当人类遇到错误时，他们通常会扫描信息，推断问题，并制定解决方案。然而，机器驱动的客户端缺乏这种直观的问题解决能力。它们通常会尝试随机更改或干脆放弃。为了支持它们，API 错误响应必须明确、提供上下文并遵循一致的格式。强烈建议采用“HTTP API 的问题详情”规范（RFC7078）。这种结构化格式不仅识别并解释了错误，还可以建议可能的解决方案，例如“此更新失败，因为缺少一个字段：hatsize。”这种方法也符合一致性原则，因为 RFC7078 在 LLM 训练数据中被广泛识别。此外，通过将错误视为“部分尝试”并提供清晰的反馈，API 可以有效地“重新训练”机器客户端，用如何解决未来问题的示例填充其本地上下文。
最终，那些增强与 AI 驱动的 API 客户端交互的实践，正是长期以来倡导的用于改进人类开发者 API 设计的实践。明确性降低了认知负荷，告诉开发者（和机器）原因简化了决策，一致性培养了直观体验，而可操作的错误响应则能更快地解决问题。持续监控 API 使用情况——观察常见端点、持续错误条件和流量模式——为未来的设计改进提供了关键见解。无论是服务于人类开发者还是机器代理，关注这些基本设计原则都能带来可观的回报。