Today's web was built for humans. Every button, every form, every navigation menu assumes a person with eyes and hands. But the fastest-growing user base on the internet isn't human — it's AI agents browsing sites, calling APIs, reading docs, and completing tasks on behalf of people.
Most websites are invisible to agents. JavaScript-rendered pages with no structured data. Auth flows that require clicking through browser popups. Error messages that say "something went wrong." These aren't edge cases — they're the default. Every website already has an agent experience. The question is whether it's good or bad.
AXD is the practice of designing your web presence so both humans and agents can use it. Not by building a separate "agent version" — by building the same site better.
The 12 Principles
The foundation of Agent Experience Design. Each principle addresses a specific way websites fail agents today — and how to fix it.
- IAgents are users. Treat agents as a real user persona alongside your human users.
- IIStructure is the interface. Your API responses, HTML structure, and data formats are the agent's UI.
- IIIContext beats prompting. A self-describing site beats clever instructions every time.
- IVOpen ecosystems win. Let people bring their own agents. Don't lock them into yours.
- VEvery action needs feedback. Agents can't see your success toast. Return structured results.
- VIRecovery is mandatory. Typed errors with retry guidance. Not "something went wrong."
- VIIDiscovery is part of the product. If agents can't find your capabilities, they don't exist.
- VIIIAuth is experience. Browser-only OAuth kills agents. Scoped tokens enable them.
- IXMemory and events for long work. Agents don't stay on the page. Support async and resumability.
- XTrust must be computable. Machine-readable provenance, not marketing badges.
- XIAutonomy must be bounded. Label safe vs dangerous actions. Let agents move fast within limits.
- XIIAccessibility for agents. Design for the range: large models and small, rich context and limited.
The 15 Primitives
The building blocks of agent experience on the web. Each primitive is a category of interaction that agents need from your site.
Context — Can agents understand what your site does? Through structured data, semantic HTML, llms.txt, and clear page descriptions.
Access — Can agents authenticate? Scoped API tokens over browser-only OAuth. Explicit permission errors. No CAPTCHAs on API endpoints.
Navigation — Can agents find their way around? Sitemaps, linked resources, next-action hints in API responses. Not visual menus only.
Discovery — Can agents find your features? Root-level capability indexes, structured search results, metadata on every resource.
Feedback — Do agents know if their actions worked? Every mutation returns resulting state. Long operations return progress. No silent success.
Recovery — Can agents self-recover from errors? Typed error codes, retryable flags, Retry-After headers, suggested alternatives. Not HTML error pages from API endpoints.
Onboarding — Can a new agent start using your site in minutes? Quick-check summaries, working examples, progressive disclosure from simple to detailed.
Anti-Patterns
25 things that break agent experience on the web.
The Browser-Only Auth Flow. Auth requires visual browser interaction with no programmatic alternative. Agents can't click buttons.
The Pretty Website, Useless API. Beautiful landing page, marketing copy everywhere, but the actual API docs are an afterthought.
The "Something Went Wrong" Error. Generic error message with no error code, no classification, no recovery guidance. Agent is stuck.
The PDF Documentation. Product docs are a 200-page PDF. Not searchable, not linkable, not parseable.
The Rate Limit Without Retry-After. Returns 429 but doesn't say when to retry. Agent must guess.
The Silent Mutation. POST endpoint that sends emails, creates records, or charges money with no mention in the docs.
The Kitchen Sink Endpoint. One endpoint that does 5 different things depending on which parameters you send.
The 100 Tools With No Categories. Dumps all capabilities in a flat list with no organization.
And 17 more. Read the full list →
AX Scoring
Rate any website or web app across 20 metrics. Each scored 0–2. Maximum score: 40.
Metrics include: time-to-first-action, context cost (tokens needed to start), error recovery rate, discovery friction, schema coverage, documentation-to-capability ratio, action classification rate, and model range support. Full scoring system →
The AX Stack
10 layers of agent experience. Each builds on the one below. A governance problem might actually be a schema problem three layers down. Fix from the bottom up.
- 10GovernancePolicies, audit, safety
- 9CoordinationMulti-agent orchestration
- 8TrustVerification, provenance
- 7MemoryPersistence, recall
- 6ExecutionTool use, actions
- 5ContextEnvironment, identity
- 4CapabilityDiscovery, onboarding
- 3SchemaTypes, validation
- 2ProtocolHTTP, MCP, CLI
- 1TransportNetwork, auth
/llms.txt for a machine-readable index of the full standard. Install the AXD audit skill to evaluate any website against these principles.