Agent Experience (AX): Designing for Agent Consumers
An agent is now a consumer of your platform, your documentation and your APIs. It cannot infer, cannot ask a colleague and cannot click a button, so everything that is merely annoying for a human is blocking for it.
A Consumer That Cannot Improvise
What the term means, and what part of it is settled
Start with a disclaimer, because it changes how to read the rest of this page. Agent Experience, usually shortened to AX, is an emergent discipline rather than a settled one. People use the term to mean different things: CLI ergonomics when a model drives them, API design for tool calling, the shape of in-repo instruction files, or simply the features a product ships. Much of what is published under the label is vendor positioning rather than established practice. Underneath it is a durable idea: a non-human caller is now a first-class consumer of your platform, documentation, APIs, CLIs and error messages, alongside human developers rather than instead of them.
Developer experience quietly assumed a human: someone who infers intent from a half-written sentence, asks the person two desks away, recognizes that an error is nonsense, clicks through a console when the CLI has no equivalent. An agent can do none of that reliably. It has no colleague, no memory of last week's outage, no browser session in your admin panel, and no way to tell "this error is misleading" from "this error is the truth". It has only the text your tools return.
The volume makes it worth designing for. DORA's "State of AI-assisted Software Development" (September 2025, nearly 5,000 respondents) reports 90 percent of developers using AI daily, at a median of about two hours per day, and finds that AI amplifies an organization's existing strengths and weaknesses rather than fixing either (DORA, 2025). That is the mechanism here: clear machine-readable failures make a platform faster, ambiguous ones produce more confidently wrong changes.
The trust picture agrees. The Stack Overflow Developer Survey 2025 (n=48,885) found 84 percent use or plan to use AI tools while only 33 percent trust the accuracy of the output (Stack Overflow, 2025). Adoption is near-universal, confidence is not, so every agent-driven workflow ends in human verification. Good AX reduces how much there is to verify.
Annoying for a Human, Blocking for an Agent
The single most useful lens for auditing an existing platform
Nearly every AX problem worth fixing is a rough edge humans have absorbed for years without complaining loudly enough to get it prioritized. Introduce a caller that cannot absorb it and the edge becomes a wall. An interactive prompt is the clearest case: a human sees "Overwrite existing config? [y/N]", presses a key and moves on, while an agent has no keystroke to send and no notion it is being asked anything. The process sits holding an open pipe until something times out, and the run is scored as a hang rather than a question.
A vague error is worse, because it fails quietly. "Something went wrong" tells a human little, but the human has context: a migration ran this morning, staging is flaky, check the logs. The agent has the string and nothing else, and it will still act, because acting is what it does. The most available action is to change the code in front of it, which is how an interface defect becomes a source-tree defect. That failure mode, and why it is expensive on a repetitive edit-build-test cycle, is covered on environment drift and the inner loop.
Output formatting is overlooked longest. A tool that draws a spinner and emits ANSI color is pleasant to watch and useless to parse, and one whose output changes shape off a TTY means the agent sees something the developer never documented.
| Rough edge | Annoying for a human | Blocking for an agent |
|---|---|---|
| Interactive prompt, no flag | Press a key, continue | Hangs until the run times out; the question never surfaces |
| "Something went wrong" | Check the logs, recall last week's outage | Nothing to branch on; it guesses, usually by editing source code |
| Undocumented exit codes | Read the message instead of the code | Cannot tell bad input from a broken environment from an empty result |
| Non-idempotent setup command | Know not to run it twice | Retry is its default recovery, so run two corrupts the state |
| Console-only setup step | Two minutes of clicking | No path at all; the workflow has a hole in the middle |
| Output that changes shape off a TTY | Looks slightly different in a pipe | Parsing written against the pretty form silently breaks |
| Spinners in captured logs | Reassuring while you wait | Escape sequences and repeated frames flood the context |
| Tribal knowledge in the docs | Ask a teammate, never write it down | A documented dead end; no non-human can complete it |
Errors a Caller Can Act On
A stable identifier, a retry hint, and a code that does not change when the prose does
The most valuable single change most platforms can make is to give every error a stable machine identifier separate from its human message. The identifier is what a caller branches on; the message is what a person reads. Keeping them apart lets the prose be rewritten or translated without breaking anything downstream, which is what makes the identifier worth depending on.
The anti-pattern is matching on message text. It works in testing and breaks the first time someone improves the wording, quietly, because the match stops matching and the caller falls through to its generic handler. An agent doing that concludes an unrecognized failure means the code is wrong.
A Machine-Readable Error
{
"error": {
"code": "WORKSPACE_QUOTA_EXCEEDED",
"message": "The team quota of 40 concurrent workspaces is fully in use.",
"resource": "workspace/platform-team",
"retryable": true,
"retry_after_seconds": 120,
"docs": "https://docs.example.internal/errors/WORKSPACE_QUOTA_EXCEEDED"
}
}The code lets a caller handle quota exhaustion differently from a bad request without reading English. The retryable flag is what stops the guessing: it is the difference between waiting two minutes and rewriting a deployment manifest. The docs URL gives a model something to fetch rather than invent. None of it helps if the code is derived from the message or renumbered between releases.
Exit codes are the same idea at the process boundary. Zero versus non-zero says something failed, not what kind of thing failed. The distinction that matters is between "your input was wrong", which an agent can fix, "the environment is broken", which it must not try to, and "ran correctly, found nothing", which is not a failure at all. That last one is routinely conflated with an error, and sends agents chasing problems that do not exist.
| Exit code | Meaning | What a caller should do |
|---|---|---|
| 0 | Success | Continue |
| 1 | Unexpected internal failure | Stop and report; do not attempt a code fix |
| 2 | Usage error: the input was wrong | Fix the arguments or configuration and retry |
| 3 | Environment error: a dependency is missing or unreachable | Escalate; the source tree is not the problem |
| 4 | Ran correctly, found nothing | Treat as an empty result, not a failure |
| 5 | Missing input that would have been prompted for | Supply the named value; the error must name it |
Interfaces That Do Not Require a Person
Non-interactive modes, idempotency, and output that does not move
Every Interactive Tool Needs a Non-Interactive Mode
A flag or environment variable guaranteeing the tool never prompts. A missing input becomes an immediate failure naming the value it needed. Failing loudly beats defaulting silently: a tool that quietly picks a default produces a run that appears to succeed and a result nobody chose.
Idempotent Commands
An agent retries. That is not a flaw, it is the correct response to an ambiguous failure, and it happens constantly. A setup command safe to run twice removes a whole class of failure. Where one cannot be idempotent, say so in its help text and make a second invocation detectable, so the caller gets "already applied" rather than a corrupted half-state.
Deterministic, Versioned Output
A structured output mode whose schema is versioned, so changing the display format is not changing the contract. No color codes, spinners or width-dependent wrapping off a terminal. Stable ordering counts too: a list returning in a different order each call makes diffs meaningless.
Capability Discovery
A machine-readable description of what a tool can do beats prose describing it. A parseable help output, a published schema, an OpenAPI document or an MCP server all let the caller learn the surface rather than guess. Keep expectations modest: a machine-readable description of a bad interface is still bad.
No Dead Ends
The test for any documented workflow is whether a non-human could complete it end to end. Walk the steps and find the point where the only instruction is to click something, ask someone, or consult a page that does not exist. That is where every agent run stops, and it is usually a step nobody has looked at in years because the humans routed around it. Fixing it is small work with an outsized effect.
Documentation Agents Can Actually Use
In-repo instructions, site-level conventions, and how much to believe about each
Documentation written for humans leans on shared context. "The standard way", "configure it as usual" and "see the team wiki" are not laziness, they are compression, and they work because the reader holds the missing half. A fresh agent holds none of it, so every compressed reference expands into a guess or a stop. The remedy is not more words but the specific thing: the actual command, the actual path, the actual value, and what to do when the step fails.
Two conventions have grown up around this, and both are genuinely new rather than rediscovered good practice. The first is AGENTS.md, an in-repo file carrying agent-directed instructions: how to build the project, how to run the tests, what not to touch. It is the highest-leverage AX artifact for most codebases because it sits next to the code and is versioned with it. The details are on AGENTS.md; what belongs in an agent's working context is on context engineering.
The second is llms.txt, a proposed convention for a file at the root of a site pointing a model at the parts worth reading. Describe it exactly that way: a proposal some sites publish, not an adopted standard. Claims about which vendors or crawlers actually consume it deserve caution unless you have verified the behavior yourself. Publishing one is cheap; assuming it changes how any model reads your documentation is not something this page can support.
The durable point sits underneath both: documentation that states its assumptions and never terminates in a human-only step is better documentation for people too. The agent is simply the reader who cannot paper over the gaps.
Where AX Sits Relative to Platform Engineering
A persona, not a separate function
AX is not a new department. It is a new persona inside platform engineering, and once the agent is a persona the existing machinery applies: it needs an identity, a scope, a quota, an audit trail and a support path, exactly as a human developer does. That framing turns a vague design sentiment into concrete platform work.
The CNCF has named this explicitly. In "Evolving platform engineering for AI-native workloads" (CNCF blog, July 6, 2026), Pankaj Gupta, Senior Director of Private Cloud Solutions at VMware by Broadcom, writes that "AI agents are recognized as non-human platform consumers with their own access, scope, and governance needs" (CNCF, 2026). Discount it appropriately: publication on the CNCF blog gives it standing, but the author writes for a commercial vendor with products in this space. Treat it as a well-argued position, not a neutral finding.
The persona view puts most of AX inside work platform teams already do. Access and scope are identity problems, quotas and cost attribution are what you already solve for CI, and making a workflow completable without a browser is golden-path work. That picture is on platform engineering, and the audit of whether a codebase is ready is on agent readiness. agent-experience.dev is a reference site gathering patterns, surfaces and design principles for AI agents; this page makes no claim about who publishes it or what it recommends, only that it collects material on the subject.
The Honest Tensions
What designing for agents costs, and which parts of this are actually new
Optimizing for Agents Can Degrade the Human Experience
Verbose machine-readable output is worse to read at a terminal, a rigid flag-driven interface is less pleasant than a good wizard, and stripping color and progress makes a long command feel dead. The usual resolution is dual-mode: rich for a TTY, structured otherwise. That is two interfaces to build and test, and the structured one silently rots, because no human looks at it until something breaks.
A Stable Machine Interface Is an API Contract
The moment callers branch on your exit codes and error identifiers, those values are public API. You cannot renumber them, fold two together, or repurpose one whose meaning went obsolete. That is an ongoing commitment deserving the same deprecation discipline as any other interface, and promising stability you will not keep is worse than never promising it.
Most of This Is Not New
Non-interactive modes, documented exit codes, idempotent commands and machine-readable errors long predate agents. They were already the right way to build anything intended for CI or scripting. What changed is the consumer: scripting could route around missing discipline with a wrapper and a regex, and an agent cannot. It fails in a way that costs a full run.
Some of It Is Marketing
Be blunt about the split. Durable engineering practice: non-interactive modes, stable exit codes, idempotency, machine-readable errors, documentation without dead ends. Genuinely new and unsettled: AGENTS.md conventions, llms.txt, and the AX label itself. The first list is safe to adopt on its own merits, agents or not. The second is cheap to try, but should not carry a migration or a procurement decision.
Good AX Does Not Make the Output Good
A clean machine interface removes ambiguity from the loop. It does not improve the quality of what an agent writes, and the two are worth keeping separate. GitClear's 2026 analysis of 623 million changes reports duplicated code up 81 percent (GitClear, 2026). GitClear sells code-quality analytics, so it has a commercial interest in the finding, and the number is a correlation across a large corpus rather than a controlled comparison. Read it as a reason to keep review capacity in the picture, not as a verdict.
So improving agent experience shifts work downstream: fewer runs fail on the environment, more produce a diff, and the diff still needs a reviewer who trusts it less than their own. That queue is covered on the AI code review bottleneck, and whether any of this helped is a measurement question, on DevEx metrics.
Related
The instruction files, the failure modes, and the platform work underneath
AGENTS.md
The in-repo instruction file, and how stable the convention actually is.
Agent Readiness
Auditing a codebase for the dead ends an agent cannot get past.
Context Engineering
What an agent should be given, and what it should discover.
The Inner Loop
Why a repetitive edit-build-test cycle makes every ambiguity expensive.
Environment Drift
The ambiguous failure that ends with an agent editing source code.
Platform Engineering
Golden paths, identity and quotas, with a non-human persona to serve.
Sources and Citations
Every claim on this site with a publisher, a year and a link.