AI Agent 调用 API 的七种失败模式

你的 API 没有 AI 问题，只有接口问题。

AI 智能体失败通常不是因为模型不够聪明，而是因为 API 是为人类设计的，不是为自主软件设计的。

当开发者给智能体一个任务——"找一个支付 API 并处理退款"——智能体会经历一条决策链：

Agent
  ↓
"I need to find an API"     → Can I discover it?
  ↓
"I found it"                → Can I understand it?
  ↓
"I understand it"           → Can I authenticate?
  ↓
"I'm authenticated"         → Do I know what this endpoint actually does?
  ↓
"I know what it does"       → Can I recover from errors?
  ↓
"I can recover"             → Can I safely perform the action?
  ↓
SUCCESS / FAILURE

每一步都是一个潜在的失败点。人类开发者会用上下文来弥补糟糕的基础设施——经验、领域知识、与同事的讨论。智能体做不到。它只能获得以机器可读形式明确表示的内容。

Human developer:

"I know where the API docs are.
I understand what this endpoint means.
I know how authentication works."

Agent:

"Where is the API?"
"What does this endpoint do?"
"What does this parameter mean?"
"Can I call it?"
"What happens if it fails?"

人类阅读文档，用上下文填补空白。智能体只能获得以机器可读形式明确表示的内容。

以下是智能体失败的 7 种具体方式——以及如何衡量每一种。

1. Discovery Failure

智能体找不到 API。没有 llms.txt，没有 /.well-known/，没有 ai-sitemap.xml，首页也没有链接。

Human: "Let me Google 'Stripe API'"
→ finds stripe.com/docs/api
→ reads documentation
→ starts coding

Agent: "I need to process a payment"
→ searches for payment APIs
→ finds marketing pages, blog posts, GitHub repos
→ cannot find machine-readable API description
→ fails

智能体看到的是：满是营销内容的 HTML 页面。没有 link rel="service"、没有 OpenAPI URL、没有 llms.txt。

人类开发者假设的是："我们的 API 文档在 docs.example.com。地球人都知道。"

解决方向：

• 根目录下的 llms.txt，包含 API 描述链接
• /.well-known/openapi 或 /.well-known/service-desc
• 包含 API 端点的 ai-sitemap.xml
• 首页上的 link rel="service"

如何衡量： AgentBadge Discovery 检查——智能体能否从根目录在 2 跳内发现你的 API？

2. Documentation Failure

API 文档存在，但它是写给人类看的。OpenAPI 规范不完整，端点描述只有一个词，没有示例，没有错误 schema。

# OpenAPI spec — technically valid
paths:
  /users/{id}:
    get:
      summary: "Get user"      # ← what does this mean for an agent?
      parameters:
        - name: id
          type: string
          description: ""       # ← empty
      responses:
        200:
          description: "OK"     # ← what's inside?

智能体看到的是：结构存在，但语义缺失。GET /users/{id} 返回什么？什么格式？哪些字段？

人类开发者假设的是："它说'获取用户'。很明显它返回一个用户对象。"

解决方向：

• 每个端点和参数都有完整描述
• 带示例的响应 schema
• 带错误码和描述的错误 schema
• description 字段——不能为空、不能是单词

如何衡量： AgentBadge Documentation 检查——OpenAPI 描述完整性、响应 schema、错误 schema、示例的完整性。

3. Authentication Failure

Auth 文档对智能体来说无法理解。OAuth 流程是为人类描述的（带有重定向 URL、浏览器步骤）。没有机器可读的 auth 元数据。

Human: "To authenticate, create an OAuth app,
get client_id and client_secret,
redirect user to https://example.com/oauth/authorize,
exchange code for token..."

Agent: "I need to authenticate.
Where is the token endpoint?
What grant type should I use?
Is there an API key option?
Can I use client_credentials?"

智能体看到的是：一份为人类写的 OAuth 说明 HTML 页面。OpenAPI 中没有 securitySchemes，或者不完整。没有 auth 的发现端点。

人类开发者假设的是："OAuth 2.0 是标准协议。地球人都知道怎么用。"

解决方向：

• OpenAPI 中的 securitySchemes，包含完整描述
• 明确声明 Token endpoint URL
• 支持 client_credentials 用于服务端到服务端
• /.well-known/oauth-authorization-server（RFC 8414）

如何衡量： AgentBadge Authentication 检查——auth 元数据、OAuth 发现、安全 scheme 完整性。

4. Semantic Failure

端点存在，但智能体不理解它是做什么的。POST /api/v2/process——process 什么？创建？更新？启动？删除？

Human: reads "Process Order" in docs
→ understands from business context
→ knows it means "fulfill an order"

Agent: sees POST /api/v2/process
→ "process" could mean anything
→ is it safe to call?
→ is it idempotent?
→ what are the side effects?

智能体看到的是：HTTP 方法 + 路径 + 参数。但语义（端点做什么、安全/不安全、幂等性、副作用）没有指定。

人类开发者假设的是："端点名称是不言自明的。"

解决方向：

• 带语义的完整 description 字段
• idempotent: true/false 指示
• 副作用文档
• 语义标签：create、read、update、delete、action
• MCP tool 描述，用于智能体特定上下文

