如何为人工智能代理设计API

API是为人类开发者设计的。人们会阅读文档，理解某个接口背后的设计意图，并知道在遇到意外情况时该如何处理边缘案例。

而AI代理并没有这样的背景知识与理解能力。

AI代理是通过模式、示例、随机数据以及实时响应来理解API的。当某种行为或方法存在模糊性或不一致性时，AI模型并不会停下来“思考”——它会直接用随机值来填补这些空白。

在实际应用环境中，这种随机处理方式可能会导致各种问题，比如重复的操作、意外的副作用，甚至破坏整个工作流程。

正因为如此，那些对人类开发者来说完全可行的API，在被AI代理使用时却常常会出故障。问题的根源往往不在于“代理不够智能”，而在于这些API本来就不是为需要自主决策、调用工具并在没有人类干预的情况下处理异常的机器或代理设计的。

在本文中，你将学习如何设计能够让AI代理可靠使用的API。我们的讨论将围绕三个关键原则展开：

1. 确定性行为：相同的输入和状态应该产生可预测的结果。

2. 严谨的模式：完整、清晰且可测试的规范。

3. API边界上的防护机制：授权机制、验证规则以及安全默认设置，这些都能防止不必要的自主行为导致风险。

本文的目的并不是要开发“基于AI”的API，而是要打造那些清晰、严谨且可靠的API——即使使用这些API的不是AI代理，而是其他开发者或工具。

目录

• 先决条件

• 为什么“对开发者来说足够好”的API并不适合AI代理使用

• 原则1：确定性行为

• 原则2：严谨的模式

• 原则3：API边界上的防护机制

• 连接API与AI代理运行环境的模式

• 一个实际的案例分析

• 检查清单：你的API是否适合AI代理使用？

• 结论

先决条件

在阅读本指南之前，建议具备以下知识：

• 对HTTP API和REST概念有基本的了解

• 熟悉JSON格式以及API请求/响应的模式

• 理解认证、分页、重试等常见的API相关概念

为什么“对开发人员来说足够好”的标准并不适用于智能代理

人类开发人员会运用隐含的知识和上下文信息：他们会阅读Slack聊天记录、博客文章，并且知道“404错误通常意味着你忘记了工作区ID。”

而智能代理所获取的信息，主要局限于技术规范、示例代码以及最后的响应内容。

这种差距会以一些可预见的方式表现出来：

• 语义模糊：错误的端点或参数组合会导致问题。

• 未记录的扩展功能：模型可能会自行添加字段，或者误解某些可选行为的含义。

• 错误响应不一致：有时应该重试操作，但却不会重试；而有时候明明可以重试，却反而不进行重试。

• 非幂等的“执行操作”端点：这会导致重复收费、重复创建工单或重复发送邮件等问题。

行业专家和实际操作者的意见都一致认为：智能代理正成为API的主要使用者之一，因此机器能够理解这些接口的重要性与开发人员的体验同样重要。

例如，关于将OpenAPI视为智能代理的信息来源、新兴的工具协议，以及那些与人类用户不同的使用行为模式，都可以在本文末尾列出的资源中找到相关讨论。

原则1：确定性行为

对于智能代理来说，“确定性”并不意味着“永远返回相同的JSON响应”。它实际上意味着：在相同的请求和相同的服务器端状态下，你的API必须表现出智能代理能够预测的行为；而当状态发生变化时，你也必须明确地告知智能代理这一变化。

优先使用明确的状态表示方式，而非隐藏的机制

智能代理很难理解“有时服务器会根据内部标志来执行某些操作”这种行为。人类可以通过产品说明来推断意图，而智能代理则需要通过观察模式来理解行为规律；如果这些模式发生了变化，智能代理的自主性就会受到影响。

一些实际可行的做法包括：

• 明确地定义各个状态阶段（如草稿 → 已提交 → 已批准），而不要用未记录的参数组合来覆盖同一个status字段。

• 在数据发生变更后，返回所有发生变化的信息（如更新后的资源内容、相关的ID以及接下来可以执行的操作）。

• 避免隐式地强制修改数据（例如自动纠正错误的枚举值、悄悄删除未知字段），除非你事先对这些行为进行了明确的说明和标注。

确保写入操作的安全性：幂等性与意图标识符

