Agent experience: How to design products that agents can actually use

There is a new class of user interacting with your product. It does not read tooltips. It does not recover gracefully from ambiguous error messages. It cannot solve a CAPTCHA, infer intent from layout, or remember context between sessions unless you give it that context explicitly. It operates at machine speed, retries aggressively, and will make decisions based entirely on what you surface to it in text.

That user is an AI agent. And most products are not designed for it.

Agent experience (AX) is the full design layer between your product and the agents that use it, whether those agents are built by you, by your customers, or by third parties connecting to your API. Getting it right is not a nice-to-have. As agent-driven workflows become the default way software gets used, your AX is increasingly your product's interface to an enormous share of its traffic.

This is a practical guide to designing for that reality, across two surfaces: building platforms and APIs that agents consume well, and building agent-powered products that give human users enough visibility and control to actually trust them.

Part 1: Designing platforms and APIs for agents

Agents are API-first users, whether you like it or not

If your product has a public API, agents are already using it. The question is whether you designed for that or whether they are fighting the interface you built for humans.

The products that agents use most fluently share a set of traits that are largely orthogonal to what makes a good human UX. They are explicit over implicit. They fail loudly. They are stateless by default. They return structured, parseable data. They document edge cases as carefully as happy paths.

Stripe is the canonical example. Its API has been the gold standard for developer experience for over a decade, and it turns out that what makes it great for developers makes it exceptional for agents: consistent object shapes, predictable error codes, idempotency keys, exhaustive documentation, and a changelog that treats breaking changes as a serious event. An agent calling the Stripe API can reliably interpret what happened, handle errors without guessing, and retry safely. That is not an accident.

Contrast this with products where critical functionality lives only in the UI, where there is no API equivalent for a button that exists on a dashboard, where bulk operations require clicking through a paginated table, or where authentication flows depend on browser session state. Agents either cannot use these products at all, or they resort to brittle browser automation that breaks every time the layout changes.

The practical implication: if your product roadmap does not treat API parity with the UI as a first-class requirement, you are accumulating AX debt that will cost you as agent-driven workflows scale.

Principle: Prefer explicit over implicit

Human users are good at resolving ambiguity. They read context, make inferences, and ask for help when they are confused. Agents are not good at this. They will pick an interpretation and run with it, often confidently and often wrong.

This shows up in a few specific places:

• ‍Error messages. A human seeing "something went wrong" will look around for more context. An agent will either retry blindly or fail silently. Good AX requires error messages that are machine-readable (a stable error code, not just an HTTP status), specific (what went wrong, not that something did), and actionable (what the caller should do next). Resend does this well. Its API returns structured error objects with a name field (missing_required_field, invalid_to, daily_sending_quota_exceeded), a human-readable message, and links to relevant documentation. An agent calling Resend can branch on the error name without parsing strings. That is a design decision, not a side effect of being a good API.‍
• Object states. If a resource in your system can be in multiple states, enumerate them explicitly and document what transitions are valid. Do not rely on implicit conventions ("if the completed_at field is null, it is still in progress") when an explicit status field with documented values would be clearer. Agents will use whatever you give them. Give them something unambiguous.‍
• Pagination and limits. Document your rate limits, pagination cursor behavior, and what happens at the edges. What does an empty page look like versus an error? What is the maximum page size? An agent hitting an undocumented rate limit with no guidance will retry in a way that makes the problem worse.

Principle: Design for idempotency

Agents retry. Networks fail. Operations time out. If your API does not support idempotent operations for anything that has side effects, agents will occasionally do things twice and you will have no clean way to prevent it.

Idempotency keys are the right pattern here. Stripe pioneered them; the model is simple. The caller generates a unique key for each logical operation and passes it in a header. The server deduplicates on that key within a time window. The caller can retry freely without risk of double-execution.

This matters more as agent workflows become longer and more complex. A 10-step workflow that fails on step 8 needs to be retryable from the point of failure, not from scratch. If steps 1 through 7 are not idempotent, retrying means side effects accumulate.

Anti-pattern: POST endpoints that create resources with no idempotency support, combined with non-specific errors that make it unclear whether the operation succeeded or failed. This is a recipe for duplicate records at scale.

Principle: make structure explicit in your data model

Agents parse text. The more structure you put in your API responses, the less parsing they need to do, and the less room there is for misinterpretation.

A few common failure modes:

