agent-protocols

Agent 协议

修复 IsAgentReady.com 的 Agent 协议类别。这些检查点用于测试 Agent 是否能通过标准协议发现并使用网站的功能。

• 方法论版本：2026-10-22。方法论：https://isagentready.com/en/methodology
• 评分（权重和分数）：https://isagentready.com/api/v2/methodology/2026-10-22/scoring
• 完整检查点数据（阶段、证据类型、验证命令、重新扫描命令）：references/checkpoints.md

许多检查点仅适用于已检测到的界面（API、MCP、电商）。没有 API 的内容网站可跳过这些检查点。WebMCP 结果属于实验性证据，不会影响总分。

适用情形

• 扫描显示 Agent 协议中存在失败项（旧版 ID 为 4.x）。
• 网站有表单、API、MCP 服务、Agent 或商店，且 Agent 必须使用它们。
• 用户要求处理 WebMCP、A2A、MCP、OpenAPI、API 目录、NLWeb 或 Agent 支付。

不适用情形

• 没有交互功能或 API 的静态内容网站。
• 安全标头或 OAuth 元数据：使用 security-trust。
• JSON-LD：使用 structured-data。
• robots.txt、llms.txt 或 AGENTS.md：使用 ai-content-discovery。

说明

1. 从扫描结果中获取失败的检查点。每个结果都包含一个旧版 ID（4.3）和一个稳定 ID（ia.a2a-agent-card）。
2. 使用与稳定 ID 相同的锚点，前往修复工作流。
3. 根据网站调整示例。将 example.com 替换为网站的域名。
4. 将每个 /.well-known/* 文档作为 application/json 提供。确保 WAF 和 CDN 不会拦截它。
5. 运行验证命令。所有验证命令均为只读。然后使用 isagentready results <domain> --checkpoint <stable-id> 重新扫描。

如果提供了 $ARGUMENTS，则将其用作要修复的网址或检查点。

检查点

强度是 agentready.org 规范级别（MUST、SHOULD、MAY）。强度不会改变得分。

旧版	稳定 ID	名称	AR ID	强度
4.1	ia.webmcp-declarative	WebMCP 声明式 API	AR-ACT-07	SHOULD
4.3	ia.a2a-agent-card	A2A Agent 卡片	AR-READ-06	MAY
4.4	ia.mcp-discovery	MCP 发现	AR-ACT-03, AR-ACT-10	MAY
4.5	ia.openapi	OpenAPI / API 文档	AR-ACT-02	SHOULD
4.6	ia.agents-json	agents.json	none	MAY
4.7	ia.webmcp-form-quality	声明式表单质量	AR-ACT-07	SHOULD
4.9	ia.interactive-surface-coverage	交互界面覆盖度	AR-ACT-07	SHOULD
4.10	ia.api-catalog	API 目录（RFC 9727）	AR-READ-06, AR-ACT-02	SHOULD
4.11	ia.agent-skills-index	Agent Skills 索引	AR-ACT-06	MAY
4.12	ia.x402	x402 支付	AR-ACT-08	MAY
4.13	ia.mpp	MPP（x-payment-info）	AR-ACT-08	MAY
4.14	ia.ucp	UCP	AR-ACT-08, AR-READ-06	MAY
4.15	ia.acp-manifest	ACP 清单	AR-ACT-08, AR-READ-06	MAY
4.16	ia.ap2	AP2	AR-ACT-08	MAY
4.17	ia.openapi-quality	OpenAPI 可操作性质量	AR-ACT-02	SHOULD
4.18	ia.mcp-server-card	MCP 服务卡片质量	AR-ACT-04	MAY
4.19	ia.openapi-live	实时 OpenAPI 验证	AR-ACT-02	SHOULD
4.20	ia.mcp-live	实时 MCP 验证	AR-ACT-03	SHOULD
4.21	ia.ai-catalog	AI 目录	AR-FIND-04	MAY
4.22	ia.api-errors	API 错误响应	AR-ACT-02	SHOULD
4.23	ia.api-rate-limits	API 速率限制标头	AR-ACT-02	MAY
4.24	ia.developer-docs-link	开发者文档的可发现性	AR-FIND-02, AR-READ-04	MAY
4.25	ia.mcp-apps	MCP Apps UI 资源	AR-ACT-05	MAY
4.26	ia.nlweb-ask	NLWeb ask 端点	AR-ACT-09	MAY
4.27	ia.agent-checkout	Agent 结账	AR-ACT-08	MAY
4.28	ia.sdk-cli	SDK 和 CLI	AR-ACT-06	SHOULD
4.29	ia.agent-task-access	Agent 任务访问	AR-ACT-10	MUST
4.30	ia.docs-answer	能解答问题的文档页面	AR-READ-04, AR-FIND-02, AR-READ-05	SHOULD

修复工作流：WebMCP

4.1 WebMCP 声明式 API

在表单或字段上设置 toolname 和 tooldescription，或使用 document.modelContext.registerTool() 即可通过检查。仅使用带连字符的属性（tool-name）或 navigator.modelContext 只能获得部分分数。

1. 为 Agent 需要使用的表单添加注解：

   <form action="/search" method="get" toolname="search_products"
         tooldescription="Search the product catalog by keyword and category">
     <label for="q">Search</label>
     <input id="q" name="q" toolparamdescription="Search keywords">
   </form>
   

2. 或在脚本中注册工具。请参阅 references/webmcp-guide.md。

验证：curl -sf https://example.com/ | grep -oE '<form[^>]*toolname="[^"]*"'

4.7 声明式表单质量

适用于设置了 toolname 和 tooldescription 的表单。检查要求 toolname 使用 snake_case，tooldescription 至少包含 10 个字符，每个字段都具有 name 和 <label>，且输入项设有 toolparamdescription。

1. 按照 4.1 中的表单作为范例。为每个字段添加 name、id、<label for> 和 toolparamdescription。

验证：curl -sf https://example.com/ | grep -oE 'tool(name|description|paramdescription)="[^"]*"'

4.9 交互界面覆盖率

统计可见的表单、搜索输入框、操作按钮和筛选控件。工具注释覆盖这些元素时即为通过。隐藏内容、inert 内容和 template 内容不计入。

1. 按照 4.1 注释每个搜索、筛选和主要操作表单。覆盖率目标为 50% 或更高。

验证：curl -sf https://example.com/ | grep -c '<form'（与 4.1 中的工具表单数量比较）

修复工作流：Agent 和 API 发现

4.3 A2A Agent 卡片

在 /.well-known/agent-card.json（或 /.well-known/agent.json）提供包含 name、description、version、capabilities 和完整 supportedInterfaces 条目的 A2A 1.0 卡片即为通过。旧版 0.3 卡片可获得部分分数。

1. 发布卡片：

   {
     "name": "Example Support Agent",
     "description": "Answers order and product questions",
     "version": "1.0.0",
     "capabilities": { "streaming": false, "pushNotifications": false },
     "supportedInterfaces": [
       { "url": "https://example.com/a2a/v1", "protocolBinding": "JSONRPC", "protocolVersion": "1.0" }
     ],
     "skills": [{ "id": "order_status", "name": "Order status", "description": "Get the status of an order" }]
   }
   

验证：curl -sf https://example.com/.well-known/agent-card.json | jq -e '.name and .description and .version and .capabilities and (.supportedInterfaces | length > 0)'

4.4 MCP 发现

当 /.well-known/mcp.json、/.well-known/mcp/server-card.json 或 /.well-known/mcp/server-cards.json 包含 name 或 serverInfo.name 时即为通过。旧版 mcpServers 映射也可通过。

1. 发布服务卡片（SEP-1649）：

   {
     "name": "com.example/catalog",
     "title": "Example catalog",
     "version": "1.0.0",
     "description": "Search products and read order status",
     "remotes": [{ "type": "streamable-http", "url": "https://example.com/mcp" }]
   }
   

验证：curl -sf https://example.com/.well-known/mcp/server-card.json | jq -e '.name // .serverInfo.name'

4.18 MCP 服务卡片质量

当 4.4 找到卡片时适用。检查内容包括身份信息和版本、传输类型和端点、功能、身份验证元数据，以及描述或说明。

1. 在 4.4 的卡片中添加 capabilities（例如 { "tools": {} }）以及 remotes[].headers 中的身份验证标头。参见 references/a2a-mcp-guide.md。

验证：curl -sf https://example.com/.well-known/mcp/server-card.json | jq -e '.version and .description and (.remotes | length > 0)'

4.20 MCP 实时验证

扫描器会连接到同源的 Streamable HTTP 端点。它只发送发现请求和列表请求，不会调用任何工具。

1. 在与卡片同源的位置提供 MCP 端点，例如 https://example.com/mcp。
2. 支持 server/discover（MCP 2026-07-28）或 initialize。对于未知方法，返回方法未找到（HTTP 404，JSON-RPC 错误）。

验证：MCP 需要 POST 请求，因此不存在只读的 shell 检查。请使用重新扫描命令。

4.25 MCP Apps UI 资源

当 4.20 验证 MCP 端点后适用。tools/list 中的工具包含 _meta.ui.resourceUri，或 resources/list 中存在返回 text/html;profile=mcp-app 的 ui:// 资源时即为通过。

1. 将工具关联到 UI 资源：

   { "name": "show_order", "description": "Show an order", "_meta": { "ui": { "resourceUri": "ui://orders/detail" } } }
   

2. 通过 resources/read 提供 ui://orders/detail，MIME 类型为 text/html;profile=mcp-app。

验证：MCP 需要 POST 请求，因此不存在只读的 shell 检查。请使用重新扫描命令。

4.5 OpenAPI / API 文档

在 /openapi.json、/openapi.yaml、/swagger.json、/api-docs 或 /.well-known/openapi 提供 OpenAPI 3.x 即为通过。Swagger 2.x 可获得部分分数。HTML（例如 Swagger UI）不计入。

1. 以 JSON 格式提供规范。完整示例见 references/a2a-mcp-guide.md。

   { "openapi": "3.1.0", "info": { "title": "Example API", "version": "1.0.0" },
     "servers": [{ "url": "https://example.com/api" }], "paths": {} }
   

验证：curl -sf https://example.com/openapi.json | jq -e '.openapi | startswith("3.")'

4.17 OpenAPI 可操作性质量

适用于有效的 OpenAPI JSON。每个操作都需要 operationId、摘要或描述、类型化参数、2xx 响应架构和错误模型。

1. 完善每个操作：

   "/products": { "get": { "operationId": "listProducts", "summary": "List products",
     "parameters": [{ "name": "q", "in": "query", "schema": { "type": "string" } }],
     "responses": { "200": { "description": "Products", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductList" } } } },
       "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }
   

验证：curl -sf https://example.com/openapi.json | jq '[.paths[][] | objects | select(.operationId == null)] | length'（预期为 0）

4.19 实时 OpenAPI 验证

扫描器会选择一个同源的 GET 请求，该请求不需要身份验证、路径参数、必填输入或请求正文。它会检查文档中说明的 2xx 状态码和媒体类型。

1. 为一个公开的 GET 请求编写文档，例如返回文档中所述 2xx 响应和内容类型的 GET /api/status。

验证：curl -sf https://example.com/openapi.json | jq -r '.paths | to_entries[] | select(.value.get) | .key' | head -5

4.22 API 错误响应

当 4.5 检测到 OpenAPI 时适用。扫描器会在 API 基础路径下请求一个不存在的路径。返回 404 或 410，且 JSON 响应正文包含 title、detail、error、message、code、type 或 status 即可通过。

1. 为未知 API 路径返回问题详情：

   { "type": "about:blank", "title": "Not Found", "status": 404, "detail": "No route for /api/unknown" }
   

验证：curl -s -H 'Accept: application/json' https://example.com/api/isagentready-missing-check

4.23 API 速率限制标头

检查 4.19 和 4.22 的响应。包含 RateLimit、RateLimit-Policy 或 RateLimit-Limit 即可通过。仅包含 X-RateLimit-* 或 Retry-After 时只能获得部分分数。

1. 在 API 响应中发送标准标头：RateLimit-Policy: "default";q=60;w=60 和 RateLimit: "default";r=59;t=60。

验证：curl -sfI https://example.com/api | grep -iE '^(ratelimit|ratelimit-policy|ratelimit-limit):'

4.10 API 目录（RFC 9727）

当 /.well-known/api-catalog 返回一个 linkset 数组时即可通过。每个条目都需要 anchor，以及 item、service-desc、service-doc 或 status 中的一个或多个字段。

1. 将 linkset 作为 application/linkset+json 发布：

   { "linkset": [{ "anchor": "https://example.com/api",
     "service-desc": [{ "href": "https://example.com/openapi.json", "type": "application/openapi+json" }],
     "service-doc": [{ "href": "https://example.com/docs", "type": "text/html" }] }] }
   

验证：curl -sf -H 'Accept: application/linkset+json' https://example.com/.well-known/api-catalog | jq -e '.linkset | length > 0'

4.21 AI 目录

可通过同源 Link 关系找到，或位于 /.well-known/ai-catalog.json。检查要求包含 specVersion、数量受限的 entries 列表；每个条目都必须包含媒体类型，以及一个 url 或内嵌数据，并且 URL 必须同源。

1. 发布目录：

   { "specVersion": "1.0", "entries": [
     { "identifier": "urn:air:example.com:mcp:catalog", "displayName": "Example MCP server",
       "type": "application/mcp-server-card+json", "url": "https://example.com/.well-known/mcp/server-card.json" } ] }
   

验证：curl -sf https://example.com/.well-known/ai-catalog.json | jq -e '.specVersion and (.entries | length > 0)'

4.11 Agent Skills 索引

当 /.well-known/agent-skills/index.json（或 /.well-known/skills/index.json）包含 skills 数组时即可通过。每个条目都需要 name、type、description、url 和 digest。

1. 发布索引（v0.2.0）：

   { "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
     "skills": [{ "name": "place-order", "type": "skill-md", "description": "Place an order",
       "url": "https://example.com/.well-known/agent-skills/place-order/SKILL.md", "digest": "sha256:<64 hex>" }] }
   

验证：curl -sf https://example.com/.well-known/agent-skills/index.json | jq -e '.skills | all(.name and .type and .description and .url and .digest)'

4.6 agents.json

当 /.well-known/agents.json 或 /agents.json 中存在有效且非空的 JSON 文档时即可通过。

1. 发布 Agent 列表：

   { "agents": [{ "name": "Support agent", "url": "https://example.com/a2a/v1", "protocol": "a2a" }] }
   

验证：curl -sf https://example.com/.well-known/agents.json | jq -e 'length > 0'

4.24 开发者文档可发现性

当网站提供 API、MCP 或 A2A 接口时适用。首页链接到 /docs、/developers、/api、/api-docs、/documentation 或 /reference，或者发送带有 rel="service-doc" 的 Link 标头，即可通过。

1. 在主导航中添加文档链接：<a href="/docs">开发者文档</a>。

验证：curl -sf https://example.com/ | grep -oE 'href="/(docs|developers|api|api-docs|documentation|reference)[/"]'

4.30 能解决问题的文档页面

当 4.24 检测到文档链接时适用。扫描器会读取 1 到 3 个文档页面。页面需要返回状态码 200，包含服务器渲染的文本、标题、足够的文本内容，以及带有语言类的围栏代码块。

1. 将文档渲染为服务器端 HTML。为每个代码块标注其语言：

   <h2>Create a project</h2>
   <pre><code class="language-bash">curl https://example.com/api/projects</code></pre>
   

验证：curl -sf https://example.com/docs | grep -cE '<code[^>]*class="[^"]*language-'

4.28 SDK 和 CLI

当文档链接到 npm、PyPI、crates.io 或 Homebrew，文档展示了安装命令，或者 llms.txt 或 AI Catalog 列出了 CLI 时，即通过检查。

1. 发布 SDK 或 CLI。将安装命令添加到文档和 llms.txt：

   ## Tools
   - [CLI](https://www.npmjs.com/package/@example/cli): `npm install -g @example/cli`
   

验证：curl -sf https://example.com/llms.txt | grep -iE 'npm|pypi|crates.io|brew|cli'

4.29 任务网站的 MCP 服务或 CLI

适用于交易和任务网站。当 4.20 验证了 MCP 服务，或 4.28 找到了 CLI 时，即通过检查。

1. 为 Agent 提供一条直达网站任务的路径：经过验证的 MCP 服务（4.4 和 4.20）或 CLI（4.28）。

验证：此项检查使用 4.20 和 4.28 的结果。请使用重新扫描命令。

4.26 NLWeb ask 端点

实验性。扫描器会向 /ask?query= 发送固定且无害的 GET 请求，并在 /mcp 上查找 NLWeb ask 工具。它需要包含 schema.org results 的 JSON。

1. 提供 NLWeb ask 端点：

   { "query": "help", "results": [{ "@type": "Article", "name": "Getting started", "url": "https://example.com/docs/start" }] }
   

验证：curl -sf 'https://example.com/ask?query=help' | jq -e '.results | type == "array"'

修复工作流：Agent 商务

这些检查点仅适用于显示商务信号（Offer 或 Product JSON-LD）的网站。探测为只读操作。扫描器绝不会向商务端点发送 POST 请求。

4.12 x402 支付

当 /api、/api/v1 或 / 返回 HTTP 402，且 Payment-Required 标头中包含有效的 x402 v2 挑战（Base64 JSON）时，即通过检查。

1. 对于付费端点，返回 402，并将此 JSON 进行 Base64 编码后放入 Payment-Required 标头：

   { "x402Version": 2, "resource": { "url": "https://example.com/api/report" },
     "accepts": [{ "scheme": "exact", "network": "eip155:8453", "amount": "10000",
       "asset": "0xUSDCAddress", "payTo": "0xYourAddress", "maxTimeoutSeconds": 60 }] }
   

验证：curl -s -D - -o /dev/null https://example.com/api | grep -iE '^(HTTP/|payment-required:)'

4.13 MPP（x-payment-info）

当 /openapi.json 中的某个操作包含有效的 x-payment-info 扩展时，即通过检查。

1. 将扩展添加到付费操作中："x-payment-info": { "price": "0.01", "currency": "USD", "protocols": ["x402"] }。

验证：curl -sf https://example.com/openapi.json | jq -e '[.paths[][] | objects | has("x-payment-info")] | any'

4.14 UCP

当 /.well-known/ucp 返回包含 version 和非空 capabilities 列表的配置文件时，即通过检查。

1. 发布配置文件：{ "version": "2026-01-11", "capabilities": [{ "name": "dev.ucp.shopping.checkout" }] }。

验证：curl -sf https://example.com/.well-known/ucp | jq -e '.version and (.capabilities | length > 0)'

4.15 ACP 清单

当 /.well-known/acp.json 包含非空的 flows 列表和 capabilities 对象时，即通过检查。

1. 发布文档：{ "flows": ["checkout"], "capabilities": { "checkout_sessions": "https://example.com/acp/checkout_sessions" } }。

验证：curl -sf https://example.com/.well-known/acp.json | jq -e '(.flows | length > 0) and (.capabilities | type == "object")'

4.16 AP2

当 4.3 中的 A2A Agent Card 声明了 AP2 扩展时，即通过检查。

1. 将以下内容添加到卡片中："extensions": [{ "uri": "https://google.github.io/A2A/extensions/ap2", "required": false }]。

验证：curl -sf https://example.com/.well-known/agent-card.json | jq -e '[.extensions[]?.uri] | any(test("ap2"))'

4.27 Agent 结账（Link、ACP checkout）

实验性。当结账页面上有 Stripe Link 或 Shared Payment Token 标记，或者 4.15 中的 ACP 文档包含 checkout_sessions 端点时，即通过检查。

1. 在 Payment Element 中启用 Stripe Link，或接受 Shared Payment Tokens。
2. 在 /.well-known/acp.json 中声明 ACP checkout_sessions 端点。

验证：curl -sf https://example.com/.well-known/acp.json | jq -e '.. | strings | select(test("checkout_sessions"))'

关键注意事项

1. 只有 tool-name（带连字符）才能获得部分分数。请使用 toolname。
2. 顶层包含 url 且没有 supportedInterfaces 的 A2A 0.3 卡片只能获得部分分数。
3. /api-docs 上的 Swagger UI HTML 不算 OpenAPI。
4. 空的 {} 文档无法通过任何发现检查。
5. WebMCP 清单文件不算数。没有规范定义这种文件，也没有 Agent 会读取它。

正确和错误示例请参阅 references/gotchas.md。

参考资料

• references/checkpoints.md：每个检查点的生成数据
• references/webmcp-guide.md：声明式和命令式 WebMCP
• references/a2a-mcp-guide.md：A2A、MCP、OpenAPI 和 agents.json
• references/gotchas.md：常见错误及正确和错误示例