对于任何会生成账单、发送消息、配置基础设施，或者执行其他不可逆操作的端点，都应假设用户可能会多次提交相同的请求。

• 为创建类操作提供幂等性标识符（可以放在请求头中或响应体中）。

• 使用明确的HTTP语义：POST用于创建新资源，PUT用于替换现有资源，PATCH用于部分更新；同时要明确说明重复请求的含义。

• 在可能产生重复数据的情况下，提供基于客户端标识符的查询路径，以便智能代理能够进行数据合并处理。

分页与排序：统一的标准，适用于所有场景

如果每种资源的分页方式都不相同，模型就会混淆各种处理策略。

为了解决这个问题，应为每个API接口指定一种分页方式（如使用光标还是偏移量），并严格遵循这一规范。

此外，必须确保返回的数据排序顺序是稳定的，或者明确要求用户使用`sort`函数进行排序。同时，应始终以统一的方式提供`next`链接或光标功能。

超时处理、部分成功结果以及异步操作

代理程序最讨厌“可能成功了”这种不确定的状态。那些需要长时间才能完成的操作，必须被明确设置为异步执行的：

• 响应格式应为`202 Accepted` + 作业ID + 加上轮询或Webhook通知。

• 终端状态应明确划分为`succeeded`、`failed`或`canceled`，并且在失败时需要提供详细的错误信息。

原则2：严谨的规范设计

如果确定性关乎行为，那么规范则关系到通信机制。对于代理程序而言，你的OpenAPI规范并非仅仅是书面文件，而是运行时接口的重要组成部分。

将OpenAPI视为合同，而非纪念品

如果规范制定滞后于实际生产环境，这种做法比没有规范还要糟糕——因为它会让代理程序错误地理解系统的行为。如今，越来越多的团队将OpenAPI视为具有法律效力的合同，在持续集成流程以及前端接口开发中都会依据这些规范来验证请求和响应的结果。

以下是符合代理程序使用需求的OpenAPI规范的最低标准：

• 每个操作都应该有`summary`和`description`，这些内容不仅要说明该操作返回什么结果，还要明确说明在什么情况下应该使用它。

• 请求体中的每个字段都应配有`description`以及具体的`example`值，以便开发者能够清楚地了解其用法。

• 所有响应结果都应被详细记录下来，包括4xx和5xx错误代码，并且返回的数据格式必须是稳定的JSON格式。

用自然语言准确描述意图

代理程序不会因为描述过于详细而感到困扰，但它们会对于含糊不清的表述感到困惑。

与其这样写：

“获取订单信息。”

不如这样写：

“为已认证的商家列出所有订单。支持按`status`状态或`created_at`创建时间进行筛选。最多返回`limit`条记录；如需查看下一页内容，请使用`cursor`参数。”

这种描述方式符合许多指南所倡导的上下文相关或自描述型API设计原则：规范中不仅包含了数据类型的信息，还蕴含了具体的使用意图。

示例是合同的重要组成部分

对于每个接口端点，你都应该提供一个正常的操作示例，至少提供一个因验证失败而返回400错误码的示例，并且还要为那些可选字段提供示例，以便说明当这些字段的值发生变化时，系统会如何做出反应。

这样的示例有助于避免模型出现“误解数据结构”的情况，从而确保系统能够正确地处理各种输入数据。

JSON模式的严格性有助于工具调用流程的正常运行

如果你的代理程序使用函数调用或结构化输出数据，那么请优化相关的数据模式：

• 对于规模较小的封闭集合，优先使用enum类型。

• 对于必须存在的字段，请明确标注为required。

• 在确实需要使用特定格式时，才使用format属性（例如uuid、date-time）。

• 如果需要对敏感数据进行严格验证，请避免在涉及安全性的数据结构中设置additionalProperties: true选项。

请统一各项内容的命名规则

如果在不同的接口中使用不同的字段名称，比如一个接口使用userId，而另一个接口使用user_id，这不仅会给人类用户带来困扰，也会让代理程序出现错误。因此，请选择一种统一的命名规范并严格执行它。

原则3：在API边界设置防护机制

自主执行功能会放大犯错的可能性。而防护机制则能将“小错误”转化为被及时阻止的请求，从而避免严重问题的发生。

授权权限应该狭窄且明确

