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.
AX 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.
1. Add an llms.txt to your site root describing what your site does and what agents can do there.
2. Return typed errors with retry guidance from every API endpoint. Not "something went wrong."
3. Let agents authenticate with scoped API tokens instead of browser-only OAuth flows.
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.
Notifications - Can agents know when things change? Webhooks, event streams, polling endpoints with ETags. Not just email notifications for humans.
Memory - Can agents pick up where they left off? Session persistence, state snapshots, resumable workflows. Not "start over every time."
Identity - Does your site recognize agents as users? Agent-specific accounts, usage tracking, rate limits per agent identity. Not just human user profiles.
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.
Communication - Can agents hand off to humans cleanly? Escalation paths, structured handoff context, human-in-the-loop checkpoints. Not "please contact support."
Autonomy - Do agents know what's safe to do alone? Action classification (read/write/destructive), confirmation requirements, rollback support. Clear boundaries, not guesswork.
Onboarding - Can a new agent start using your site in minutes? Quick-check summaries, working examples, progressive disclosure from simple to detailed.
Social Proof - Can agents evaluate trust programmatically? Machine-readable reviews, verified usage stats, provenance chains. Not star ratings in images.
Orchestration - Can agents run multi-step workflows? Transaction boundaries, dependency declarations, parallel-safe operations. Not "call these 12 endpoints in the right order and hope."
Governance - Are the rules of engagement explicit? Terms of service in structured format, rate limit policies, data retention declarations. Not buried legal PDFs.
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 click buttons, but it's slow, fragile, and expensive compared to a simple API call.
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 the 15 AX primitives. Each scored 0-2. Maximum score: 30.
One score, one system. Score each primitive - Context, Access, Navigation, Discovery, Notifications, Memory, Identity, Feedback, Recovery, Communication, Autonomy, Onboarding, Social Proof, Orchestration, Governance - and get a single number that tells you where you stand. Full scoring system →