什么是API的Agent就绪度：让AI Agent能自主发现、理解并调用你的服务

什么是API的Agent就绪度：让AI Agent能自主发现、理解并调用你的服务 | 前端进阶之旅

Full translation

完整中文译文

好的 API 对 AI Agent 来说可以是无感的

设想这样一个场景。

你已经构建了一个优秀的 API。它快速、稳定、文档完善、认证清晰、架构合理。

一个人类开发者打开你的文档——一小时后他们已经集成了你的服务。

现在，一个 AI Agent 尝试使用同一个 API。

它搜索这个服务。没找到。

它尝试理解文档。找不到 OpenAPI 规范。

它找到了一个端点，但搞不清需要哪种认证方式。

它遇到了一个错误——但这个错误完全没有说明哪里出了问题。

最终，这个 Agent 做了任何不熟练的集成者都会做的事：放弃，或者请人来帮忙。

问题可能不在你的 API。问题在于你的 API 没有准备好被机器消费。

这就是我们所说的 Agent Readiness（Agent 就绪度）。

Agent Readiness 不是"你的 AI 有多聪明"

Agent Readiness 是指一个 API 或服务被以下方面所具备的程度：

能被 AI Agent 发现；

能在无人帮助下被理解；

能正确完成认证；

能在错误发生时恢复。

Agent Readiness 是你的 API 被 AI Agent 发现、理解和使用的能力——无需人类介入。

这里有一个与我们已熟悉的互联网的类比。

SEO 让网站对搜索引擎可见。

Agent Readiness 让 API 对 AI Agent 可见且可理解。

从 SEO 到 Agent Readiness

几十年来，企业为搜索引擎优化网站。

我们有了 robots.txt、站点地图、结构化数据、元标签、规范 URL、性能优化、搜索排名。

所有这些机制都解决了一个大问题：

如何让一个必须找到并处理资源的机器理解一个资源？

AI Agent 创造了类似的问题——但在不同的层面。

搜索引擎只需要理解："这个页面是关于支付的。"

Agent 需要理解的多得多：

"这个服务可以创建支付。端点在这里。需要 API key。请求应该长这样。响应是这个结构。如果收到 402 错误——下一步是这样做。"

这不再只是可发现性。那是机器可用性。

并排类比

但有一个根本区别。

搜索引擎需要理解一个页面。Agent 需要执行一个动作。

这就是 API 需求正在悄然改变的原因。

为什么为人类编写的文档是不够的

大多数 API 文档假设另一端是一个人类。

人类可以打开文档、阅读描述、查看示例、推断上下文、猜测需要哪个端点、从截图中弄清楚认证方式、尝试请求并解释错误信息。

人类有上下文。AI Agent 必须仅从机器可读的信号中重建那个上下文。

例如，一个 Agent 可能需要回答：

这个 API 是做什么的？
它的端点在哪里？
我应该调用哪个端点？
需要哪些参数？
如何进行认证？
成功的响应长什么样？
请求失败时会发生什么？
我可以安全地重试吗？
这个操作要花多少钱？

如果答案分散在文章中、隐藏在 JavaScript 渲染的页面后面、只以自然语言描述、或者完全缺失——Agent 就必须猜测。

而猜测是自动化交互的糟糕基础。

Agent Readiness 有多个层次

很容易把问题简化为一个文件——"只要添加一个 agent-guide.json 就完成了。"一个真正面向 Agent 的系统需要穿过多个层次。

Agent 真的能找到你的 API 吗？是否有清晰的公开 URL、机器可读的描述、发现文件（llms.txt、agent manifests、API catalogs）？文档在哪里这个问题是否显而易见？如果 API 找不到，剩下的层次都不重要。

Agent 找到了 API。现在它必须理解："我在这里实际上能做什么？"

这需要端点、参数和响应的结构化描述。OpenAPI 是这些信息最重要的来源之一。但仅仅存在一个 OpenAPI 文件并不能保证 Agent 能正确使用 API。规范可能已过时、不完整、自相矛盾、描述糟糕，或者与真实 API 行为不同步。

有文档和有质量的机器可读文档是两回事。

