Agent Experience (AX) covers what happens when software agents use your APIs, documentation, and tools on a user’s behalf. It extends Developer Experience work to schemas, permissions, retries, and other machine-facing behaviour.
Why use a separate label
Human users can infer intent from layout, prose, and context. Agents depend more heavily on deterministic behaviour, idempotency, machine-readable schemas, precise tool descriptions, and errors they can parse. A polished dashboard does not compensate for ambiguous tool names or undocumented rate limits. Complete schemas likewise do not replace clear explanation for a person evaluating the product.
The dual-audience thesis (see Humans and agents) requires both DX and AX, with different design work for each audience.
What AX covers in practice
A working scope for AX work as of mid-2026:
1. Agent-facing schemas and capability descriptions
- OpenAPI / GraphQL spec quality.
- MCP server design (tool naming, descriptions, schema, parameter constraints).
- Schema.org / JSON-LD markup on web surfaces.
- Type-correct, version-stable representations.
2. Documentation written for agent consumption
- One concept per page.
- Complete runnable code examples (no ”// rest omitted for brevity”).
- Explicit version metadata.
- Canonical URLs.
llms.txtandllms-full.txt.
See Agent-facing documentation.
3. Error message design
- Programmatically parseable error codes.
- Clear human-readable hints embedded in error responses.
- Suggested fixes (“did you mean…”).
- Stable, versioned error codes.
4. Idempotency and retry semantics
- Idempotency keys exposed on side-effecting operations.
- Predictable retry behaviour.
- Clear semantics for partial success / failure.
5. Rate limit and quota communication
- Limits documented and surfaced in response headers (
X-RateLimit-Remainingpatterns). - Backoff hints.
- Quota-exceeded errors that agents can act on rather than fail with.
6. Authentication ergonomics for agentic access
- OAuth scopes that map to the operations an agent is likely to perform.
- Token introspection so agents can check their own permissions.
- Refresh flows that agents can complete without human intervention (where appropriate).
7. Performance and latency
- Agents have time budgets per tool call. Slow tools time out and hurt agent task completion.
- Long-running operations exposed as Tasks (see MCP for DevRel).
8. Observability of agent behaviour
- Logs that distinguish agent traffic from human traffic.
- Metrics on tool-call success rate, latency distribution, error patterns.
- Feedback loops from agent-mediated usage into product and DevRel decisions.
Who owns the work
Teams can assign AX work in several ways:
- Agent Experience Engineer (or AX Engineer). Owns the MCP server, the OpenAPI quality, and the schemas. Often sits inside engineering or DX but with explicit “agent-facing” responsibilities. Common at AI infrastructure companies and at developer-tool companies whose products are increasingly invoked by agents.
- DevRel Engineer with AX scope. A developer advocate whose remit explicitly includes both human-facing content and machine-facing surfaces. Less specialised but pragmatic for mid-stage companies.
- Documentation Engineer for AI. A technical writer or doc engineer who treats AI-readability as the primary craft concern.
- Solutions Engineer for AI integrations. A pre-sales / customer-facing engineer who helps enterprise customers wire their agents to your MCP server cleanly.
How AX is measured
The metric stack is still developing. Some early candidates:
- Tool call success rate. Across agent-mediated invocations of your MCP server / API, what share succeed without error?
- Agent task completion rate. When an agent starts a workflow that involves your product, what fraction complete successfully? (Hard to measure without telemetry from the agent itself; sometimes inferred from server-side logs.)
- Recovery rate from errors. When your API returns an error to an agent, how often does the agent self-correct and retry successfully?
- Time-to-first-successful-tool-call. The agent analogue of TTFHW: from MCP server install to first successful invocation, what’s the median time?
- Citation accuracy in AI assistants. When ChatGPT / Claude is asked about your product, what percentage of the technical claims it makes are accurate?
- Schema completeness. What percentage of your public API surface is exposed via OpenAPI, GraphQL schemas, or MCP tool definitions?
These are nascent. Most teams in 2026 are still figuring out which metrics correlate with business outcomes; the canonical AX scorecard does not yet exist.
How AX intersects with DX
A useful framing:
| Layer | DX | AX |
|---|---|---|
| Onboarding | Quickstart with explanation, context, and guided steps | Quickstart with complete code, explicit imports, and minimal irrelevant preamble |
| Docs | Conceptual, opinionated, varied formats; voice | Reference-complete, structured, stable URLs, dated |
| APIs | Easy to call; good error messages | Predictable; idempotent; machine-parseable errors |
| Errors | ”Something went wrong. Try X.” | {"code": "INVALID_INPUT", "message": "...", "hint": "...", "docs_url": "..."} |
| Authentication | Easy human OAuth flow; smooth UI | Scoped tokens; refresh flows; introspectable |
| Versioning | Clear migration guides; deprecation banners | Predictable versioning; capability negotiation; tool versioning |
| Discovery | Marketing site; blog posts; conference talks | llms.txt; MCP server; OpenAPI; schema.org |
| Support | Community forum; Discord; office hours | Telemetry-driven; doc gap analysis; agent log review |
Common AX failure modes
- Treating MCP server as marketing. Tool descriptions full of brand language; agents struggle to invoke effectively.
- Presentation without schema quality. The documentation site looks polished while its OpenAPI specification remains incomplete or inconsistent.
- Error messages designed only for humans. Agents can’t parse them; they fail and retry inappropriately.
- No telemetry distinguishing agent traffic from human traffic. The team cannot tell which errors or failed workflows belong to agent-mediated use.
- Late ownership. Tool names, permissions, and error shapes become expensive to change after clients depend on them.
When to assign explicit ownership
A developer-product company needs explicit AX ownership when customers use agents to call its APIs or tools. The owner may sit in engineering, DX, documentation, or DevRel. What matters is that someone can change the schemas, retry semantics, permissions, documentation, and telemetry together.