• ‍Putting structured data in strings. A field like "metadata": "priority:high; due:2025-06-01; assignee:alex" is parseable by a human at a glance. An agent has to write custom parsing logic for it, and that logic will break the moment the format changes slightly. The right shape is "metadata": { "priority": "high", "due": "2025-06-01", "assignee": "alex" }. This is not a new principle; it is good API design that becomes critical when agents are consumers.‍
• Inconsistent field naming. If some endpoints use user_id and others use userId or author or created_by for semantically equivalent fields, agents have to maintain a mental map of your inconsistencies. This is exactly the kind of implicit knowledge that human developers acquire over time and agents cannot. Audit your field names across endpoints and normalize them.‍
• Untyped or loosely typed fields. Fields that can be a string, a number, or null depending on context force agents to handle multiple cases. Pick a type and be consistent. If the type genuinely needs to vary, document the conditions explicitly.

Principle: Give agents a way to understand your schema

The best AX investment you can make for API consumers is a well-maintained OpenAPI spec. This is not a new idea, but it has taken on new urgency: most LLM-based agents can consume an OpenAPI spec directly and use it to understand how to call your API without any additional prompting.

Linear publishes a complete GraphQL schema. Stripe's OpenAPI spec is maintained in a public GitHub repo and is comprehensive enough that third-party SDK generators use it as their source of truth. GitHub's spec covers thousands of endpoints with full parameter documentation.

If your API has no machine-readable schema, agents connecting to it are working from documentation written for humans, which is slower, more error-prone, and depends on the quality of your prose. A complete OpenAPI or GraphQL schema removes that dependency entirely.

The UI-only anti-pattern

One of the most common and costly AX failures is functionality that exists only in the UI with no API equivalent. This forces agent workflows into browser automation, which is fragile, slow, and maintenance-intensive.

The specific failure mode: a product adds a feature to the web dashboard, ships it, and never builds the API version because "the API is for developers, not for this use case." That calculus made sense in 2015. It does not make sense when the primary consumer of your product in 2026 is an agent running a workflow.

Webflow's early API had significant gaps between what you could do in the designer and what was available programmatically. Notion launched with almost no API for years, which made it a dead end for any automated workflow. Both eventually invested heavily in their APIs, in part because the gap between UI and API capability was becoming a competitive liability.

The pattern to internalize: anything a human user can do in your product should be achievable programmatically. If it cannot be, document that explicitly so agents can fail fast rather than attempting and failing in unexpected ways.

Part 2: Designing agent-powered products for human users

The core design problem

When you put an agent in the middle of a user's workflow, you change the fundamental contract of the product. The user is no longer operating the software directly. They are delegating to a system that will make decisions on their behalf, take actions with real consequences, and occasionally be wrong.

Most products treat this as a model quality problem. It is not, or at least not primarily. It is a design problem. The question is not just whether the agent does the right thing, but whether the human understands what happened, trusts the outcome appropriately, and has enough control to catch and correct errors before they compound.

Pattern: make the agent's reasoning visible

The single highest-leverage AX decision in an agent-powered product is how much of the agent's reasoning you surface to the user.

The temptation is to hide it. It feels cleaner. A spinner and a result feels like a finished product. Streaming reasoning feels like a rough edge.

The products that build durable user trust do the opposite. Cursor shows which files the agent read, which it is about to modify, and why. Perplexity shows its sources before it shows its answer. Linear's AI summarizes the specific comments and history it used to generate a suggestion.

This is not transparency for its own sake. It serves a concrete function: it lets users catch wrong assumptions early, calibrate their trust accurately, and learn how the agent reasons over time so they can brief it better in the future.

Anti-pattern: an agent that presents conclusions without process. "I've reorganized your project" with no explanation of what changed or why. The user now has to audit the entire output to understand what happened, which is more work than if they had done it themselves.

Pattern: stream the agent's step log in a scannable format. Not a prose explanation — a structured trace. File read. Decision made. Action taken. This is inspectable, skimmable, and recoverable.

Pattern: Match autonomy to reversibility

Not all agent actions carry the same risk. The design mistake most teams make is applying a uniform level of confirmation to all of them — either confirming everything (death by dialog box) or confirming nothing (loss of user control on the actions that actually matter).

The right model maps autonomy to two axes: how reversible is the action, and what is its blast radius.

