agent-friendly-design

Agent 友好型设计

如何构建 AI Agent 真正能够使用的网站和应用。

为什么要做这件事

大多数设计指南都关注 Agent 构建 UI。本指南关注的是 Agent 使用 UI。你网站的受众不再只有人类——2024 年，自动化流量已超过人类流量（占所有 Web 交互的 51%）。Agent 会代表用户浏览、比较、购买、研究和交互。

如果 Agent 看不见你的网站，那么随着 Web 上越来越多的流量来自 Agent，你的网站也会逐渐变得隐形。

核心洞见

无障碍树最初是为屏幕阅读器构建的，如今正成为 AI Agent 与网站交互的主要接口。OpenAI 的 Atlas 明确使用 ARIA 标签来理解页面结构。Microsoft 的 Playwright MCP 提供的是无障碍快照，而不是屏幕截图。即使是视觉优先的 Agent（Anthropic Computer Use、Google Mariner），也在整合无障碍数据以提高可靠性。

**为 Agent 构建体验与构建无障碍体验，是同一件事。**你为一方做出的每项改进，都会让另一方受益。

检查清单

1. 语义化 HTML（不可妥协）

Agent 无法“看见”你的布局，它们读取的是结构。堆满 div 的页面对它们来说形同虚设。

• 使用原生元素：<button>、<nav>、<main>、<article>、<section>、<header>、<footer>、<aside>
• 正确设置标题层级：使用 <h1> 到 <h6>，不要跳过级别
• 使用 <label> 元素明确关联表单输入框（使用 for 属性）
• 使用 <table> 展示表格数据，并搭配 <thead>、<th> 和 scope 属性
• 链接使用 <a> 元素，按钮使用 <button> 元素。绝不要使用 <div onclick>
• 表单使用 <form>，并用 <fieldset> 和 <legend> 对字段分组
• 为 <img alt> 提供有意义的文本（而不是“image1.png”）

**测试：**禁用 CSS。你还能理解页面吗？如果可以，Agent 也能。

2. ARIA：有用，但不是魔法

ARIA 用于补充语义化 HTML，而非取而代之。只有在原生元素无法表达交互时才使用它。

• 对缺少可见文本的按钮和链接（图标按钮、关闭按钮）使用 aria-label
• 对切换控件、下拉菜单和手风琴使用 aria-expanded
• 对 Agent 需要注意的动态内容（状态消息、通知）使用 aria-live 区域
• 仅在没有对应原生元素时使用 role 属性（例如，role="tablist"、role="dialog"）
• 对需要补充说明的复杂表单字段使用 aria-describedby
• 对 Agent 应忽略的装饰性元素设置 aria-hidden="true"

**不要这样做：**给所有内容都添加 ARIA。过多的标签会造成干扰。如果原生元素已经传达了对应的角色，就不要添加 ARIA。

3. 机器可读的状态

Agent 无法理解视觉线索。如果没有设置 disabled，灰显的按钮就毫无意义。

• 对非活动控件使用 disabled 属性
• 使用 aria-selected、aria-checked、aria-pressed 表示切换状态
• 加载状态：在正在更新内容的容器上设置 aria-busy="true"
• 错误状态：在存在验证错误的字段上设置 aria-invalid="true"，并使用 aria-errormessage 链接到错误文本
• 空状态：渲染实际的 DOM 内容（不要只使用 CSS ::after 伪元素）
• 分页：使用 aria-current="page" 标记当前页

**规则：**如果人类看一眼就能判断状态，Agent 就应该能通过读取 DOM 判断状态。

4. 结构化数据（JSON-LD + Schema.org）

帮助 Agent 理解内容是什么，而不只是内容如何组织。

• 根据需要使用 Organization、Product、Article、BreadcrumbList、FAQPage、HowTo 架构
• 在 <script type="application/ld+json"> 中使用 JSON-LD（优先于微数据或 RDFa）
• 确保结构化数据与可见内容一致——不要堆砌关键词
• 包含 dateModified 和 datePublished，让 Agent 了解内容的新鲜度
• 产品页面：价格、库存情况、评价、SKU
• 文章：作者、datePublished、标题、描述

5. llms.txt

位于 /llms.txt 的 Markdown 文件，为大模型简要介绍你的网站。它类似于 robots.txt，但面向语言模型。

# Your Project Name

> Brief description of what this site/product does.

## Docs

