AI 代理崛起，API需转型为机器中心，重视规范质量和语义丰富性。遗留习惯如通用端点和轻量规范需摒弃。组织文化需转变，视AI为协作者，规范为产品。版本控制需更精细，最终目标是智能系统适应变化。
译自：Why Your Legacy APIs Are a Roadblock for AI Agents
作者：Saqib Jan
多年来，API 的构建都明确面向一个消费者：另一个团队的人类开发人员，他们可以解读文档、处理不一致之处，并在共享的 Slack 频道中提问。但现在，AI 代理正在崛起成为主要的 API 消费者，他们缺乏直觉或“部落知识”来弥补设计不佳的合约中的空白。
这给技术领导者带来了一个紧迫的战略问题。互联网上充斥着解释如何从 OpenAPI 规范生成模型上下文协议 (MCP) 服务器的技术步骤的教程，但仅仅运行工具并不是一种策略。仅仅具有功能的 API 和真正有效的 AI 交互 API 之间的区别在于其底层规范的质量和语义丰富性。
API 开发平台 Ambassador 的 CEO Steve Rodda 评论道：“一个有效的 MCP 服务器，即允许 AI 可靠地进行推理和行动的那种服务器，源于一个远不止功能的规范。”Ambassador 帮助开发人员开发、测试、模拟和部署 API 服务。
Rodda 推理说：“真正的问题是您的 API 是否真正为这个新的自主世界做好了准备，” 他补充说，组织必须批判性地评估其现有 API（以及支持它们的代码）为这个新的自主消费时代做好了准备。
为了获得全面的了解，我们咨询了行业内杰出的技术领导者，寻求他们对被忽视的细节、需要改变的根深蒂固的习惯以及从以人为本转向以机器为中心的 API 策略所需的文化转变的见解。他们的集体见解为生成规范之后该怎么做提供了一个实用的路线图。
为什么上下文对您的 API 规范至关重要
推动在代理 AI 中实现有效的 MCP 正在获得动力，因为它解决了关键且代价高昂的业务问题，尤其是在客户加入的时间和复杂性方面。AI 原生测试平台 LambdaTest 的联合创始人兼产品负责人 Mayank Bhola 分享了一个直接的例子。
对于他们的一个产品，手动来回配置新客户的设置可能需要几个小时到两周的时间。他说，通过开发一个智能扫描客户项目并自动生成必要配置的 MCP，“整个两周的入职流程现在缩短到不到一个小时。”
这证明了通过 MCP 进行的精心设计的、具有上下文意识的交互远远超出了传统 REST API 的能力，从而提高了业务效率和客户满意度。
那么，区分 AI 可以仅仅解析的规范和它可以真正理解的规范是什么？大多数工程领导者的共识是，上下文至关重要。由于 AI 代理无法推断意图或要求澄清，因此规范本身必须完成所有工作，从简单的技术合约转变为丰富、描述性的指南。
这首先要像对待团队中最新的成员一样对待 AI，这位成员才华横溢，但没有机构知识。它需要许多团队忽视的描述性清晰度，因为 AI 无法填补空白。
Harness 的首席产品经理 Rohan Gupta 强调了这一点，他指出：“AI 代理需要清晰且一致的参数，例如精确的描述、模式示例和定义明确的错误代码。与人类不同，AI 代理无法推断或填补空白。上下文至关重要。” 这意味着团队必须养成习惯，要求每个 API 参数、字段和错误代码都包含详细的、人类可读的描述和一个具体的示例，就像他们向第一次看到您系统的开发人员解释一样。
这种对语义清晰度的需求不仅限于描述，还直接适用于正在传输的数据。例如，虽然 “勾选” MCP 服务器在技术上可以提供 API 调用，但这对于 AI 代理来说是不够的。一个名为 status 的 API 字段，其值为 1、2 或 3，除非明确记录这些值代表什么，否则毫无意义。强制执行此操作的最有效方法是在您的 CI/CD 管道中实施一个 linting 规则，该规则标记使用数字或缩写代码的任何 API 参数，除非它具有相应的、详尽的所有可能值及其明确含义的列表。
但这不仅仅是描述数据；而是要赋予您的 API 端点目的。您可能需要将您的规范更多地视为组织良好的能力目录，而不是原始的接口合约。开发人员可能会发现，为每个操作提供一个唯一的、基于动词的名称（例如，listAllTodos 而不是仅仅 list）以及对其目的的清晰描述很有帮助。这里的一个好的第一步是建立一个 API 治理策略，该策略要求所有端点操作都基于动词且高度具体，清楚地说明它们执行的操作以及它们作用的资源。
这指向了 API 设计理念的根本转变。HighByte 的首席技术官 Aron Semle 使用了一个强有力的类比，他评论说，低级 CRUD API 就像 “让 AI 访问乐高积木并要求它建造房屋：它可能会成功，但它将有很多自由度和幻觉空间。” 这种结构不良的 API 不仅会使代理感到困惑； 它们会直接增加不正确操作或幻觉 API 序列的风险。这应该促使组织优先创建更高级别的、复合 API 端点，这些端点与常见的用户目标保持一致，即使它们在幕后协调多个细粒度的内部 CRUD 操作。
对于高风险环境中的 API，此上下文还必须扩展到操作规则。正如 Scality 的首席技术官 Giorgio Regni 指出的那样，许多规范缺乏 “用于事务类交互的内置原子操作” 和 “基于上下文的动态权限来保护敏感数据”。为了解决这个问题，组织应让其安全和平台工程团队直接参与 API 设计审查过程，确保规范包括事务完整性的明确定义并实施最小权限原则。
所有这些要点都归结为一个关键问题。核心挑战不仅仅是添加一些描述性字段，而是从根本上重新思考首先设计 API 的意义。Rodda 强调，重点必须从简单地记录端点转移到设计一个丰富的、具有上下文意识的合约，该合约为 AI 提供有效且安全地行动所需的所有指令。这使得领导层必须将 “AI 就绪” 确立为 API 设计和审查过程中的正式签署标准，并附带一个涵盖语义清晰度、任务导向和操作安全性的清单。
使 AI 代理感到困惑的遗留习惯和实践
构建高质量的规范只是解决方案的一部分； 组织还必须积极地摒弃遗留的设计习惯，这些习惯虽然适用于人类开发人员，但会给自主代理带来重大问题。对于开发人员来说，曾经可以接受的捷径或小麻烦现在是 AI 代理的重大障碍，他们会逐字逐句地理解每个细节。
首先是构建过于通用的 “厨房水槽” 端点的习惯。开发人员经常创建一个单一的、灵活的端点来更新大型对象，假设调用开发人员会知道哪些字段可以安全地组合更新。但是对于 AI 来说，这种灵活性是一个陷阱，迫使它猜测有效的操作并可能破坏某些东西。
Microsoft 的高级软件工程师 Nandita Giri 通过 updateCustomer 端点的示例指出了这一点，该端点 “允许对大型对象进行任意的部分更新”。她解释说，这是不好的，因为 “代理必须猜测更新什么是安全的和有效的。” 相反，她的建议是将操作分解为有针对性的、显式的端点，如 updateCustomerEmail 或 updateCustomerAddress，以便代理的任务明确无误。
还有暴露过多的相关习惯，为 AI 创造了一个嘈杂且令人不知所措的表面。为了快速提供透明度，团队可能会将每个内部函数映射到 AI 工具，但这可能会适得其反。
根据 Hopper 的首席软件工程师 Ravi Teja Thutari 的说法，这种 “将每个 REST 端点天真地一对一映射到 AI 工具可能会使 LLM 不堪重负”， 使模型难以从大量的低级选项中选择正确的操作。更好的方法是在可能的情况下进行策划和抽象，将相关函数分组或仅公开与代理目标相关的高级工作流程。
并且有一个非常实际的、经济的原因要简洁。MCP 服务器返回的每个上下文片段都会添加到 LLM 的上下文窗口中，这会带来实际的性能和成本影响。Cloudinary 的 CTO 兼联合创始人 Tal Lev-Ami 告诫说：“使用 MCP 返回的所有上下文都会添加到 LLM 上下文中，这意味着它需要简短而精炼，返回冗长的描述在 token 方面既昂贵，又可能导致 LLM 溢出。” 这迫使团队在编辑时要毫不留情，确保每个描述和暴露的每个工具都服务于手头任务的直接目的。
另一个坏习惯是编写轻量级规范，并假设人类会手动在系统之间建立桥梁。多年来，团队一直依赖其他开发人员编写适配器或 “粘合代码” 来处理未记录的字段或不一致的行为。但是 AI 代理无法做到这一点。Gupta 解释说，这导致了 “AI 代理无法有意义地进行推理的轻量级规范和脆弱的适配器”。为了打破这个习惯，团队必须转变他们的心态，并开始将 API 设计为完整的、最终的接口，并将规范作为唯一的、不容置疑的真理来源。
这种不完整性的一个常见症状是缺乏对大型结果集的正确数据处理。Scality 的 Regni 指出，“缺少分页可能会导致服务器和代理的长时间等待和不必要的负载，同时可能导致超时和内存问题。” 对于任何可能返回超过少数结果的 API，构建健壮的、有据可查的分页不再是一个可选的 功能，而是创建 稳定可靠的 AI 就绪服务的核心要求。
虽然考虑 AI 不能做什么很重要，但更危险的是忽视使用它产生的新安全漏洞。随着 MCP 服务器的采用不断增长，安全性变得极其重要，因为 LLM 漏洞（例如 提示注入攻击、数据中毒和供应链问题）越来越受到组织的关注。
在 LambdaTest，工程团队对这一挑战采取了积极主动的方法。Bhola 分享说，他们远程运行 MCP 服务器，这种策略确保客户数据被移动到更安全的协议，并且永远不会离开本地系统。这需要在 API 设计中采用 “安全第一” 的心态，团队必须积极扫描并减轻新的风险，如工具中毒或权限管理问题。
这些问题通常是软件开发方式中更深层次的文化问题的症状。这些坏习惯持续存在是因为规范通常被视为在完成实际编码工作后生成的工件，而不是主要的设计文档。
当人们未能从一开始就创建或使用良好的 OpenAPI 规范时，“生成的 MCP 服务器不好”，Rodda 指出。真正修复这些习惯的唯一方法是以与应用程序代码本身相同的严谨性和重要性来对待 API 规范的设计和维护。
弥合从现有代码到有效规范的差距
避免在新 API 中出现坏习惯是一回事。但是，对于过去十年或更长时间编写的现有关键任务 API 呢，这些 API 首先是用代码编写的，而文档是遥远的后顾之忧？对于大多数已建立的组织来说，这是他们面临的最重大障碍，并且这个问题无法通过简单地将工具指向 Git 存储库来解决。
这是因为基本要素（高质量、最新的规范）通常根本不存在。这是 Rodda 为大多数企业确定的核心挑战。他提出了关键问题：“那么所有你没有规范的东西呢？ 很多 API 只是代码。 如果你无法从代码到规范，那么你无论如何也无法使用其中一种工具。”
这突显了对一类可以弥合这一差距的新工具的迫切需求。这就是为什么，借助像 Blackbird 这样的解决方案，Ambassador 的方法是使团队能够直接 “从代码到 MCP 服务器”，从而生成必要的规范作为现代 API 工作流程的核心部分。
但是，即使在生成初始规范之后，真正的挑战是保持该规范与不断发展的代码完美同步。Giri 根据她在 Microsoft 从事 AI 代理框架和企业 API 集成方面的工作经验，强调了 “维护差距”，即未记录的更改会在规范和 API 的实际行为之间产生差异。
对于人类开发人员来说，这是一种不便； 但对于信任规范的代理来说，她说，“这是致命的”， 并警告说，这种偏差也会损害对代理性能的信心，因为 “一旦代理由于规范代码偏差而失败，就很难重新获得用户的信任。” 这使得团队必须添加自动化的 CI 管道，以执行合约测试，验证实时 API 行为始终与规范中的内容相匹配，然后再将更改推送到生产环境。
障碍也是翻译障碍，因为遗留 代码很少包含 AI 需要理解意图的语义业务逻辑。您可以从代码生成规范，但该规范将与代码一样难以理解。
最困难的部分是 “在每个端点上改造语义透明性和意图公开控制”，0rcus 的联合创始人兼 CEO Nic Adams 说。该过程无法完全自动化； 它需要产品经理和领域专家付出专门的努力，以手动丰富生成的规范，使其包含代码本身无法提供的业务上下文和目的。
弥合 AI 就绪差距意味着在系统的三个关键要素之间建立一个生动的、动态的连接。根据 Harness 的 Gupta 的说法，真正的工作是 “收紧规范、代码和 API 的实际运行时行为之间的反馈回路。” 为了实现这一点，组织必须投资于可以监控实时 API 流量以发现不一致之处并建立自动化标准化流程的工具。这减少了开发人员的辛劳，同时确保 API 对其新的 AI 消费者来说以可预测的方式运行。
为代理世界重新构建您的公司文化
解决遗留代码的技术难题是关键的第一步。但是，为了真正利用这种新范例，组织必须超越代码，并解决最重要的因素：他们的文化。AI 代理的兴起需要团队从根本上改变他们思考、构建和重视 API 的方式。
这始于心态的深刻转变。多年来，API 是为其他程序构建的，但现在它们是为可以自主推理和操作的协作者构建的。Gupta 认为，为了获得最大的收益，组织需要开始 “将 AI 代理视为操作员和协作者，而不仅仅是后端自动化工具。” 这要求从第一天起就将 AI 视为主要用户，让 AI/ML 专家参与 API 设计阶段，并根据代理性能（而不仅仅是 API 正常运行时间）定义成功指标。
如果 AI 代理是新的核心用户，那么 AI 的 API 规范 实际上就变成了它的用户界面。这会将规范从简单的文档提升为需要专门投资的核心产品。
Hopper 的 Thutari 强调，在 AI 驱动的世界中，工程团队必须 “将 OpenAPI 规范视为意图的真实来源”，因为对于代理来说，它就是产品。为了实现这一点，团队必须像对待功能开发一样，给予规范维护同样的优先级，并进行专门的所有权、严格的同行评审和像生产代码一样管理的版本控制。
这种流程转变自然需要打破旧的组织结构。代码优先的开发通常会创建孤岛，但以 AI 为中心的模型需要团队之间持续的、高速的沟通。0rcus 的 Adams 呼吁 “处置代码优先的孤岛”，而是围绕 “持续规范验证、跨学科设计审查和 [对抗性模型在环测试]” 重新构建工程。这意味着组建包括平台、API 和 AI 代理团队的跨职能小组，并强制执行它们之间的快速反馈循环，以将 API 转换为动态的、自我调整的合约。
甚至质量保证的定义也必须发展。由于大型语言模型是非确定性的，因此您无法使用用于传统软件的相同通过/失败逻辑来测试 AI 驱动的系统。“当应用程序使用大型语言模型时，您无法以传统的、确定性的方式 ‘测试’ 它…… ‘测试’ 一词不再适用； 这就是 ‘评估’ 一词发挥作用的地方”，Bhola 解释道。这种文化变革要求工程和质量保证团队超越简单的测试用例，而是构建强大的评估框架，可以大规模评估非确定性 AI 输出的质量和安全性。
但是，这种转变不应被视为负担； 这是一个使开发民主化的机会。通过使 AI 可以访问工具和系统，您还可以使更广泛的人群更容易访问它们。Cloudinary 的 Lev-Ami 将此视为一个摆脱 “仅限开发人员或开发人员优先” 的机会，创造一个更具包容性的工具集，其中 “创建者生态系统已经扩大” 以包括代理和更广泛的人类用户。领导者可以通过创建内部平台和教育资源来支持这一点，这些平台和教育资源使核心工程以外的角色能够参与构建 AI 驱动的工作流程。
这种从将 API 视为技术实现到核心业务产品的文化转变是释放价值的关键。这正是 “为什么 AI 使 API 和规范变得如此重要”，Rodda 认为，在这个新的世界中，拥抱 “基于规范的开发文化至关重要”，因为规范的质量直接决定了使用它的任何 AI 的有效性和潜力。
AI 如何打破传统的 API 版本控制
这种与 AI 代理的新型协作关系不仅改变了 API 的设计方式； 它从根本上打破了我们用于管理其整个生命周期的传统模型。在 AI 驱动的工作流程需要实时适应的世界中，熟悉的 v1、v2、v3 进程感觉缓慢而僵化。
这需要一种新的管理变更的思维模式。它不再仅仅是避免会使应用程序崩溃的重大更改； 而是为不断学习和推理的 AI 协作者提供稳定且可预测的体验。团队将需要 “像对待 UX 的更改一样对待 API 的更改”，Lev-Ami 说。他指出，做出不可预测的更改 “不仅会破坏应用程序，还会使代理感到困惑。” 这意味着 API 变更日志和更新公告必须考虑到这个新的受众，清楚地解释不仅发生了什么变化，而且为什么要发生变化，以及它可能如何影响代理的决策过程。
风险更高，因为代理通常跨来自不同提供商的多个 API 运行以完成单个任务。一个地方的更改可能会引起多米诺骨牌效应。根据 Gupta 的说法，这意味着版本控制不能再仅仅关注单个服务中的向后兼容性； 它还必须 “在不同的工具链中保持上下文连续性。” 因此，您的 API 治理策略必须扩展到包括跨系统影响分析，确保一个 API 中的版本更改不会导致代理复杂的、多工具工作流程中出现意外故障。
这种复杂性正在推动行业走向更流畅、更精细的方法。对于可能想要混合和匹配功能的代理来说，单一版本太粗粒度了。Giri 说，未来是 “基于能力的版本控制”，其中 [API 宣传精细的功能]，例如 supportsSegmenting=true。这允许 “对单个字段进行细粒度的弃用”，而不是终止整个版本。团队可以从今天开始尝试使用这种方法，在他们的 API 响应中使用功能标志和元数据标签，这允许代理在运行时查询特定功能，而不是被锁定在静态版本中。
这个未来需要重新关注流程和稳定性。企业 [必须改进他们的 API 治理]，并专注于 “实施逐渐弃用，而不是突然的重大更改”，Regni 建议。这意味着生命周期管理现在必须包括一个正式的、[数据驱动的弃用策略，其中 API 使用情况受到密切监控]，并且团队提供长期的支持和明确的时间表，以便 AI 代理的开发人员有足够的时间进行调整。
那么，这一切将走向何方？在最具前瞻性的愿景中，整个版本控制的概念可能会变得过时。Semle 设想了一个未来，在这个未来中，一个足够智能的 AI 使版本控制变得无关紧要，因为它 “可以像以前一样使用新的或更新的工具集来完成任务。” 但他用一点现实来缓和了这一点，指出幻觉仍然是一个挑战。虽然我们可能还没有达到这个目标，但这个愿景应该鼓励架构师设计最大的灵活性，因为最终目标是一个可以适应变化而无需人工干预的智能系统。
让您的组织为新的 API 经济做好准备
AI 就绪的旅程显然不仅仅是技术。这是一场哲学的根本转变。这些领导者的见解表明，API 正在从简单的合约演变为 AI 协作者的丰富、具有上下文的指南。这是一种从代码优先的文化（规范是事后的想法）向设计为中心的文化（规范是产品）的转变。
因此，在您的组织能够利用这个未来之前，它必须诚实地审视它的现在。对于任何已建立的企业来说，这条道路始于回答 Ambassador 的 Rodda 坚持领导者必须提出的基本问题。最重要的第一步是对您的资产进行坦率的评估，以确定 “您的规范是否达到了获得 MCP 服务器所需的水平？ 如果您有代码而没有规范怎么办？” 这些问题的答案将决定您的策略，并揭示从您现有的代码到 AI 驱动的未来之间建立强大桥梁的关键重要性。
投入到这种转变中的努力将是下一波竞争中的一个决定性因素。蓬勃发展的公司将是那些拥抱这种新现实并相应地构建其服务的公司。正如 Microsoft 的 Giri 精辟地总结的那样，“随着 AI 代理成为主要的 API 消费者，清晰性、一致性和机器可读性将决定胜者。”
