AHMAD BILAL
← AHMAD BILAL / WRITING AI & RESEARCH
AI & DESIGNAGENT UXAX

Agent experience design: when the user is sometimes an agent

Agents now consume products alongside humans. What that changes in affordances, error states, and provenance, from someone who ships both.

Ahmad BilalAug 2026~7 minAI & Research
FIG. 01 · BOTH READERS A split interface: the human side with visual weight, the agent side as a declared node manifest; one citation mark rendered identically on both.
One interface, two readers. The citation is the element both can use.

Software is being read by machines now, not just people. Agent experience design means building a product so an AI agent can tell what a button does, understand what went wrong when something fails, and check where a number came from. Mathias Biilmann named the field AX at Netlify in January 2025, putting it after UX and DX. The actual work is smaller than the name suggests. Most of it is already sitting in features you shipped for humans.

01What Biilmann actually named

Read the original post and the community site that grew from it, agentexperience.ax, and it is mostly infrastructure. Clean APIs. Docs a machine can read. A standard way for an agent to log in, work out what a service does, and recover when a call fails.

The site's own principles read like an accessibility spec written for machines. Don't put a barrier in front of an agent that you wouldn't put in front of a person. Don't assume the model already knows your domain. And an agent should admit it is one, in its own request headers. Good, durable guidance. It's aimed at people building the pipes an agent calls.

Microsoft took the same three letters somewhere else. Their framework is about designing the agent itself, sorted into space, time, and core, with rules like “connecting, not collapsing” and “nudging more than notifying.” That is persona work. It shapes how the agent behaves, not how your product looks to it.

And the platforms have found the term too. Salesforce is publishing agent experience design content that reads like Agentforce onboarding: a naming convention for your agent ("Name + Agent," kept under ten characters), a standardized avatar system, a decision tree for monolithic versus multi-agent architecture. Useful if you're selling an agent platform.

None of the three answers what happens to a screen you already shipped, the one some other company's agent is reading right now without asking your permission.

02The question most designers have

You didn't build the agent. It showed up. It's reading your help center to close a support ticket, filling out your checkout form on someone's behalf, or pulling structured data off a page you built for a person's eyes. Nobody asked whether your interface was ready for that.

The best writing on this makes a simple point. An agent has a goal, an interface, and a result, which is the same shape as a person doing a task. So the advice lands on accessibility work most teams owed anyway: label things, keep the structure predictable, stop shipping buttons that are only an icon.

That is correct and it is not enough. It gives a designer nothing to measure on a Friday with a review due. There is no test for whether a screen is readable by an agent, and no way to decide what to fix first when the deadline forces a choice.

That's the actual gap, and it's smaller than a new discipline. It's a checklist, and on any interface it lives in exactly three places.

03Affordances stop being implied

A person reads a raised button, a filled background, and a hover state as "click here," and reads a grayed-out one as "not yet." An agent parsing a DOM or an accessibility tree gets none of that for free unless the state is declared somewhere it can actually check: a label, an aria attribute, a disabled flag. The visual hierarchy that makes a screen feel calm to a person is invisible to a parser. So the affordance has to exist twice. Once as weight and color for the eye. Once as a stated, checkable property for whatever else is reading.

I built this without naming it, on Scarlett, a personal AI assistant I designed end to end. Every action on the surface obeys a verb law: Scarlett can draft, remind, watch, propose, and compare. Only the person can send, book, confirm, approve, and decide. That split was built to earn a human's trust, capability-honest copy like "only you press send" shipped verbatim because people needed the limit stated, not implied. It turns out the same split is close to the cleanest API contract available. An agent reading that surface doesn't have to infer what's safe to call. The verb already tells it.

FIG. 02 · ONE BUTTON, TWICE A dithered send button beside its declared-property ledger row: role, aria-disabled, label.
The same button as a human reads it and as an agent reads it.

04Error states stop being allowed to be vague

"Something went wrong, try again" works fine for a person, who brings judgment, memory of what they were doing a minute ago, and the option to just stop. An agent retrying blindly against a vague error can loop, repeat a side effect it already completed, or read a partial failure as success and move on to the next step. The fix isn't friendlier copy. It's specificity: which part failed, whether retrying is safe, what state the system is actually in right now. A human benefits from that detail too. It just isn't the thing that breaks them when it's missing.

FIG. 03 · TWO RETRIES A spiraling retry trace with repeated x marks beside a straight labeled trace ending in a stop block.
A vague error loops with side effects; a specific one ends in a clean stop.

05Provenance is where the two readers agree

This is the one place agent legibility and human trust stop trading off against each other. On Scarlett, every claim on every screen traces to a source you can name: an insight ties to the email that produced it, a draft cites the thread it's answering, the Context Inspector shows exactly what the system has learned about you and lets you correct it. That rule got written for a person deciding whether to trust an assistant with their inbox. It would satisfy an agent auditing the same claim too, provided the source is structured somewhere a machine can parse it and not just written into a sentence a person reads. That qualifier is the actual work. A citation is agent-legible the moment it stops being prose only a human can follow.

Articos runs on the same instinct one layer down, in research rather than assistance. The model never sees the hypothesis. The eval harness is written down. A reader can follow any claim back to its source in half an hour.

None of that was built for agents. It turns out that showing your work to a doubtful person gets you most of the way to showing it to a doubtful machine. What is left is formatting the trail so something other than a person can walk it.

06A checklist, run against what you already shipped

Pick a screen you built for people and ask it four questions. Where does an affordance live entirely in color or weight, with no declared state a caller could check? Where does an error message apologize instead of naming what failed and whether retrying is safe? Where does a claim on the screen have no traceable source, for a human or for anything reading alongside one? And where would supervising an agent's action actually require more than the confirm-and-audit-trail pattern you'd design for a person anyway?

That last question matters most. Most interfaces do not need rebuilding for agents. They need the review step they should have shipped already.

I made the approval-gate case in AI as a Design Material and it carries over almost unchanged. Build the harness that lets a person catch a wrong answer that sounds right, and you have most of the harness an agent needs standing over it too. The decision layer under an agent's interface is the same layer either reader leans on.

07Where this leaves the practice

Strip away the platform pitch and agent experience design is three edits to something you already shipped. Make the affordance clear. Make the error say what went wrong. Show where the number came from. You were probably underbuilding all three for people too.

The one new thing is the second reader. It notices immediately, and it never complains.

Which of your product's error states would actually survive an agent retrying against it without a human stepping in? That's usually the fastest way to find where to start.

The Scarlett case study walks through the rest of the verb law, if you want to see where the split holds up against a real inbox instead of an argument.

08References

09Further study

Branching by what you are actually trying to do next.

If you are about to run the checklist on a screen you already shipped.

If your error states are where you are starting.

If you are deciding what your product should declare to the agents arriving.