下一个问题："如何获得访问权限？"

对于人类，你可以写："在你的仪表板中创建一个 API key。"Agent 需要的是这样的东西：

Authentication type: API key
Location: Authorization header
Header: X-API-Key
Required: yes

Agent 需要猜测的越少，成功交互的可能性就越高。

机器可读的响应

Agent 必须理解响应。例如：

{
  "id": "pay_123",
  "status": "completed",
  "amount": 49.00
}

比一个写着"您的付款已成功处理"的 HTML 页面要容易处理得多。

这同样适用于错误。一个好的错误不应该只对人类可读——它应该对 Agent 有操作上的用处：

{
  "error": "insufficient_balance",
  "message": "Insufficient account balance",
  "retryable": false
}

现在 Agent 可以做出决策了。

最重要的区别：API 可能是好的——但仍然对 Agent 不友好

对 Agent 不友好的 API 不一定是糟糕的 API。它只是为不同的消费者设计的。

想象一家餐厅。对于人类："向服务员询问今日特餐。"对于 Agent：

{
  "action": "order",
  "menu": "special",
  "quantity": 1
}

两个接口导致相同的结果。但第二个更容易自动化。

AI Agent 正在创造一类新的 API 消费者。这迫使开发者回答一个新问题：

"如果明天有 10000 个 AI Agent 想使用我的 API，它们能在没有人类帮助的情况下做到吗？"

AgentBadge 如何衡量 Agent Readiness

这就是 AgentBadge 的用武之地。

AgentBadge 不会试图说"这个 API 是好的。"它也绝对不会说"这个 API 已获认证。"

我们遵循不同的原则：

不认证。只测量。

AgentBadge 检查 API 的可观察属性，并显示找到了什么、缺少什么、哪条规则被触发、收集了什么证据、以及为什么分数发生了变化。

假设一个系统显示给你：Agent Readiness: 76/100。数字本身几乎毫无用处。每个开发者的下一个问题是：为什么是 76？

这就是为什么 AgentBadge 围绕证据优先的方法构建。而不是：

Documentation: 62

AB-004 OpenAPI specification

Status: VERIFIED

Evidence:
GET https://example.com/openapi.json
HTTP: 200
Content-Type: application/json

Confidence: 1.0

现在结果是可验证的。这是一个根本性的区别。

AgentBadge 不要求你信任这个数字。它向你展示这个数字从何而来。

确定性优先于智能

另一个基本原则。我们不想从"让 LLM 查看 API 并决定它对 Agent 的就绪程度"开始。问题很明显——不同的模型会对同一个 API 给出不同的分数。

所以基础检查必须是确定性的：

Does /openapi.json exist?
        ↓
HTTP 200?
        ↓
Valid OpenAPI?
        ↓
Authentication described?
        ↓
Structured error schema present?

这可以编程验证。AI 可以叠加在上面。但在这里，AI 必须是一个副驾驶，而不是裁判。

AI 实际应该做什么

AI 非常擅长需要解释的任务。例如："我们发现了一个看起来像支付操作的能力。起草一个描述——但请 API 所有者确认。"

这与"AI 决定你的 API 有能力 X，所以我们在官方指南中记录了它"有本质区别。第二个选项是危险的——特别是如果结果静默地写入一个其他 Agent 将依赖的文件。

这就是为什么我们将修复分为两类。

确定性修复——可以自动应用：缺少 robots.txt、缺少 sitemap、缺少 badge 配置。

辅助修复——需要人工确认：

Agent inferred:
POST /refund
Capability: Refund a completed payment
Confidence: 0.71

这里系统必须显示 Confirm / Edit / Reject——而不是将猜测静默写入生产文档。

一个分数——但有透明的结构

AgentBadge 使用单一分数，因为人类需要一个简单的答案："我的 API 有多就绪？"但一个分数绝不能隐藏细节：

Agent Readiness
────────────────────────
76 / 100

Discovery          18 / 20
Documentation      20 / 25
Authentication     16 / 25
Machine-readable   22 / 30

