API设计正从以人为中心转向AI优先。需弃用多功能端点、隐式规则和通用错误响应。新范式强调语义清晰、专用工具，并需扁平化数据模型，以确保AI代理的确定性行为和行为契约。
译自：It’s Time To Build APIs for AI, Not Just For Developers
作者：Saqib Jan
在过去的二十年里，API设计原则一直以人类开发者为中心。我们构建了为开发者便利性优化的系统，提供灵活的端点和他们可以解读的丰富文档。
但一类新型且强大的消费者正在以自主AI代理的形式进行颠覆，它们基于一套根本不同的原则运作，这要求我们构建和描述服务的方式采取新方法。
“这意味着我们开发者面临一个新范式：我们现在必须构建针对机器消费进行优化的API，这需要一种与我们用于以人为中心开发的设计理念截然不同的设计理念，”LambdaTest（一个AI原生软件测试平台）的工程总监Srinivasan Sekar表示。
这种日益增长的“AI优先”设计理念转变，优先考虑了机器有效推理和行动所需的明确性和可预测性。它为重新设计系统以适应新的代理世界奠定了清晰的框架。
从“开发者优先”转向“AI优先”
这一新宣言的核心是任何架构变更之前都必须进行的核心文化转变：从“开发者优先”转向“AI优先”设计。正如Srinivasan Sekar所解释的，多年来，我们一直为人类开发者的便利性优化我们的API。
这种方法偏爱灵活性，通常导致更少、多用途的端点，并依赖外部文档来澄清歧义。人类开发者可以阅读指南来理解某个参数仅在另一个参数存在时才需要——这是一个我们长期以来视为理所当然的细微差别。
“我们现在必须构建针对机器消费进行优化的API，这需要一种与我们用于以人为中心开发的设计理念截然不同的设计理念。” —— Srinivasan Sekar，LambdaTest 工程总监
然而，AI代理是根本不同的消费者。它们无法阅读外部文档，也无法推断参数之间隐含的关系。AI仅根据API模式提供的显式、机器可读契约进行操作。他认为，这正是“AI优先”理念的核心：一种优先考虑机器所需的绝对、明确清晰度的设计方法，在契约中不留任何解释空间。
与Srinivasan Sekar一起工作的Sai Krishna为这一转变补充了一个实际维度：“在LambdaTest，我们通过艰难的方式学到了这一点。我们有一个功能完善的API，用于配置测试环境，开发者们因其灵活性而喜爱。但当AI代理开始使用它时，我们发现失败率高达40%，因为代理无法解读我们单独文档中记录的隐式规则。我们不得不彻底重新思考我们的方法。”
这意味着要优先使用更具体、单一用途的端点，并在模式本身中明确定义所有约束。这种思维模式是构建任何成功可靠的代理系统的不可协商的基础。
忘却以人为中心API的三个习惯
在实践中采纳“AI优先”理念意味着要主动忘却传统、以人为中心API设计中根深蒂固的几个习惯。Srinivasan Sekar指出了三种常见的模式，这些模式虽然对人类开发者很方便，但当被AI代理消费时会造成严重故障。
首先是单个端点承载多重行为的习惯。开发者可以处理这种灵活性，但AI代理会因歧义而苦恼。AI优先方法要求端点明确、单一用途。
- 之前： 一个单一的
POST /user端点会根据请求体中是否存在id来模糊地处理创建和更新用户。 - 之后： AI优先方法使用两个不同且可预测的端点：
POST /users用于创建新用户，PUT /users/{id}用于更新现有用户。
其次是依赖隐式契约和外部文档。为了让代理可靠地行动，所有参数关系和依赖性都必须在机器可读的模式本身中明确声明。
- 之前： 传统模式会将
user_type和admin_level列为可选，迫使开发者阅读外部文档以了解它们的条件关系。 - 之后： AI优先模式使用条件逻辑使这种关系明确，允许机器在没有任何外部上下文的情况下理解契约。
最后，团队必须忘却提供通用错误响应的习惯。AI优先API必须提供结构化、详细的错误响应，以便代理能够自我纠正。
- 之前： 像
{"message": "Bad Request"}这样的通用JSON响应会中止自动化工作流。 - 之后： 结构化JSON错误提供特定字段，包括错误
code、message和details，精确指示哪个参数无效。
这些转变的共同目的是消除歧义。通过使端点、契约和错误明确化，开发者为自主代理可靠有效地行动提供了必要的可预测基础。
AI优先设计的新支柱
除了避免旧习惯之外，构建AI优先API还需要采纳一套以清晰性和可预测性为中心的新积极设计原则。
“这始于语义清晰性，”Confluent的产品高级总监兼AI战略负责人Sean Falconer说。一个真正的AI原生API必须不仅仅描述其技术功能；其机器可读契约还必须描述其业务目的、先决条件以及任何潜在的副作用。这为AI代理推理提供了丰富的上下文，使其不仅知道如何使用工具，还知道何时以及为何使用。
一个真正的AI原生API必须不仅仅描述其技术功能；其机器可读契约还必须描述其业务目的、先决条件以及任何潜在的副作用。
这意味着开发者必须丰富他们的API模式，超越简单的数据类型。例如，在OpenAPI规范中，每个参数和端点都应包含详细描述，不仅解释“是什么”（例如，一个整数ID），还解释“为什么”（例如，用于计费和支持工单的唯一客户标识符）。
通过设计Sean Falconer所说的“小型、专门构建的工具”，而不是暴露大型、通用API接口，可以最好地实现这种清晰度。 Typedef的首席技术官Yoni Michael同意这一原则，主张“最小化接口暴露”，这意味着API应只暴露给定任务绝对必需的部分。
对于架构师而言，这转化为一个明确的设计指令：抵制创建单体、通用端点的冲动。相反，复杂的业务流程应该分解为最小的逻辑组件，并为每个组件设计一个专用、受限的API。例如，一个庞大的/orders API可以重构为专注的、专用工具，如/create-order、/check-order-status和/request-refund。创建这些定义明确的工具可以减少歧义和AI的认知负荷，使其行为更容易治理和评估。
所有这些原则都服务于一个单一的关键目标：实现Yoni Michael所说的确定性行为。当自主代理串联多个工具来执行复杂工作流时，它不能承受意外。系统必须绝对可靠和可预测。
为了实现这一点，工程师必须优先考虑严格测试和尽可能采用无状态设计。每次具有相同输入的API调用都应始终产生相同的输出，不受隐藏依赖或不可预测的副作用的影响。这涉及为任何修改数据的操作提供清晰、幂等的接口，确保重复调用不会产生意外后果。
通过以语义清晰性、最小化接口暴露和明确目的来构建API，架构师提供了信任的基础，使AI代理能够有效利用它们。
AI数据重塑的障碍
即使有了这些前瞻性的设计原则，支撑所有AI优先设计的还有一个最终的、更深层的架构挑战。LambdaTest 的Srinivasan Sekar将其认定为所有挑战中最显著的一个：困难但必要的数据模型扁平化任务。
他解释说，大多数现有的企业API反映了根深蒂固的数据平台挑战，因为它们是围绕复杂的内部数据库模式或嵌套对象模型设计的。虽然人类开发者可以驾驭这些复杂的结构，但它们为AI代理带来了显著的“认知开销”。
一个深层嵌套的数据结构迫使AI模型在甚至开始处理信息之前就必须耗费宝贵的资源来理解数据的形状及其各部分之间的关系。
这种复杂性带来了很高的出错可能性，并使代理的行为更难预测。AI优先的解决方案是扁平化和规范化这些数据模型，将它们重新设计成更简单、更可预测的格式，以针对机器消费进行优化。
“构建最可靠代理系统的公司，不一定是拥有最复杂AI模型的公司。他们是那些努力重新设计API基础以使其能说机器理解的语言的公司。” —— Srinivasan Sekar
这通常是成为AI原生的过程中资源最密集的部分。Srinivasan Sekar认为，这项任务远不止简单地记录现有系统。它经常需要对数据访问层进行根本性的重新设计，并创建全新的、并行的API接口，专为AI代理构建。
Sai Krishna分享了这种转型的实际情况：“我们现在维护两个API层；我们的传统开发者API和我们的AI优化API。AI版本将一个以前嵌套四层的测试结果对象扁平化为具有显式关系ID的单层结构。它使我们的模式大小增加了三倍，但将代理处理时间缩短了70%。这项投资是巨大的，但却是必要的。”这确保了提供给AI的上下文不仅语义清晰，而且结构简单且立即有用。
未来是“行为契约”
总而言之，这些原则——向AI优先思维模式的文化转变、忘却旧习惯以及对清晰性和简单数据模型的深刻架构承诺——构成了API设计的新宣言。但这种新理念的影响超出了我们系统的初始工程阶段，并延伸到其整个生命周期。
Srinivasan Sekar预测，这将最终重塑API版本控制等核心DevOps实践。在一个自主代理是主要消费者的世界里，API管理的重点将从跟踪简单的语法变化转向保证“行为契约”。对AI的承诺将不再仅仅是API结构稳定，而是其行为一致且可预测，确保相同的输入始终产生预期类型的输出。
Sai Krishna阐述了这在操作上如何体现：“我们已经开始将行为契约与API版本分开进行版本控制。一个代理订阅一个行为契约，例如‘带有分页的搜索功能’，我们保证该契约的行为，即使我们演进底层实现。如果我们需要改变行为，我们会引入一个新的契约版本，给代理留出适应时间。”
Srinivasan Sekar和Sai Krishna都强调，这种对显式、可预测且行为一致的API的承诺是AI优先理念的最终体现。
“构建最可靠代理系统的公司，不一定是拥有最复杂AI模型的公司，”Srinivasan Sekar指出。“他们是那些努力重新设计API基础以使其能说机器理解的语言的公司。”
这一基础将是下一代可靠的代理AI应用程序的构建基石。