- [Getting Started](https://yoursite.com/docs/getting-started): How to set up...
- [API Reference](https://yoursite.com/docs/api): Full API documentation...

## Optional

- [Changelog](https://yoursite.com/changelog): Recent updates...

• 控制在 2000 个 token 以内，以便快速加载上下文
• 链接到重要页面的详细 Markdown 版本（如可行，请在 URL 后追加 .md）
• 内容变更时及时更新——过时的 llms.txt 还不如没有
• 规范：https://llmstxt.org

6. 可抓取性与渲染

并非所有 Agent 都能执行 JavaScript。许多 Agent 依赖原始 HTML。

• 对关键内容使用服务器端渲染（SSR）或预渲染
• 不要将关键信息隐藏在仅由客户端 JavaScript 呈现的内容中
• 更新 robots.txt，允许已知的 AI 用户代理（ChatGPT-User、OAI-SearchBot、Googlebot 等）访问
• 维护最新的 sitemap.xml
• 确保响应速度快（Agent 可能会在 10-30 秒后超时）
• 将重要内容放在 HTML 源码靠前的位置（Agent 可能不会滚动页面）

7. 交互应当可预测

Agent 通过寻找模式来自动执行操作。不一致会导致执行失败。

• 命名保持一致：如果一个页面的按钮文字是“加入购物车”，其他页面就不要改成“立即购买”
• 使用标准 HTML 表单控件（而不是外观像输入框、实际却不是的自定义 JavaScript 组件）
• 类似页面使用可预测的 ID 和类名
• 避免使用需要复杂步骤才能关闭的模态框、弹窗和插页式内容
• 尽量减少浏览过程中的登录限制（在可行时允许访客结账）
• 在非关键流程中避免使用 CAPTCHA——它们会完全阻止 Agent

8. API 优先模式

如果 Agent 无需抓取 HTML 就能获取数据，对所有人都有好处。

• 为核心数据（产品、内容、状态）提供 REST 或 GraphQL 端点
• 发布 OpenAPI 规范，并在 llms.txt 中提供链接
• 提供 MCP（Model Context Protocol）服务，支持直接访问工具——Agent 无需浏览器自动化，即可通过 MCP 调用你的 API
• 集成 NLWeb，以便通过自然语言查询你的数据
• 使用 A2UI 构建由 Agent 驱动的原生界面（Google 的开源项目——Agent 发送组件蓝图，这些蓝图会沿用宿主应用的样式）
• 为 Agent 需要响应的状态变更提供 Webhook

9. 内容应面向 Agent，而不只是人类

• 编写清晰、描述性强的页面标题（Agent 会大量使用 <title>）
• 编写真正能描述页面内容的 meta 描述
• 使用描述性链接文字（“查看价格详情”），而不是通用文字（“点击此处”）
• 使用标题将长篇内容拆分为多个部分
• 为内容密集的页面提供摘要或 TL;DR
• 不要只依赖图片传达信息——始终提供对应的文本

10. 使用 Agent 进行测试

• 使用浏览器开发者工具检查无障碍树（Chrome：Elements 中的 Accessibility 面板）
• 使用 AI 浏览器 Agent（ChatGPT Atlas、Playwright MCP）测试关键流程
• 运行 Lighthouse 无障碍审查——它发现的大多数问题也会影响 Agent
• 检查表单能否通过程序完成填写
• 确认动态内容更新会反映在 DOM 中，而不只是视觉上

双界面心智模型

你正在一个页面上构建两种界面：

**人类界面：**视觉层级、色彩、字体、留白、动效、愉悦体验
**Agent 界面：**语义结构、ARIA 角色、JSON-LD、可预测的控件、API 端点

二者并不冲突。结构良好的语义页面对人类和 Agent 都更易于使用。双界面是在现有基础上的扩展，而非取舍。

路线图

• **每个 Web 项目：**项目 1-3（语义化 HTML、ARIA、机器可读状态）不可或缺
• **面向公众的网站：**添加项目 4-6（结构化数据、llms.txt、可抓取性）
• **产品/电子商务/SaaS：**添加项目 7-9（可预测的交互、API 优先、内容优化）
• **全面实现 Agent 就绪：**全部 10 项

值得关注的新兴协议

协议	功能	状态
llms.txt	面向大模型的 Markdown 网站概览	已被许多项目采用，实现简单
MCP	为 Agent 提供直接的工具访问能力（无需浏览器）	快速发展，由 Anthropic 主导
NLWeb	使用自然语言查询你的数据	Microsoft 开源项目，仍处于早期阶段
A2UI	由 Agent 驱动的原生 UI 组件	Google 项目，规范仍处于早期阶段
AGENTS.md	项目级 Agent 指令	社区采用度持续提升

持续积累

为提升 Agent 友好度而构建或审查网站后：

• 记录 Agent 难以处理的模式 → 加入此技能的检查清单
• 记录效果最显著的 ARIA 模式 → 与团队分享
• 在分析工具中跟踪 Agent 流量（user-agent 字符串）→ 了解实际使用情况
• 随着新协议逐渐成熟（MCP、A2UI），对其进行测试 → 更新本指南

网络正从页面驱动转向操作驱动。为 Agent 设计并非面向未来的准备，而是为了今天的流量。