The Agent Experience Framework
A structured way to design, build, and evaluate the layer of a digital product that AI agents use. Written for designers and engineers, and meant to be read in under twenty minutes.
01
Definition and purpose
Agent Experience (AX) is the practice of designing digital products and services so AI agents can discover capabilities, understand context, execute actions, recover from errors, and achieve goals reliably, safely, and efficiently.
The framework exists because agents now use products that were never designed for them. They can operate graphical interfaces, but they do it the way a person would operate a machine through a keyhole: slowly, expensively, and with frequent misreadings.
AX Framework gives teams three things: a vocabulary for talking about agent experience (pillars, principles, patterns), a method for designing it (task-first, lifecycle-aware), and a way to evaluate it (checks, task-based testing, a maturity model).
It is deliberately technology-neutral. It describes outcomes, then points to established standards where they already solve part of the problem.
User interface
Pages, controls, visual feedback
Agent Experience layer
- Capability manifest
- Resource descriptions
- Action contracts
- Grants & approvals
- Receipts & status
Delivered through HTML + JSON-LD, an HTTP API, and/or an MCP server
02
Foundational principles
Ten proposed principles describe what good agent experience looks like. Each comes with examples, implementation guidance, and evaluation criteria.
03
The six pillars
The pillars are the dimensions along which agent experience succeeds or fails. Four describe the flow of a task. Trust & Control bounds the flow. Recovery & Resilience keeps it going.
- 01DiscoverabilityCan an agent discover what a product can do?
- 02ComprehensionCan an agent understand content, context, and constraints?
- 03ActionabilityCan an agent execute supported actions?
- 04Feedback & ObservabilityCan an agent understand outcomes and state changes?
- 05Trust & ControlCan an agent operate within clear permissions and safety boundaries?
- 06Recovery & ResilienceCan an agent handle errors, ambiguity, and interruptions?
Discoverability
Can an agent discover what a product can do?
02Comprehension
Can an agent understand content, context, and constraints?
03Actionability
Can an agent execute supported actions?
04Feedback & Observability
Can an agent understand outcomes and state changes?
05Trust & Control
Can an agent operate within clear permissions and safety boundaries?
06Recovery & Resilience
Can an agent handle errors, ambiguity, and interruptions?
04
Agent interaction lifecycle
Agents work in a loop. They find out what is possible, interpret what they find, confirm they are allowed to act, act, check the result, and recover when something goes wrong. Each stage maps to a pillar, and each is a place where a product can help or hinder.
01
Discover
What can I do here?
Discoverability
02
Understand
What does this mean?
Comprehension
03
Authorize
Am I allowed?
Trust & Control
04
Act
Do it, predictably.
Actionability
05
Verify
Did it work?
Feedback
06
Recover
What now?
Recovery
Designing for the lifecycle, rather than for individual endpoints, keeps attention on the whole task. A product with excellent actions but no way to verify their outcome still leaves the agent guessing at the end.
05
Relationship to UX and accessibility
AX and UX
UX and AX share a goal: helping someone accomplish a task. They differ in who is doing the work. In UX, the person acts and the interface helps. In AX, an agent acts for the person, and the product has to support both the agent doing the work and the person who remains accountable for it.
That means AX is still a human-centered discipline. Approval screens, activity logs, and the language agents relay to people are all UX surfaces that AX depends on.
AX and accessibility
Accessibility work makes meaning explicit in the markup instead of leaving it to vision. That is precisely what agents reading a page need. A product with good semantic structure, labelled controls, and text alternatives is already partway to Level 1 in the maturity model.
AX should never be built at the expense of accessibility. If a change helps agents but hurts people using assistive technology, it is the wrong change.
06
Relationship to APIs, MCP, and standards
AX does not define a new transport. It describes what agents need, then uses existing technologies to deliver it. The table distinguishes established standards from community proposals and from AX's own proposals.
| Technology | Status | Role in AX |
|---|---|---|
Semantic HTML & WAI-ARIA W3C specifications for document structure and accessible semantics. | W3C | The baseline. Agents that read pages benefit from the same structure assistive technology uses. |
schema.org & JSON-LD A shared vocabulary for describing things on the web, commonly embedded as JSON-LD (a W3C Recommendation). | Widely adopted | Resource descriptions for public content: products, events, organizations, articles. |
OpenAPI A specification for describing HTTP APIs, maintained by the OpenAPI Initiative. | Industry spec | Machine-readable action contracts for products that expose HTTP APIs. |
OAuth 2.0 The IETF authorization framework for delegated access (RFC 6749 and related RFCs). | IETF | Scoped, revocable grants for agents acting on a person's behalf. |
Problem Details (RFC 9457) An IETF format for machine-readable HTTP API errors. | IETF | A foundation for structured, recoverable error responses. |
Model Context Protocol An open protocol, introduced by Anthropic in 2024, for connecting AI applications to tools, resources, and prompts. | Open protocol | One delivery channel for AX capabilities, especially for agents running in AI clients. |
llms.txt A community proposal for a Markdown file that summarizes a site for language models. | Community proposal | A lightweight, human-readable entry point that can link to deeper AX resources. |
AX capability manifest The manifest format described in these docs. | AX proposal | A product-level index of capabilities, risk, and auth. Experimental and subject to change. |
See MCP Integration and API Integration for implementation detail.
07
Design considerations
Exposure versus attack surface
Every capability you describe is also documentation for misuse. Expose what serves real tasks, enforce authorization on every call, and never treat the manifest as an access control mechanism.
Untrusted content
Agents read content your users and third parties wrote. Keep instructions and data clearly separated, and never let content in a resource change what an action does. Prompt injection is a product design problem as much as a model problem.
Autonomy versus oversight
Too many confirmations make delegation pointless; too few make it dangerous. Decide per action, based on reversibility and cost, and let people adjust the dial.
One source of truth
The UI, the structured data, and the action contracts should be generated from the same definitions. Drift between what people see and what agents receive is a bug in both experiences.
Agent identity
Distinguish agent traffic from human traffic so you can apply appropriate limits, label activity in logs, and support people when something goes wrong.
Cost and rate
Agents can be fast and persistent. Rate-limit per grant, make expensive operations explicit, and prefer one well-shaped request to many small ones.
08
Maturity model
Five levels describe how far a product has come. Levels are cumulative, and most products today sit at Level 0 or 1 for most tasks. A product can be at different levels for different tasks.
LEVEL 2 · OPERABLE
Agents can perform core tasks through declared, documented actions.
Typical next step
Introduce scoped grants, risk labels, approvals, and receipts.
- Capability manifest at a known location
- Typed action contracts with server-side validation
- Structured errors with stable codes
- Idempotency on state-changing actions
09
Evaluation methodology
- STEP 1
Define tasks
List the five to ten tasks people are most likely to delegate. Evaluation is always against tasks, never against a product in the abstract.
- STEP 2
Inspect
Review each task against the checks for every pillar. Can the capability be found? Is context typed? Are actions explicit? Is the outcome verifiable?
- STEP 3
Test with agents
Run the tasks with one or more real agents. Record task success, steps taken, guesses made, errors recovered, and human interventions.
- STEP 4
Score and prioritize
Score each pillar, then prioritize the gaps that block the most valuable tasks. Retest after changes.