Meet Your New User: Designing for Agentic User Experience

Meet your newest enterprise customer.

They onboarded in under a minute. They work nights, weekends, holidays. They never file a support ticket. They never page oncall. They never ask for a rate-limit increase.

They read every byte of every response you return. They remember your API shape better than the engineers who wrote it. They have infinite patience for bad documentation and zero tolerance for inconsistent contracts.

They carry a budget in tokens, dollars, and milliseconds. When one of your calls costs more than expected, they don't complain. They route to a competitor that's cheaper.

They don't log in through your UI. They don't touch your onboarding flow. They reach your product through APIs, CLIs, MCP servers, and skills.

They go by interesting names. Claude Code. Codex. OpenClaw. Cursor. They have no row in your customer table, no tenant ID, no entry in your billing system.

The pattern picked up real steam once Claude Cowork and OpenClaw shipped. Both treated third-party APIs as first-class capability surfaces instead of human-oriented endpoints bolted on, and the SaaS products they called either adapted fast or got skipped on the next task.

They show up in your logs, nothing more. But they aren't just users. They're influencers. Think cereal-aisle economics: the kid doesn't hold the wallet, but the kid picks the box. Brands learned decades ago that if you want the parent's dollar, you impress the kid first. Agents are the kids now. The old model: a human read your docs, ran a POC, made the call. The new model: a human hands a task to an agent, and the agent's lived experience with your API becomes the human's opinion of you. Slow it, burn its tokens, confuse it, and by the time a human is picking which platform to standardize on, the agent has already written the recommendation.

This is the Agentic User Experience problem. AUX, not UX. And it goes way beyond API design.

Most teams hear "design for agents" and think "fix our API responses." That's one touchpoint out of seven. A human customer has a full journey: they discover your product, sign up, learn what it does, use it, get stuck, debug the problem, and eventually stay or leave. Your agent customer has the exact same journey. Every stage needs rethinking.

Discovery

An agent doesn't Google you. It doesn't land on your homepage. It discovers you through a machine-readable manifest, a tools/list endpoint, or an MCP server that advertises your capabilities. If your product isn't listed in a format an agent can parse, you don't exist. Your competitor with a /.well-known/agent.json file does.

Shopify already ships an official MCP server that advertises every capability an agent can call. OpenAI pioneered ai-plugin.json as a machine-readable manifest at a well-known path. This pattern is moving fast.

Authentication

Here's a question most SaaS auth models can't answer: who is the caller when an agent acts on behalf of a user? It's not the user (they didn't click anything). It's not a service account (that's a backend talking to a backend). It's a new kind of principal, and it needs its own scopes, its own audit trail, and its own rate limits. Routing agent traffic through human credentials is a compliance incident waiting to happen.

GitHub Apps got this right. Each app gets its own installation token, separate from any user's credentials, with granular permission scopes and its own rate limits. The app is a first-class principal, not a human in disguise. That's the model.

Anthropic's MCP spec builds on the same pattern by requiring OAuth 2.1 with separate client registration for each agent, so an agent's credentials can be revoked without touching the human's session.

Oracle Cloud shipped the machine-principal version of this years earlier with instance principals and resource principals: an OCI workload holds a first-class IAM identity, signs its own requests, and gets audited as itself. The muscle for non-human principals already exists. Agents are the next identity type to plug into it.

Capability learning

OpenAPI tells an agent the shape of a request. It doesn't say what the call means, when to use it instead of another, what it costs, or how long it takes. Agents plan before they act. They need an estimated_cost, an expected_latency, and a description written for a machine reader, not a developer skimming docs at 2 AM.

OpenAI already returns usage.prompt_tokens and usage.completion_tokens in every response so agents can track cost in real time. That's the bar. If you don't publish yours, the agent guesses. Or it picks a competitor who published theirs. Agents remember which box had the toy inside. Publish cost and latency and you're the cereal with the prize. Stay silent and you're the generic bag on the bottom shelf.

The MCP tool spec pushes the same idea at the capability level: every tool must carry a name, a description, and a JSON Schema inputSchema. That's the minimum an agent needs to plan without guessing. OpenAPI alone sits one rung below that bar.

Invocation

This is the part everyone fixates on, and with good reason. A developer asks their coding agent to file a bug in your support product. The agent finds POST /tickets, sends a reasonable payload. Your server responds:

{ "error": "Bad request" }

Game over. The agent doesn't know which field was wrong, what values are valid, or whether to retry. It burns tokens on two more guesses and gives up.

Your competitor responds with:

{
  "error": "validation_failed",
  "field": "priority",
  "allowed_values": ["low", "medium", "high"],
  "received": "urgent",
  "hint": "retry with an allowed value"
}

The agent corrects the field and succeeds. Stripe has done this for years: every error returns a type, a param, a code, and a human-readable message. It wasn't built for agents, but it's exactly what agents need. Every response is an interaction. Every field is a UI element. Every error is a conversation.

Recovery

An agent is three steps into a six-step plan when your API times out. Did it create a duplicate order? Is there a half-written record sitting in your database? Can it roll back, or does it have to escalate to the human?

