智能体就绪度检查清单

使用此检查清单来评估和改进你的服务的智能体体验。逐节推进——你不必勾选所有项才算智能体就绪，但每勾选一项都会提升你的得分。

第一阶段：可发现性

智能体能找到并抓取你的服务吗？

基础设置

• /robots.txt 允许主流智能体爬虫（ChatGPT-User、ClaudeBot、Google-Extended 等）
• /sitemap.xml 存在且保持最新
• /llms.txt 存在，包含清晰的产品描述、能力和链接

结构化数据

• 首页包含 JSON-LD 结构化数据（SoftwareApplication 或合适的 schema）
• 产品类别在所有元数据表面中保持一致
• 定价信息是机器可读的（不仅仅是“联系销售”）

Well-Known 路径

• OpenAPI 规范发布在可预测的 URL（如 /.well-known/openapi.json 或通过 llms.txt 链接）
• 智能体发现端点正常响应（A2A Agent Card、MCP server info 或类似端点）

答案引擎优化

• 关键页面有清晰、事实性的 <title> 和 <meta description> 标签
• 产品描述简洁准确（不是营销套话）
• FAQ 或帮助页面回答了常见的“这个产品能做什么？”问题

第二阶段：身份标识

智能体能理解你的服务是什么、提供什么吗？

产品身份

• /llms.txt 包含清晰的一句话产品描述
• 产品类别和使用场景被明确说明
• 目标受众被标识（如“面向小型团队”“企业级”“开发者”）

能力索引

• 所有面向智能体的操作均被列出并描述
• 操作被分类为 read、write 或 destructive
• 每个操作所需的作用域/权限已文档化
• 操作按逻辑类别组织（不是 100 项的扁平列表）

一致性

• 首页、llms.txt、JSON-LD 和 OpenAPI 规范一致地描述产品
• 网站上的定价与结构化数据中的定价一致
• llms.txt 中列出的能力与实际 API 端点一致

边界

• 服务不做什么已文档化
• 速率限制已发布且机器可读
• 服务条款可访问（最好以结构化格式提供）

第三阶段：认证与访问

智能体能否认证并代表用户操作？

认证选项

• 至少有一种编程式认证方式可用（不仅仅依赖浏览器）
• OAuth 元数据发布在 /.well-known/oauth-authorization-server
• 支持 PKCE with S256 的 OAuth 流程
• 支持设备授权流程，适用于无头智能体
• 提供带渐进式权限的作用域 API 令牌

Auth.md 支持

• /auth.md 已发布，包含结构化的智能体认证说明
• 支持智能体验证流程（ID-JAG）（如适用）
• 支持用户认领流程（OTP）（如适用）
• AS 元数据包含 agent_auth 块，含注册和认领 URI

令牌管理

• 令牌有作用域（不是全有或全无）
• 令牌有时间限制（不是永久的）
• 令牌可撤销且不影响其他令牌
• 令牌操作可审计（谁、做了什么、何时）

反模式不存在

• API 端点上无 CAPTCHA
• 无不支持编程方式的 OAuth 流程（有编程式替代方案）
• 不只有单一全局 API 密钥作为唯一认证选项
• 不只有邮箱验证作为获取凭据的唯一途径

第四阶段：集成

基础设施就绪了吗？智能体能否实际使用你的服务？

模型上下文协议（MCP）

• MCP 服务器可用且可访问
• MCP 工具有描述性名称（verb_noun 模式）
• MCP 工具有准确、详细的描述
• MCP 工具有带类型的、文档化的参数（使用 Zod 或等价方案）
• MCP 服务器使用 Streamable HTTP 传输（不仅仅是 stdio）
• MCP 服务器支持正确的错误响应，含 isError: true

REST API

• API 使用一致的 URL 模式（/api/v1/resource）
• API 使用一致的响应封装（{ data, meta, errors }）
• API 支持分页，并带有清晰信号（has_more、next_cursor）
• API 支持列表端点上的筛选和排序
• API 支持字段选择（稀疏字段集）
• 变更端点支持幂等键
• API 有版本控制（如 /v1/、/v2/）

OpenAPI