代理程序应获得的权限应该是最小限度的。例如，可以使用有效期较短的令牌，并明确规定令牌的更新流程；同时，授权范围也应与具体的操作相对应（比如orders:read表示仅可读取订单信息，orders:write则表示可以修改订单信息）。此外，应避免设计那些需要人类用户介入才能完成的流程（例如验证码验证），或者通过点击链接来完成操作的流程；对于这类流程，应该使用人工干预机制来进行处理。

进行严格验证，确保错误能被及时、清晰地发现

在接口边界处，应对无效输入进行拒绝处理。此时，应返回稳定的error_code值，以及人类能够理解的message内容（用于日志记录和用户界面显示）；同时，还可以提供指向问题所在位置的field或JSON指针，以及链接到相关文档的doc_url。

这种处理方式符合许多专业文章中的建议：不透明的500错误代码和通用性的错误信息，往往会让自主执行的客户端程序陷入混乱。

RFC 7807中规定的application/problem+json格式，是一种适用于HTTP接口的、结构化明确的错误报告机制，代理程序可以一致地解析这种格式的数据。

区分“读取数据”与“修改数据”的操作

对于那些影响较大的操作（如退款、删除数据、转账等），建议采用两步验证机制：首先创建操作意图，然后再确认是否真的执行该操作。

或者，你可以先使用查询参数或专门的接口进行测试性操作，以确保操作流程的正确性，而无需真正提交修改请求。

另外还需要注意的是，针对代理程序的突发行为和自主执行的循环机制，需要适当设置速率限制和配额，这样才能避免这些机制带来的流量压力超过人类用户的正常使用需求。

可观测性是一项重要的产品功能

请为所有日志记录添加关联ID，并在安全的情况下将这些信息包含在响应结果中；同时，要密切监控那些可能导致重复尝试的操作行为。如果代理程序将409错误代码误解为“可以无限次重试”，那么这种行为就会对你的系统造成严重的威胁。

连接API与代理程序运行时环境的通用模式

工作流程文档编制：序列而非仅终点

当代理能够按照既定步骤操作时，他们的表现会非常出色。记录常见的操作序列（例如“创建客户账户→添加支付方式→进行收费”），并且当产品的复杂性需要时，可以参考为多步骤API流程设计的标准规范（比如Arazzo的标准）。

超媒体与“下一步行动”

提供指向合理后续操作的链接（例如分页功能中的next按钮，或相关资源链接），可以有效减少即兴决策的需要。这种设计理念与HATEOAS的原则是一致的：响应会明确告诉用户下一步该做什么，而不是让系统自己去猜测URL地址。

以工具为导向的设计方案（以MCP为例）

像Model Context Protocol（MCP）这样的协议正逐渐被广泛采用，它们能够以结构化的方式暴露出可供代理直接使用的功能模块。

一种实用的做法是：不要将所有的微端点都作为独立工具来提供，而是要根据用户的需求提供较为粗粒度的工具接口，同时确保底层的REST API设计保持简洁清晰。

MCP并不能替代优秀的API设计，它只是提供了一种用于功能展示和发现的机制。如果在一个杂乱无章的API上套上一层薄薄的包装层，系统依然会显得混乱不堪——只不过在公开环境中这种混乱会更快地显现出来而已。

用于发现目的的元数据（llms.txt及类似文件）

有些团队会在文档网站上发布/llms.txt或类似的轻量级元数据文件。不过这些文件应该被视为辅助工具，而非OpenAPI的替代品。

虽然各生态系统对这类元数据的采用程度仍在发展中，但其核心理念是正确的：就是要让机器能够轻松获取这些标准化的描述信息。

实际应用前的对比

弱式设计模式（对代理不友好）

POST /do-stuff

响应结果为200 OK:

POST /v1/invoices
Idempotency-Key: 7b3c-...

{
  "invoice": {
    "id": "inv_9Qz",
    "status": "draft",
    "total": { "amount": "120.00", "currency": "USD" }
  },
  "links": {
    "finalize": "/v1/invoices/inv_9Qz/finalize"
  }
}

{
  "type": "https://api.example.com/problems/duplicate-idempotency-key",
  "title": "重复的幂等性键值对",
  "status": 409,
  "detail": "收到了另一个使用相同Idempotency-Key的值体。",
  "error_code": "IDEMPOTENCY_KEYReuse_BODY_MISMATCH"
}