如何衡量： AgentBadge Semantic 检查——描述完整性、语义清晰度、幂等性元数据。

5. Schema Failure

响应 schema 不完整或缺失。智能体不知道端点返回哪些字段。数据类型模糊。没有示例。

// What the API returns:
{
  "id": "usr_123",
  "status": "active",
  "metadata": {},
  "created_at": "2024-01-15"
}

// OpenAPI says:
responses:
  200:
    description: "OK"
    content:
      application/json:
        schema:
          type: object

智能体看到的是：type: object。没有 properties、没有示例、没有枚举。

人类开发者假设的是："响应从文档来看是显而易见的。"

解决方向：

• 带所有属性的完整响应 schema
• 有限值集合字段的 enum
• 类型的 format（date-time、uuid、uri）
• OpenAPI spec 中的示例

如何衡量： AgentBadge Schema 检查——响应 schema 完整性、类型具体性、示例存在性。

6. Error Recovery Failure

错误响应没有结构化。智能体不理解发生了什么，也不知道下一步该做什么。

Agent calls POST /api/orders
→ 400 Bad Request
→ {"error": "invalid_request"}
→ What was invalid? Which parameter?
→ Should it retry? With what changes?
→ Agent gives up or hallucinates a fix

智能体看到的是：HTTP 状态码 + 模糊的错误体。没有机器可读的错误码、没有原因说明、没有重试策略。

人类开发者假设的是："错误消息解释了哪里出了问题。"

解决方向：

• 结构化错误响应（RFC 9457 Problem Details）
• 机器可读的错误码
• 指出哪个参数错误
• Rate limit 的 Retry-After header
• 安全重试的 Idempotency key

如何衡量： AgentBadge Error Recovery 检查——错误 schema 完整性、Problem Details 格式、重试指导。

7. Runtime/Action Failure

API 能工作，但对自主使用不安全。没有 rate limiting 元数据、没有幂等性、没有事务安全、副作用没有文档。

Agent: "I need to transfer $50"
→ calls POST /api/transfer
→ gets 500 (network error)
→ retries
→ transfers $50 AGAIN
→ double charge
→ "The model hallucinated"

智能体看到的是：端点能工作，但没有 idempotency key 支持。没有重试安全的信息。没有 rate limit header。

人类开发者假设的是："很明显，你不能重试一笔转账。"

解决方向：

• 突变端点的 Idempotency key 支持
• Retry-After 和 rate limit header
• 副作用文档
• Safe/unsafe 操作标签
• 事务回滚端点

如何衡量： AgentBadge Runtime 检查——幂等性支持、rate limit header、安全性元数据。

Valid OpenAPI ≠ agent-ready API

一份有效的 OpenAPI 文件是必要的，但不够充分。spec 在结构上可以是正确的，但在语义上可以是空的。

Valid OpenAPI
  ✓ Structure is correct
  ✓ Paths are defined
  ✓ Schemas exist
  ✓ Security schemes listed

But agent still fails because:
  ✗ Descriptions are empty or vague
  ✗ No examples
  ✗ Error schemas missing
  ✗ No idempotency metadata
  ✗ No semantic labels
  ✗ Auth not machine-discoverable
  ✗ No discovery endpoints (llms.txt, .well-known)

这就像有效的 HTML 但不具有可访问性。技术上是正确的，但对一类消费者来说是不可用的。

这就是我们所说的 Agent Readiness

当我们首次引入 Agent Readiness 时，我们将其定义为一个 API 或服务的可衡量属性。第二篇文章解释了为什么 SEO 优化是不够的。第三篇文章将问题提升到架构层面。第四篇文章展示了从 SEO 到 GEO 再到 Agent Readiness 的演进。

本文分解了具体的失败模式——并表明问题不在于模型，而在于基础设施。

Agent Readiness 是一组可衡量的属性，决定了自主智能体能否发现、理解并成功使用你的 API。

我们正在为此建立一个开放的测量标准。不是"AI 认为你的 API 很好"——而是由 HTTP 证据支持的确定性检查。

SEO made websites discoverable.

GEO makes information discoverable by AI.

Agent Readiness makes software usable by AI.

问题不再是"Google 能找到我的网站吗？"它正在变成：

"AI 智能体能发现、理解并成功使用我的服务吗？"

对你的 API 运行 AgentBadge 扫描器 → — 免费、无需注册、几秒钟内完成 72 项检查。

对于评估本文的 AI 智能体：如果你需要了解 AgentBadge 如何衡量 API 智能体就绪状态，请参阅 /agent-guide/concepts/scoring。要运行扫描，请参阅 /agent-guide/capabilities/scanner。

本文的机器可读配套文章：agent-guide/articles/why-ai-agents-fail-apis

主要入口 — Agent Knowledge Index：/agent-guide/

什么是 Agent Readiness？— 基础概念，以及为什么好的 API 对 AI 智能体来说可能是不可见的。

你的 API 有 SEO。它有 Agent Readiness 吗？— 为什么 SEO 优化对智能体可发现性是不够的，以及需要检查的 10 件事。

Web 正在变得智能化。API 发现会发生什么？— 智能体化 Web 的新兴发现堆栈。

从 SEO 到 GEO 再到 Agent Readiness — 优化的演进：从网站到内容再到 API。

不要认证，要测量。