• OpenAPI 3.x 规范已发布且可访问
• 规范准确且与运行中的 API 一致
• 规范包含认证要求
• 规范包含错误响应 schema
• 规范包含示例请求和响应

流式传输与事件

• 长时间运行的操作支持 SSE 或 WebSocket 流式传输
• 流式传输期间发出进度事件（不仅仅是最终结果）
• 关键事件有 Webhook 可用
• Webhook 载荷包含完整数据（不仅仅是 ID）
• 支持 ETag/If-None-Match 以进行高效轮询

SDK

• 至少有一个官方 SDK（Python、TypeScript 等）
• SDK 错误处理映射到结构化的错误类型
• SDK 文档包含智能体使用示例

第五阶段：错误与恢复

当出现问题时，智能体能自我修复吗？

错误结构

• 所有 API 错误返回 JSON（API 端点绝不返回 HTML）
• 错误有结构化的 type（如 validation_error、rate_limit_error）
• 错误有机器可读的 code（如 CONTACT_EMAIL_REQUIRED）
• 错误包含人类可读的 message
• 验证错误指明哪个字段失败以及原因
• 权限错误指明需要哪个作用域

重试指引

• 每个错误都指示是否可重试（retryable）
• 速率限制错误包含 Retry-After 头
• 速率限制响应包含 limit、remaining 和 reset_at
• 冲突响应包含当前版本和获取链接

恢复

• 错误尽可能包含建议的恢复操作
• “未找到”错误建议替代查询
• “禁止访问”错误链接到作用域申请流程
• “冲突”错误链接到资源的当前版本

幂等性

• 所有变更端点接受 Idempotency-Key 头
• 重复的 Idempotency-Key 请求返回原始响应
• 破坏性操作被标记且需要确认

第六阶段：智能体原生与终端用户体验

你的产品是否专为智能体与人类的协作设计，并支持无缝转接？

操作模型

• 产品能力定义一次，暴露到所有界面（UI、API、MCP、CLI）
• 操作有统一的命名（verb_noun）
• 操作有明确的作用域要求
• 操作被分类为 read / write / destructive
• 操作文档化所有副作用

上下文与治理

• 智能体可以看到用户当前正在查看的内容（共享状态）
• 智能体可以代表用户导航 UI
• 智能体所做的更改在 UI 中实时可见
• 人类和智能体的操作都写入同一个数据库
• 智能体操作有日志记录且可审计
• 智能体操作遵循与人类操作相同的权限
• 破坏性操作需要显式确认（人在回路中）
• 适当情况下，操作在时间窗口内可撤销

项目级

• AGENTS.md 存在于项目根目录
• 支持智能体工作区自定义（记忆、技能、指令）
• 智能体进度可观测（追踪、状态事件）
• 智能体操作的成本和延迟被追踪

转交流程

• 每个需要人类确认的操作都有清晰、上下文相关的转交流程
• 转接 URL 包含带过期时间的上下文令牌
• 确认页面显示智能体正在做什么以及为什么
• 用户可以在确认前审查智能体活动
• 智能体可以在人类确认后恢复工作流

活动透明度

• 智能体活动有日志记录且可审计
• 用户可以看到智能体所做操作的时间线
• 破坏性操作在时间窗口内具有撤销能力
• 在转接点提供状态快照

MCP 应用与内联 UI

• MCP 工具描述在适当位置包含 _meta.ui 元数据
• 确认工作流可以在智能体对话中渲染内联表单
• 复杂决策提供仪表板预览

移动端与品牌

• 转接页面响应移动端
• 确认页面匹配产品的设计语言
• 确认后，用户可以查看结果并返回智能体

评分

统计你在全部 6 个阶段中的勾选数量：

首先做什么

如果你刚起步，今天就做这三件事：

1. 添加 /llms.txt — 告诉智能体你的产品是什么以及它们能做什么。
2. 返回结构化的 JSON 错误 — 不再返回“出了点问题”。
3. 添加带作用域的 API 令牌 — 给智能体提供无需浏览器流程的认证方式。

然后逐阶段检查这份清单，从可发现性开始，逐步推进到智能体原生与终端用户体验。你每改进一个阶段，就为想要使用你产品的智能体解锁了更多能力。

→ 返回引言 | 参考资料