• Reversible, narrow scope (drafting a message, generating a report, writing code to a local branch): let the agent proceed without interruption. The user can review and discard.
• Reversible, broad scope (reorganizing a folder structure, bulk-editing records, modifying shared settings): surface a preview before executing. Show what will change. Let the user approve or narrow the scope.
• Irreversible, any scope (sending an email, publishing content, deleting data, making a purchase): require explicit user initiation. The agent prepares everything and stops. The human presses send.

Zapier's AI features use a version of this model. Automated triggers run without confirmation. Actions that send messages or modify external systems surface a confirmation step by default, which users can remove once they trust the workflow.

Anti-pattern: a uniform "Are you sure?" dialog that appears for both low-stakes and high-stakes actions. Users learn to dismiss it without reading, which eliminates its protective value entirely.

Pattern: design undo as a first-class feature

If your agent takes actions that can be wrong (and they will be wrong) undo is not a nice-to-have. It is a safety primitive that determines whether users will delegate high-stakes work to your product.

The implication is that agents should maintain a structured action log, not just produce an end state. Every action should be recorded with enough context to reconstruct what was done and reverse it. This is harder to build than it sounds, because it requires designing your agent's execution model around reversibility from the start, not as a retrofit.

Notion's AI edits are applied as tracked changes by default. GitHub Copilot's suggested code is a diff against the current file. Cursor's agent mode shows every file change as a reviewable edit before it is committed. These are not accidents of implementation; they are design decisions that make the agent's work auditable and reversible.

Anti-pattern: agents that modify state in place with no history. The user asks the agent to "clean up the document" and the original is gone. This is the fastest path to a user who never delegates to your agent again.

Pattern: Give agents explicit scope boundaries

One of the most common sources of agent errors is acting on stale or broader-than-intended context. The user says "archive old emails" and the agent archives the last six months of correspondence because "old" was never defined.

Good AX requires making scope explicit before execution, not inferring it during execution.

Practical patterns for this:

• ‍Scope confirmation at task start. Before a multi-step task begins, surface the agent's interpretation of the scope and let the user correct it. "I'll archive emails older than 90 days that are not starred and have no pending replies. Does that match what you wanted?" This is one question at the start, not a series of interruptions during execution.‍
• Explicit access grants. Show the user exactly what the agent has access to before it starts. Files, calendars, inboxes, APIs. Make the blast radius legible. Users who can see the agent's access surface delegate more confidently because they understand what is and is not in play.‍
• Session boundaries. Agent memory across sessions is a footgun if not handled explicitly. A standing instruction from three weeks ago should not silently apply to today's task. Make it easy to see what persistent instructions the agent is operating under and revoke them individually.

Pattern: surface uncertainty explicitly

Agents are often wrong with great confidence. The UX of certainty — a clean output, no hedging, no visible alternatives — trains users to over-trust in exactly the cases where the agent is most likely to be wrong.

The better pattern is calibrated confidence. This does not mean wrapping every output in disclaimers. It means signaling uncertainty at the specific points where it is highest.

Perplexity does this at the citation level. Confident claims are cited; uncertain or synthesized claims are marked differently. Cursor's agent will sometimes say explicitly that it is not sure which of two approaches is correct and will present both. These are UX decisions that build accurate mental models over time.

Anti-pattern: uniform confidence across all outputs regardless of actual uncertainty. Users cannot distinguish the agent's strong conclusions from its guesses, so they either distrust everything or trust everything, both of which are failure modes.

The design principles, summarized

For platforms and APIs

• Treat API parity with UI as a product requirement, not a follow-up task.
• Make errors machine-readable: stable codes, specific messages, actionable guidance.
• Design for idempotency on anything with side effects.
• Publish and maintain a complete machine-readable schema.
• Prefer structured data over strings; prefer explicit fields over implicit conventions.

For agent-powered products

• Show reasoning, not just results. Legibility builds calibrated trust.
• Map autonomy to reversibility and blast radius, not to a uniform confirmation model.
• Build undo as a first-class feature from the start, not as a retrofit.
• Make scope explicit before execution; do not let agents infer intent across sessions.
• Signal uncertainty at the point it occurs, not with blanket disclaimers.

What comes next

The products that will win in an agent-first world are the ones that take both sides of this seriously now. That means API teams treating agent consumers as a first-class persona alongside human developers. It means product teams designing the legibility, reversibility, and scope controls that make delegation feel safe rather than reckless.

The interface is no longer just the screen or the API endpoint. It is the full design contract between your product and every system that will act inside it. Most of that design is still unfinished. The teams that finish it first will have a durable advantage over the ones that are still explaining to agents what a loading spinner means.