AI Agent 真正读懂一个 API 所需的 8 个上下文层

一个 API 即使为人编写了完美的文档，对 AI Agent 来说仍可能几乎无法使用。

OpenAPI 描述的是接口——路径、方法、schema。但一个 Agent 需要的远不止这些：意图级别的描述、机器可读的身份认证、错误恢复提示、安全分类。"给人看的文档"和"Agent 能理解的文档"之间的差距，不在于模型的智能程度，而在于缺失的上下文层。

本文识别了决定自主 Agent 能否发现、理解并成功使用你 API 的 8 个上下文层。

Agent 上下文流

当 Agent 收到一个任务——"找一个支付 API 并处理退款"——它会经历一条决策链：

Agent
  ↓
"Where is the API?"          → Discovery
  ↓
"What can I do here?"        → Capabilities
  ↓
"What do I need to provide?" → Inputs
  ↓
"Do I have permission?"      → Authentication
  ↓
"What does this mean?"       → Semantics
  ↓
"What will I get back?"      → Output
  ↓
"What if something breaks?"  → Errors
  ↓
"Is it safe to do this?"     → Safety
  ↓
SUCCESS / FAILURE

每一层都是一个潜在的失败点。人类开发者会用经验和直觉来弥补。而 Agent 只能依赖机器可读形式中明确表示的内容。

1. Discovery — "这个 API 是什么？"

Agent 找不到的 API 就无法使用。机器可读的可发现性是第一层。

糟糕：没有 llms.txt，没有 .well-known 端点，没有 ai-sitemap.xml。API 对自主发现完全不可见。人类可能会用 Google 搜索，但运行在管道中的 Agent 不行。

更好：在根目录放置 llms.txt 提供 API 摘要。提供 /.well-known/openapi 或 /.well-known/service-desc 用于 spec 发现。提供 ai-sitemap.xml 列出 API 端点。从主页添加 link rel="service"。

为什么 Agent 关心这一点：没有可发现性，Agent 在第一步就停住了。如果 Agent 找不到你的 OpenAPI，它再好也没用。Discovery 是所有后续层的前提。

2. Capabilities — "我能在这里做什么？"

Agent 在意图层面而非 HTTP 方法层面规划动作。POST /orders —— 这是创建、更新还是处理？

糟糕：仅列出端点。Agent 看到 HTTP 方法但不理解意图。它可以调用端点但不知道它完成什么。

更好：将 Capability 描述映射到端点："搜索产品"、"创建订单"、"查询订单状态"、"取消订单"。每个 capability 都有人类可读的描述和机器可读的意图。

为什么 Agent 关心这一点：Agent 将任务分解为子目标。"处理退款"会变成：查找订单 → 检查状态 → 发起退款。没有 capability 级别的描述，Agent 就无法将子目标映射到你的端点。

3. Inputs — "我需要提供什么？"

Agent 无法读懂言外之意。空的描述 "" 意味着 Agent 不知道该发送什么。

customer_id:
  type: string
  description: ""

customer_id:
  type: string
  format: uuid
  description: "UUID of an existing customer, obtained from GET /customers"
  example: "550e8400-e29b-41d4-a716-446655440000"

为什么 Agent 关心这一点：没有描述，Agent 只能猜测。它可能发送客户邮箱而不是 UUID。它可能遗漏必填字段。每个缺失的描述都是 Agent 无法诊断的潜在运行时错误。

4. Authentication — "我有权限吗？"

认证是 Agent 最主要的失败原因之一。它们需要机器可读的身份认证元数据才能自主认证。

糟糕：人类可读的 OAuth 文档，包含浏览器重定向流程。Agent 无法执行浏览器步骤。它收到 401 就停了。

更好：在 OpenAPI 中使用 securitySchemes 并提供完整流程描述。提供 /.well-known/oauth-authorization-server（RFC 8414），用于机器可读地发现 token 端点、scope 和授权类型。

为什么 Agent 关心这一点：如果 Agent 无法自主认证，它就完全无法使用 API。基于浏览器的 OAuth 流程是为人类点击"授权"设计的。Agent 需要 token 端点、客户端凭证和机器可读的 scope 描述。

5. Semantics — "这个操作实际上意味着什么？"

这对自主 Agent 至关重要：操作安全吗？能重试吗？有副作用吗？会扣钱吗？

POST /api/v2/process:
  summary: "Process"
  description: ""

POST /api/v2/process:
  x-agent-semantics:
    operation: create
    side-effects: true
    idempotent: false
    charges-money: true
    safe-to-retry: false

为什么 Agent 关心这一点：没有语义元数据，对 Agent 来说 DELETE /account 和 GET /account 都只是 HTTP 请求。但风险完全不同。Agent 需要知道：我能重试吗？重试会重复扣费吗？这是破坏性的操作吗？

6. Output — "我会得到什么？"

