agent-friendly-design（Agent 友好设计）

agent-friendly design

how to build sites and apps that AI agents can actually use.

why this exists

most design guidance is about agents *building* UI. this skill is about agents *consuming* UI. the audience for your site is no longer just humans — automated traffic surpassed human traffic in 2024 (51% of all web interactions). agents browse, compare, purchase, research, and interact on behalf of users.

if your site is invisible to agents, you're invisible to a growing majority of the web.

the core insight

the accessibility tree — originally built for screen readers — is becoming the primary interface between AI agents and your website. OpenAI's Atlas explicitly uses ARIA tags to interpret page structure. Microsoft's Playwright MCP provides accessibility snapshots, not screenshots. even vision-first agents (Anthropic Computer Use, Google Mariner) are incorporating accessibility data for reliability.

building for agents and building for accessibility are the same work. every improvement you make for one benefits the other.

the checklist

1. semantic HTML (non-negotiable)

agents can't "see" your layout. they read structure. div soup is invisible.

• use native elements: <button>, <nav>, <main>, <article>, <section>, <header>, <footer>, <aside>
• proper heading hierarchy: <h1> through <h6>, no skipped levels
• <label> elements explicitly associated with form inputs (use for attribute)
• <table> for tabular data with <thead>, <th>, and scope attributes
• links are <a> elements, buttons are <button> elements. never <div onclick>
• use <form> for forms, with <fieldset> and <legend> for groups
• meaningful <img alt> text (not "image1.png")

test: disable CSS. can you still understand the page? if yes, agents can too.

2. ARIA: useful, not magic

ARIA supplements semantic HTML — it doesn't replace it. use it when native elements can't express the interaction.

• aria-label on buttons and links that lack visible text (icon buttons, close buttons)
• aria-expanded on toggles, dropdowns, accordions
• aria-live regions for dynamic content agents need to notice (status messages, notifications)
• role attributes only when there's no native element (e.g., role="tablist", role="dialog")
• aria-describedby for complex form fields that need additional context
• aria-hidden="true" on decorative elements agents should ignore

don't do: put ARIA on everything. over-labeling creates noise. if the native element already communicates the role, skip the ARIA.

3. machine-readable state

agents can't interpret visual cues. a grayed-out button means nothing if disabled isn't set.

• use disabled attribute on inactive controls
• use aria-selected, aria-checked, aria-pressed for toggle states
• loading states: aria-busy="true" on containers updating content
• error states: aria-invalid="true" on fields with validation errors, plus aria-errormessage linking to the error text
• empty states: render actual DOM content (not just CSS ::after pseudo-elements)
• pagination: current page marked with aria-current="page"

the rule: if a human can tell the state by looking, an agent should be able to tell the state by reading the DOM.

4. structured data (JSON-LD + Schema.org)

helps agents understand *what* your content is, not just how it's structured.

• Organization, Product, Article, BreadcrumbList, FAQPage, HowTo schemas as appropriate
• JSON-LD in <script type="application/ld+json"> (preferred over microdata or RDFa)
• keep structured data in sync with visible content — don't stuff keywords
• include dateModified and datePublished so agents know freshness
• product pages: price, availability, reviews, SKU
• articles: author, datePublished, headline, description

5. llms.txt

a markdown file at /llms.txt that gives LLMs a concise overview of your site. like robots.txt, but for language models.

# 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...

• keep it under 2000 tokens for quick context loading
• link to detailed markdown versions of important pages (append .md to URLs if possible)
• update when content changes — stale llms.txt is worse than none
• spec: https://llmstxt.org

6. crawlability and rendering

agents can't all execute JavaScript. many rely on raw HTML.

• server-side render (SSR) or pre-render critical content
• don't hide key information behind client-side-only JavaScript
• update robots.txt to allow known AI user-agents (ChatGPT-User, OAI-SearchBot, Googlebot, etc.)
• maintain an up-to-date sitemap.xml
• fast response times (agents may time out at 10-30 seconds)
• important content should be high in the HTML source (agents may not scroll)

7. predictable interactions

agents automate by finding patterns. inconsistency breaks them.

• consistent naming: if "Add to Cart" is the button text on one page, don't make it "Buy Now" on another
• standard HTML form controls (not custom JavaScript widgets that look like inputs but aren't)
• predictable IDs and class names across similar pages
• avoid modals, popups, and interstitials that require complex dismissal sequences
• minimize login walls for browsing (allow guest checkout where possible)
• avoid CAPTCHAs on non-critical flows — they block agents completely

8. API-first patterns

if agents can get data without scraping HTML, everyone wins.

• REST or GraphQL endpoints for core data (products, content, status)
• OpenAPI spec published and linked from llms.txt
• MCP (Model Context Protocol) server for direct tool access — agents can call your API through MCP without browser automation
• NLWeb integration for natural language queries against your data
• A2UI for agent-driven native interfaces (Google's open project — agents send component blueprints that inherit host app styling)
• webhooks for state changes agents need to react to

9. content for agents, not just humans

• write clear, descriptive page titles (agents use <title> heavily)
• meta descriptions that actually describe the page content
• use descriptive link text ("View pricing details") not generic ("Click here")
• break long content into sections with headings
• provide summaries or TL;DRs for dense pages
• don't rely on images alone to convey information — always have text equivalents

10. test with agents

• use browser dev tools to inspect the accessibility tree (Chrome: Accessibility pane in Elements)
• test critical flows with AI browser agents (ChatGPT Atlas, Playwright MCP)
• run Lighthouse accessibility audit — most issues it catches affect agents too
• check that forms can be completed programmatically
• verify that dynamic content updates are reflected in the DOM, not just visually

the dual-interface mental model

you're building two interfaces on one page:

human interface: visual hierarchy, color, typography, whitespace, motion, delight agent interface: semantic structure, ARIA roles, JSON-LD, predictable controls, API endpoints

they don't conflict. a well-structured semantic page is easier for humans AND agents. the dual-interface is additive, not a trade-off.

routing

• every web project: items 1-3 (semantic HTML, ARIA, machine-readable state) are non-negotiable
• public-facing sites: add items 4-6 (structured data, llms.txt, crawlability)
• products/e-commerce/SaaS: add items 7-9 (predictable interactions, API-first, content optimization)
• full agent-readiness: all 10 items

emerging protocols to watch

compounding

after building or auditing a site for agent-friendliness:

• document which patterns agents struggled with → add to this skill's checklist
• note which ARIA patterns made the biggest difference → share with the team
• track agent traffic in analytics (user-agent strings) → understand actual usage
• test new protocols as they mature (MCP, A2UI) → update this guide

the web is shifting from page-driven to action-driven. designing for agents isn't future-proofing — it's building for today's traffic.