UX for AI agents: design APIs that deliver a result people can trust

A shopper asks an assistant to find a replacement part that fits their machine and arrives before Friday. Returning twenty product descriptions is information. Returning a compatible option, a destination-specific quote, the remaining uncertainty and a review step is a usable result. The distinction is an experience-design problem.

The person remains the beneficiary and decision owner. The agent is an intermediary with its own limits: incomplete context, ambiguous tool names, stale facts and failure-prone execution. UX for agents means designing the shared journey so both the machine and the person can understand what is possible, what happened and what still needs a decision.

Agent-first design starts with a task, not a screen

Agent-first is a design priority, not a requirement to remove the human interface. Begin by modeling goals, constraints, allowed actions and observable results. Then decide which steps should be exposed as tools and which need a person’s judgment. A conversational facade over an ambiguous workflow preserves the underlying ambiguity.

Map each important UI state to a machine-readable state: loading to a pending operation, an empty result to a reason, a disabled control to an unmet prerequisite, confirmation to an authorization record, and success to a verifiable receipt. Keep the screen and API tied to the same business rules. Otherwise a person and an agent may receive conflicting answers to the same task.

Decide what the agent should ask rather than infer. Budget, delivery address, risk tolerance and consent may need explicit input. Make safe defaults clear, allow correction and preserve the reason for a choice. For a design review, compare the human journey and agent journey side by side using the same task and failure cases.

Start with the outcome contract

Before designing endpoints, write one task: “Prepare a quote for an exact compatible variant within a stated budget; do not place an order.” Define accepted evidence: the variant, compatibility basis, full known costs, delivery estimate, expiration and unresolved conditions. A result can be useful even when the answer is “no eligible option.”

Make exclusions explicit. “No matches” is different from “catalog unavailable.” “Tax not calculated” is different from zero tax. “Estimated delivery” is different from a promised arrival date. If an agent cannot distinguish these states, it cannot reliably explain them to a person.

Give each tool one understandable job

Use names and descriptions that express what the operation does and its side effects. Separate finding products, preparing a quote and submitting an approved order. Define required inputs, allowed values, units, currency, nullability, pagination and bounded response sizes. Return the fields needed for the next decision instead of forcing the agent to interpret a large prose blob.

The MCP tools specification, June 18, 2025 revision, describes input and optional output schemas, structured results and tool errors. MCP can expose a workflow to compatible clients; it does not replace the underlying service, implement authorization for you, or guarantee discovery by every assistant.

Design the state changes before the happy path

This is a proposed design, not a universal commerce standard. Some services have different reservation, payment and fulfillment states. Model the real business process and make those distinctions visible.

Return enough evidence to explain the decision

The following is a fictional response contract. The identifiers, price and dates are illustrative, not a live offer or production endpoint. It demonstrates a review-required quote with a source and a limit on freshness.

{
  "status": "requires_review",
  "quote_id": "quote_example",
  "quote_version": 3,
  "items": [{"variant_id": "part_example", "quantity": 1}],
  "total": {"amount_minor": 12900, "currency": "USD"},
  "costs_complete": true,
  "destination_verified": true,
  "expires_at": "2026-11-07T15:05:00Z",
  "evidence": [{
    "field": "compatibility",
    "source_url": "https://example.com/parts/part_example",
    "checked_at": "2026-11-07T15:00:00Z"
  }],
  "next_action": "open_secure_review",
  "warnings": []
}

Use an HTTPS handoff scoped to the right user and quote. Do not embed payment secrets or personal information in public URLs. A field called “approved” sent by the agent is not proof of approval: the server must enforce identity, permissions and the authorization record. If the price or items change, invalidate stale approval and present the revised terms.

Make retries safe and errors actionable

After a timeout, the caller should be able to query the operation’s state before trying again. Use a stable idempotency key for the same intended write, and document the scope, retention period and behavior when parameters differ. Stripe’s idempotent-request documentation provides a concrete example of this pattern; its exact semantics vary by API version and should not be assumed for another provider.

Return stable error codes such as QUOTE_EXPIRED, VARIANT_UNAVAILABLE or REAUTH_REQUIRED, with safe next actions. Mark whether retrying is appropriate. Respect rate limits and avoid unbounded retries. Never describe an accepted background job as completed until its authoritative result is known.

Keep the human interface in the loop

A review screen should summarize the exact action, total, destination, timing and recurring obligations where relevant. Provide edit, decline and recovery options. Consent should describe the task scope: comparing options, preparing an order or buying within an approved mandate are different permissions.

When the customer takes over, preserve the relevant context without transferring unnecessary private data. Accessible forms, keyboard operation and clear errors matter because this may be the moment automation hands the task back to someone under time pressure. An API complements a usable website.

Test the journey as a product

Create a fixed set of realistic tasks with expected outputs. Include missing inputs, ambiguous products, expired quotes, changed prices, duplicate requests, revoked authorization, unavailable inventory and slow responses. Use synthetic accounts and a sandbox. Record the model, harness, integration version, task count and success definition so the exercise is repeatable.

Do not optimize away helpful clarification just to reduce the number of calls. A slower, correct decision can be better than a fast irreversible mistake. Passing a small task set establishes operational evidence; proving customer or revenue improvement requires a suitable live evaluation.

A designer’s deliverable for the next sprint

1. One task and its success criteria.
2. A map of states, permissions and owner decisions.
3. An input/output contract with examples and unknown states.
4. A review and human-handoff prototype.
5. A failure matrix and evaluation scorecard.

Start with a read-only lookup or reviewable quote before adding an irreversible action. Use the UX decision checklist to record the task and evidence. The research brief supplies the commercial context, while the recommendations here are original design proposals to test.

Continue with the companion guides

• AI shopping, experiment bias, and the difference between retention and loyalty
• The web after AI agents: build for decisions and completed work

Published November 7, 2026. Recommendations and scenarios are editorial proposals, not measured portfolio or client outcomes.

Keep exploring

A better-looking redesign is a hypothesis. Here is how to test it.

How to prioritize UX friction without giving your product a made-up score