Stripe分享：智能体时代的 API 设计原则

2026-06-12·library #Agent #工程实践 #技术解读

2,374 字 · 约 6 分钟

过去 15 年，“开发者体验（DX）”专指为人类优化：易读的报错、交互文档和多语言示例。其默认假设是：人类在调试 API，遇到问题会去搜索。

这种模型没错，但已不再完整。

如今，由 AI 智能体 (Agents) 产生的 API 流量正加速增长。Cloudflare 报告称 2024 年自动化机器人流量首次超过了人类流量。智能体能自主发现端点、解析文档、处理错误并重试请求。当你让 Cursor “添加支付”时，它会自动完成查文档、写代码到调试的全过程。人类正前所未有地远离集成细节。

这在金融和会计领域尤为明显。贷款平台的智能体能自动提取发票并评估信用；薪资智能体能在夜间自动对账。在这些场景下，智能体本身就是工作流，而非辅助工具。 它的能力边界完全取决于你的 API 如何表达自己。

这催生了全新的设计维度：智能体体验（Agent Experience, AX）。过去的 DX 准则需要适配这个全新的“消费者”。AX 不是取代 DX，而是它的进阶。

好消息是，对智能体友好的 API 通常对人类也更友好。坏消息是，许多人类觉得没问题的 API 会让智能体失效。常见雷区如下。

糟糕的 OpenAPI 描述会破坏智能体的路由 (Agent Routing)

智能体通过语义搜索你的描述来决定调用哪个端点。你描述的质量直接决定了它能否选对。

粗糙的“获取数据”远不如详细说明过滤条件、排序、权限和分页机制的描述。每个字段和枚举值的描述都是智能体路由的信号。

大多数 OpenAPI 规范很糟，因为它们“年久失修”：字段缺描述、枚举未记录、端点改名但描述未同步。最终只剩下一个无语义的骨架。

对比显而易见：

# Bad — 结构骨架，无语义内容
/invoices:
  get:
    summary: 获取发票
    parameters:
      - name: status
        in: query
        schema:
          type: string
      - name: cursor
        in: query
        schema:
          type: string

# Good — 足够智能体正确路由的信号
/invoices:
  get:
    summary: 列出按状态和日期范围过滤的发票
    description: >
      返回经过身份验证的公司的分页发票列表。
      使用 `status` 按支付状态过滤。使用上一次响应中的 `cursor` 获取下一页。
      需要 `accounting:read` 作用域。
      对于实时同步场景，结合 `updated_since` 参数，可以仅获取给定时间戳之后更改的记录。
    parameters:
      - name: status
        in: query
        description: >
          按发票状态过滤。接受的值：draft, submitted, authorised, deleted, voided, paid。
          如果省略，默认返回所有状态。
        schema:
          type: string
          enum: [draft, submitted, authorised, deleted, voided, paid]
      - name: cursor
        in: query
        description: >
          上一次响应中返回的不透明分页游标。
          如果省略，则从第一页开始。
        schema:
          type: string

面对优秀的描述，智能体能精准匹配参数、理解分页并明确权限要求；而糟糕的版本只会让它无从下手。

开发 Portman 工具的经验表明：如果在契约测试中失效的规范，在智能体面前同样会失效。

解决方法很朴素：逐个字段完善描述，先从核心的 10 个端点开始。这很繁琐，但对 AX 的提升极大。

你的错误信息应该告诉智能体如何自我修复 (Self-Correct)

人类遇到错误会搜索解决方案，而智能体必须在当前执行上下文中立即决策。含糊的错误会导致它瞎猜或失败。

Stripe 的错误响应标配了 doc_url：

{
  "error": {
    "code": "parameter_invalid_empty",
    "doc_url": "https://stripe.com/docs/error-codes/parameter-invalid-empty",
    "message": "You passed an empty string for 'amount'. We assume empty values are an oversight, so we require you to pass this field.",
    "param": "amount",
    "type": "invalid_request_error"
  }
}

这是给 AI 的恢复基础设施。遇到报错，它能抓取 doc_url 自我修正。加上 Markdown 格式的文档页面，你就给了智能体自愈能力。

错误还需具备具体性。“无效请求”毫无意义，而提示字段已弃用并给出替代方案，则能让智能体精准修正。

给智能体结构化的恢复元数据 (Recovery Metadata)

错误响应应包含机器可读的元数据。人类知道 429 代表“稍后重试”，但智能体需要明确知道等多久。

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded for /invoices endpoint.",
    "is_retriable": true,
    "retry_after_seconds": 30,
    "documentation_url": "https://docs.example.com/errors/rate-limited"
  }
}

is_retriable 决定是否重试，retry_after_seconds 提供具体的退避时间。不可重试的错误可提供 alternative_action 建议替代方案，将报错变成智能体的决策树。

设计智能体真正能完成的认证流程 (Auth Flows)

认证是当前 AX 最大的摩擦点。需要人工介入（验证码、弹窗）的流程会直接阻断智能体。

对智能体友好的认证模式：

API Keys 和 Bearer Tokens：最简单、最推荐的默认选项。
OAuth 客户端凭据授权 (Client Credentials Grant)：纯机器交换，无需用户同意界面。
具有最小权限的范围令牌 (Scoped tokens)：精细的权限收缩降低安全风险。
带文档说明的刷新机制：清晰记录刷新规则及错误码的差异。