Agent 需要操作链。不仅要回答"返回了什么"，还要回答"接下来做什么"。

responses:
  '200':
    description: "OK"
    schema:
      type: object

responses:
  '200':
    description: "Order created successfully"
    schema:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: "Order ID for tracking"
        status:
          type: string
          enum: [pending, confirmed, shipped]
        next_actions:
          type: array
          items:
            type: object
            properties:
              action:
                type: string
                enum: [confirm, cancel, track]
              endpoint:
                type: string

为什么 Agent 关心这一点：没有结构化输出，Agent 收到一团 JSON，不知道下一步该用哪些字段。next_actions 告诉 Agent 在这个响应之后可以做什么——支持自主的多步骤工作流。

7. Errors — "出了问题怎么办？"

好的 Agent API 不仅描述如何成功，还描述如何恢复。没有结构化错误响应，Agent 无法程序化地确定原因并修复。

400 Bad Request
{"error": "invalid_request"}

{
  "type": "https://agentbadge.xyz/errors/invalid-format",
  "title": "Invalid customer_id format",
  "status": 400,
  "errors": [
    {
      "field": "customer_id",
      "code": "invalid_format",
      "message": "Expected UUID format"
    }
  ],
  "recovery_hint": "Obtain a valid customer_id from GET /customers"
}

为什么 Agent 关心这一点：没有结构化错误，Agent 看到"400 Bad Request"就停了。它不知道哪个字段出错了，也不知道怎么修复。RFC 9457 Problem Details + 字段级错误 + 恢复提示使自主错误修正成为可能。

8. Safety — "做这件事安全吗？"

对 Agent 来说 DELETE /account 和 GET /account 都是 HTTP 请求，但没有安全分类的话风险完全不同。

糟糕：没有安全分类。Agent 将所有操作一视同仁。它可能会因为超时而重试一个破坏性操作。

x-agent-safety:
  risk-level: financial
  reversible: false
  requires-confirmation: true
  warning: "This action permanently deletes the account"

安全级别：只读 → 写入 → 破坏性 → 金融 → 不可逆。

为什么 Agent 关心这一点：Agent 会在超时时重试。如果 DELETE 操作被重试，数据就会丢失。安全分类告诉 Agent："不要重试这个"、"需要确认"或"这个可以安全重复"。

Version A vs Version B

考虑两个具有相同 OpenAPI 结构的 API：

Version A — 仅 OpenAPI：

• Schemas：✅（但描述为空）
• Security schemes：✅（但没有 .well-known）
• 没有错误恢复提示
• 没有安全分类

Version B — OpenAPI + Agent 上下文：

• 带有完整描述、示例和约束的 Schemas：✅
• /.well-known/oauth-authorization-server：✅
• 每个操作都有 x-agent-semantics：✅
• 带恢复提示的 RFC 9457 Problem Details：✅
• x-agent-safety 分类：✅
• 带 API 摘要的 llms.txt：✅

拿到 Version A 的 Agent 会在第 3 步（Inputs）失败——它不知道该发送什么。拿到 Version B 的 Agent 可以自主发现、认证、调用、从错误中恢复并安全行动，无需人工干预。

差异不在于模型。差异在于上下文。

这就是 Agent Readiness

这 8 个上下文层不是一个愿望清单。它们是可量化的属性。Agent Readiness 是一个衡量 API 是否为自主使用提供了足够上下文的框架。

Agent Readiness 用确定性、基于证据的规则检查每一层：

• Discovery：llms.txt 是否存在？/.well-known/openapi 能否解析？
• Capabilities：操作描述是否非空且为意图级别？
• Inputs：schema 属性是否有描述、示例和约束？
• Authentication：securitySchemes 是否已填充？.well-known/oauth-authorization-server 是否存在？
• Semantics：是否存在 x-agent-semantics 或等效扩展？
• Output：响应是否包含带 next_actions 的完整 schema？
• Errors：错误响应是否结构化（RFC 9457）并带有恢复提示？
• Safety：是否存在 x-agent-safety 或等效分类？

72 项检查，秒级完成。免费，无需注册。

npx @agentbadge/cli scan https://api.example.com

本文定义了 8 个上下文层。下一个问题是：我们能测量它们吗？

在下一篇文章——《能测量 Agent Readiness 吗？》——中，我们将探索 AgentBadge 如何将这 8 层转化为 72 项确定性检查，每项都有证据、修复示例和 0 到 100 的评分。

• What Is Agent Readiness? — 第 1 篇：基础概念
• API Has SEO Agent Readiness — 第 2 篇：SEO vs Agent 发现
• The Web Is Becoming Agentic — 第 3 篇：代理化网络与 API 发现
• From SEO to GEO to Agent Readiness — 第 4 篇：优化的演进
• Why AI Agents Fail to Use APIs — 第 5 篇：这 8 层解决的 7 个失败模式

不要认证。要测量。

Originally published at AgentBadge