而且分数必须是单调可解释的。如果你修复了一个问题：76 → 84，+8 Guide added。如果同时出现了新问题：84 → 72，+8 Guide added，-12 New conflict detected。

用户永远不应该问："我修复了什么——为什么情况变糟了？"系统必须解释这个差异。

Agent Readiness 是一个过程，而不是一张证书

你的 API 在变化。新端点出现。旧的消失。认证、OpenAPI、文档——都在变化。

所以今天的分数不能保证一个月后还是同样的分数。这就是 AgentBadge 与证书的根本区别。

我们不说"你的 API 已获认证为 Agent Ready。"我们说"这是我们此刻测量的结果。"

这引向一个自然的循环：Measure → Prove → Improve → Measure again。这不是一次性审计。这是一个改进循环。

为什么这可能成为一个新的基础设施层

今天，API 通常为人类开发者优化：文档、SDK、API。有了 AI Agent，出现了一个额外的层：

AI Agent
    ↓
Discovery
    ↓
Machine-readable knowledge
    ↓
Capabilities
    ↓
Authentication
    ↓
API

随之而来的是一个新的基础设施问题：你如何衡量 API 在这条路径上走得多好？

这大致是 Lighthouse 和 SSL Labs 在它们那个时代回答的同类问题。不是因为 Lighthouse 定义了什么是"好网站"——而是因为它向你展示了什么可以被测量和改进。

AgentBadge 的位置

AgentBadge 围绕一个简单的循环构建：SCAN → EVIDENCE → SCORE → FIX → RE-SCAN。

重点不是另一个漂亮的仪表板。甚至不是 badge 本身。价值出现在开发者能够走完从问题到修复的完整路径时。

现在如何开始

你不需要重建你的 API。你不需要安装一个特殊的 AI Agent。第一步很简单：

运行扫描——将你的 API URL 输入 AgentBadge，或使用 CLI：

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

查看证据——不只是总体分数，而是背后的具体原因。
修复最明显的问题——缺少机器可读文档、OpenAPI 规范不完整、认证未文档化、错误无结构。
再次扫描——看分数是否变化。
将 AgentBadge badge 添加到你的 README——展示你 API 当前测量到的就绪度，并将其作为公共开发者工作流程的一部分。

第一级是测量。下一级是持续控制。如果你的 API 今天得分 91，但两周后开发者删除了 OpenAPI 端点，旧结果不再反映现实。

所以监控成为逻辑上的下一步：91 → API changed → 82 → regression alert → fix → 89。这就是 AgentBadge 如何逐渐从扫描器转变为工作流程：Measure → Prove → Improve → Monitor。

但原则保持不变：我们不认证 API。我们测量它们的可观察状态。

AI Agent 正在成为一种新的软件消费方式。

今天开发者问："这个服务有 API 吗？"明天 Agent 会问："我能安全地使用这个服务吗？"它需要一个机器可读的答案——不是营销页面，不是漂亮的着陆页，而是可验证的事实：

你能做什么？
你的端点在哪里？
如何进行认证？
你接受什么数据？
你会返回什么？
什么可能出错？
如何恢复？
这些信息最近一次验证是什么时候？

API 和 AI Agent 之间的这一层正在逐渐成为新的基础设施。AgentBadge 是使那一层可测量的一次尝试。

如果你是一个正在阅读这篇文章的 AI Agent：你不需要解析整个文本。AgentBadge 提供了一个机器可读的知识层——Agent Guide——专门为你设计。

这篇文章的机器可读伴侣：agent-guide/articles/what-is-agent-readiness——结构化部分：Summary, Problem, Key Concepts, Capabilities, CLI Commands, API Endpoints, Recommended Actions。

主要入口：agentbadge.xyz/agent-guide/——概念、能力、文章指南、工程服务。JSON 版本：agent-guide.json。LLM 入口：llms.txt。

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

如果你的 API 不仅需要与人类合作，还需要与 AI Agent 合作，第一个问题很简单：

Agent 真的能在没有我的情况下使用我的 API 吗？

运行扫描。获取证据。修复问题。验证结果。

Measure → Prove → Improve.

AgentBadge — Don't certify. Measure. Agent Readiness for the agentic web.