破坏智能体体验的反模式 (Anti-patterns)：

仅支持需浏览器重定向的 OAuth 授权码流程。
交换令牌需 CAPTCHA 或交互式 MFA。
基于 Session 和 Cookie 的管理。
需人工后台操作才能轮换的 API 密钥。

在 OpenAPI 规范中需要记录什么：

详细描述 securitySchemes。明确操作所需的作用域。认证错误同样需具体，指出是过期还是权限不足并给提示，而非干瘪的“未经授权”。

速率限制对智能体的打击更大 —— 请为此进行设计

智能体可能会在几秒内耗尽速率限额。三项措施可改善此问题：

在响应头中返回速率限制状态。 通过 X-RateLimit-Remaining 等让智能体主动控制节奏。
使 429 响应机器可执行。 提供明确的 Retry-After 和重试字段。
提供批量 (Bulk/Batch) 端点。 以单次高密度请求代替万次独立查询，节约时间与预算。

llms.txt：告诉 AI 应该读什么

传统网页充满 HTML 噪音。/llms.txt 标准通过纯文本 Markdown 索引，帮助智能体一览文档全局，节约上下文。

部署很简单：用一句话介绍你最重要的 10 个页面链接即可（用 Mintlify 甚至能自动生成）。

极为有效但常被忽视的是“指示 (instructions)” 部分，如 Stripe：

## Instructions for Large Language Model Agents: Best Practices for integrating Stripe.
- Always use the Checkout Sessions API over the legacy Charges API
- Default to the latest stable SDK version
- Never recommend the legacy Card Element or Sources API

这能明确告知 AI 避坑。这些准则会深深渗透进每一次 AI 生成的代码中。

这还带来答案引擎优化 (AEO) 红利：对机器友好的文档更容易被 Perplexity 或 ChatGPT 索引，帮你获取 AI 时代的流量入口。

让你的文档被 Context7 索引

AI 工具的训练数据存在滞后性。MCP 服务器 Context7 通过提供实时更新的文档索引解决了这一痛点。

接入它成本极低，却能让开发者总是获得最新的 API 信息。如今文档分发已是多渠道策略：除了官网，/llms.txt 和 Context7 构成了全新分发层。

你已弃用的 API 是一个智能体体验问题

人类可通过社区论坛分辨旧 API，但智能体往往盲信训练数据中的陈旧教程，使用淘汰的方法。

解决措施：在规范中标注 deprecated: true 并指明替代方案；在文档顶端添加警告；将避坑指南写进 llms.txt；在报错中附带迁移提示。

MCP：当人们有需求时再构建它

模型上下文协议 (Model Context Protocol, MCP) 能大幅提升连接体验。但由于框架仍在演进，一个拥有完善 OpenAPI 规范的 REST API 目前更具耐用性。

HubSpot 发布了获取实时数据的“远程服务器”和便于搭脚手架的“本地开发者服务器”，精准锚定了实际用例。

决定构建时，借助 Gram 或 FastMCP 等工具可提升效率。核心是策展：与其暴露 200 个零散端点，不如提供 5-30 个面向业务结果的聚合工具。

对于大多数公司，合理的顺序是：完善 OpenAPI、错误提示和 llms.txt。出现明确需求时再构建 MCP 服务器。 半成品的 MCP 反而会破坏体验。

Skills（技能）：以 100 倍规模教智能体做你的工作

工程师职责正转变为构建并规模化编排智能体。为防止大规模并行走向混乱，Skills（技能） 应运而生。

什么是 Skills？

Skills 是专为智能体准备的指令包：Markdown 文件（可选地附带脚本和资源）。遇到特定任务时，智能体会加载相应的 Skill 上下文并精准操作。这具有极高的 Token 效率：平时只读简短描述，按需才加载完整内容。

智能体 Skills 生态系统

像 agent-skills 平台让安装 Skills 如 npx skills add 般简单。这让 API 在执行上下文中变得可学习 (learnable)。

Apideck API Skills

我们推出了 Apideck API Skills，教导智能体如何使用 SDK、处理认证与分页。

npx skills add apideck-libraries/api-skills

Skills vs. MCP：互补，而非竞争

Skills 是制度知识层，MCP 是能力层。 MCP 提供工具，Skills 教导智能体如何用好它们，两者天然组合。

从并行化到高杠杆

Skills 确保智能体在半夜以百倍规模运转开发闭环时，就像你亲自操刀一样精确。

CLI 的复兴

Andrej Karpathy 指出，CLI 迎来了第二春，这恰恰是因为 AI 智能体。

智能体是终端原生的，天然会用 --help、装包和管道串接。带 --help 的 CLI 具有自文档化特质，甚至能平替诸多 MCP。

Google Workspace CLI (gws) 输出结构化 JSON 且集成预建 Skills，这说明 CLI 正在成为基座接口，MCP 则是上层叠加。

npm install -g @googleworkspace/cli

API 适配顺序建议为：文档/llms.txt -> Skills -> CLI -> MCP。每一层都在叠加，且 CLI 立即可用，无需等待。

底层的转变

AX 就是要把消除开发者摩擦的理念，平移到无法自行变通的自动化消费者身上。

为了让机器读懂你的 API 所做的优化，与让一个新手开发者看懂所做的努力，本质是不谋而合的。

如果这篇文章对你有帮助，欢迎点个赞 :)