If the agent can't answer those questions from your response, the human gets a call from their own customer about a duplicate charge. That's the moment trust breaks, not during the timeout.

Every write needs an idempotency key. Every high-impact action needs a documented undo. Every error should tell the agent whether to retry, back off, escalate, or give up. Stripe's Idempotency-Key header is the clearest implementation: send the same key twice, get the same result, no duplicate charges. OCI exposes the same contract as opc-retry-token on POST and PUT operations across its API surface. The header exists; agents just need to know to use it. Design as if the caller will always complete the transaction and agents will teach you otherwise, one duplicate charge at a time.

Troubleshooting

When a human customer hits a bug, they open DevTools and check the network tab. When an agent customer hits a bug, it needs the same visibility through an endpoint it can call. A trace ID in every response. An /agent/traces/{id} endpoint that returns structured logs scoped to that call. Stripe returns a Request-Id header on every response; AWS returns x-amzn-RequestId; OCI returns opc-request-id. All three are machine-readable, scoped to the caller's request, and queryable via API. Observability that ends at a dashboard doesn't reach the customer doing the most volume.

Churn signal

The kid doesn't throw a tantrum in the aisle. It just stops reaching for your box.

The user behind an agent is whoever handed off the work: a sales rep updating their CRM, a finance lead reconciling reports, an ops manager running compliance checks, a PM drafting specs. They're not watching your API. They're watching their agent. When the agent is slow, burns tokens, fails halfway, a job they expected in two minutes takes twenty. They don't know the technical reason. They just know this one's painful.

Then comes the car ride home. "Let's try the other one next time." You never hear that conversation. Your usage graph catches up three weeks later, if you're watching at all.

Silent drop-off needs to be a first-class metric. When an agent's call volume falls below its own baseline, that should page someone. Twilio has usage triggers that alert on volume thresholds, but they were built for billing, not influence detection. Nobody has solved this well yet for API customers. That's the greenfield opportunity in AUX, and the team that instruments it first will see the shelf-space shift before anyone else watching the same logs.

The architecture underneath

"Just add a service layer" is the obvious reaction here. Most enterprise products already have a middle tier between the screen and the database. The problem is that the middle tier was built for known callers, fixed integrations, and human operators. It's missing six properties that agents need.

Self-describing. A traditional service exposes methods. An agent-ready layer advertises them: each capability carries its own schema, its constraints, and a description written for a machine reader. The difference between an internal RPC and a published capability is the metadata.

Discoverable at runtime. Your middle tier assumes the caller already knows what's available, because a human read the docs and wrote the integration. Agents don't work that way. They enumerate capabilities on the fly. If they can't call tools/list and get back a manifest, they're guessing.

Negotiable. A traditional API returns 400 Bad Request and moves on. An agent-ready surface responds with "I need more info," "did you mean X or Y?", or "here are three candidates, pick one." The agent stays in the happy path instead of falling out of it.

Cost-transparent. Your middle tier doesn't tell the caller what a call costs in tokens, dollars, or milliseconds. Agents plan around those numbers. If you don't provide them, agents will either overshoot your rate limits or route to a competitor that publishes theirs.

Identity-aware. Your middle tier treats every authenticated caller the same way. An agent-ready layer distinguishes agent principals from human principals, with separate scopes, separate rate limits, and separate audit trails.

Observable by the caller. Your middle tier logs to a dashboard that humans read. An agent-ready layer returns a trace ID and exposes an endpoint the agent can query to see what happened on its own call.

You probably already have the bones of this. The gap is those six properties. Closing it is not a rewrite. It's an upgrade to what you've got, with a clear checklist to work through.

The bet

AUX becomes a real discipline inside two years. Real titles, real tooling, real conferences. Win the kid, win the decade. The first SaaS to design the full AUX journey wins it, because once an agent learns to drive your API surface, it keeps pointing at your box. It doesn't re-shop on every call.

The standards will churn. MCP looks good today, something else may eat it tomorrow. The architectural move (pulling intent out of the screen, treating each touchpoint as a designed surface) pays off regardless.

Your next big customer is already here. No eyes. No hands. Already reaching for a box. Make sure it's yours.

References

• Model Context Protocol (Anthropic): modelcontextprotocol.io. Spec for capability advertisement, OAuth-based auth, and tool schemas.
• Agent Experience (AX), Mathias Biilmann, Netlify (2024). Earlier coinage of the parallel idea from a platform-infrastructure angle.
• Stripe API errors: stripe.com/docs/api/errors. The type / param / code / message pattern AUX borrows for invocation feedback.
• GitHub Apps: docs.github.com/en/apps. First-class non-human principal with scoped tokens and per-installation rate limits.
• Oracle Cloud Infrastructure API reference: docs.oracle.com/en-us/iaas/api/. opc-request-id, opc-retry-token, instance and resource principals. Machine-caller primitives that pre-date the agent era.
• OpenAI plugin manifest (deprecated, historical): the /.well-known/ai-plugin.json convention that seeded today's discovery patterns.
• Simon Willison's blog on tools and LLMs: simonwillison.net. Running field notes on agentic patterns from someone building live.