How to make your service, application, or tool great for AI agents.
English | 中文
The web was built for humans. Every button, form, and navigation menu assumes a person with eyes and hands. But the fastest-growing user base isn't human — it's AI agents. Every website already has an agent experience. The question is whether it's good or bad.
Just as UX taught us to design for users, and DX taught us to design for developers, AX (Agent Experience) is the discipline of designing for agents. This guide is a practical, open-source handbook on how to do it well.
- ora.ai tells you where you stand — it scores and ranks agent readiness across thousands of sites.
- axd.md tells you what to aim for — it defines 12 principles and 15 primitives of agent experience design.
- agentexperience.ax curates conversations and articles about the AX movement.
This guide tells you how to get there — concrete, actionable steps with code examples, patterns, and anti-patterns for making your service agent-ready.
An agent trying to use your product follows a journey with six stages. Your job is to optimize each one:
Discovery → Identity → Auth & Access → Integration → Errors & Recovery → End-User Experience
If an agent can't find you, nothing else matters. If it can find you but can't understand what you do, it picks someone else. If it understands but can't authenticate, it's stuck. If it can authenticate but the plumbing is broken, tasks fail silently. If the plumbing works but errors aren't recoverable, the agent gives up. If all the plumbing works but the final handoff to the human is broken, the whole loop collapses.
This guide walks through each stage in detail.
- What is Agent Experience? — Why AX matters, the UX → DX → AX evolution, and how to think about agents as a user persona.
- Discovery — Can agents find you? llms.txt, robots.txt, sitemap, AEO/GEO, structured data.
- Identity — Do agents understand what you do? Machine-readable descriptions, metadata, pricing, capabilities.
- Auth & Access — Can agents authenticate and act? OAuth, API keys, auth.md, scoped tokens, x402.
- Integration — Is the plumbing there? MCP, A2A, streaming, SDKs, function calling, webhooks.
- Errors & Recovery — Can agents self-heal? Typed errors, retry guidance, structured responses.
- Agent-Native Architecture — Shared action models, agent UI parity, governed execution, cloneable apps.
- End-User Experience — Can humans interact through agents? Handoff flows, MCP Apps, activity transparency.
- Anti-Patterns — 25+ things that break agent experience on the web.
- Agent Readiness Checklist — A practical checklist to evaluate and improve your agent experience score.
- References — Curated links, standards, and further reading.
- Add
/llms.txtto your site root describing what your site does and what agents can do there. - Return typed errors with retry guidance from every API endpoint — not "something went wrong."
- Let agents authenticate with scoped API tokens instead of browser-only OAuth flows.
Level 0 — Invisible Agents can't find or parse your site at all.
Level 1 — Discoverable Agents can find you and understand what you do.
Level 2 — Accessible Agents can authenticate and make basic API calls.
Level 3 — Integrated Agents can use your tools, stream responses, recover from errors.
Level 4 — Agent-Ready Agents can complete full workflows with human handoff.
Level 5 — Agent-Native Agents and humans share the same action model, state, and permissions.
Most of the web sits at Level 0 or 1 today. This guide helps you move up.
Read the guide at ax.wilsonhandbook.online
Switch between Human and Agent mode using the toggle in the top-right corner.
This is an open project. PRs, issues, and discussions are welcome at GitHub Issues.
MIT
This guide draws on ideas and work from many sources including:
- AX Design Standard — 12 principles and 15 primitives of agent experience design
- ora.ai — Agent readiness scoring and ranking
- Agent Experience Community — AX movement and articles
- Netlify — Matt Biilmann's original AX formulation
- Builder.io — Agent-native architecture patterns
- WorkOS auth.md — Agent authentication protocol