# Agentic UX patterns — designing a surface where an agent acts for the user

_Load when the generated or composed surface includes an AI agent taking actions on the
user's behalf — a gen-UI experience (`gen-ui-wiring`), an assistant/chat surface (`llm-wiring`),
or any screen where the system decides and acts rather than only responding. This is the UX
design layer, not the runtime plumbing: `gen-ui-wiring` mounts and validates; this reference
answers "what does a trustworthy agent surface actually need to show."_

An agent surface creates design problems ordinary UI does not: the agent **takes actions**,
and the user must be able to **understand, control, trust, and recover from** those actions.
A gen-UI experience that renders validated A2UI but never shows the user what the agent is
about to do, or how to undo it, is technically working and experientially broken.

(Claims re-verified against the kit's live source 2026-08-26; re-verify on a MINOR cut.)

## The mental model comes first

Before any of the six patterns below, name the frame the user carries into the interaction —
their ability to *predict* the agent's behavior is what determines whether they trust it:

- **What kind of thing is this?** — a tool, an assistant, an advisor, or a delegate. Each sets
  a different expectation for how much the agent should decide on its own.
- **What does it decide autonomously vs. ask permission for?**
- **What can go wrong, and who is responsible when it does?**
- **What controls does the user hold?**

An agent surface with no stated mental model leaves each screen inventing one independently —
the same product feels like a passive tool on one screen and an autonomous delegate on the
next. Name it once, design every surface to it.

## The six patterns

Map each to a concrete AdiaUI surface — the pattern is the requirement; the primitive is the
realization. Where a pattern doesn't apply to a given surface, state **N/A with a one-line
reason** rather than silently omitting it — a silent omission reads as "not considered."

| Pattern | Phase | What it requires | AdiaUI realization |
|---|---|---|---|
| **Intent preview** | Pre-action | Show the plan *before* execution — the user sees what the agent will do and gets Proceed / Edit / Cancel. Identify where these moments occur and what the preview surface is. | `confirm-dialog-ui` (a `modal-ui` variant) with the planned action steps as a `list-ui`; the three choices as `button-ui` (primary Proceed, ghost Edit, ghost Cancel). For a streamed gen-UI plan, a `card-ui` preview region that the user commits before the runtime serializes. |
| **Autonomy dial** | Pre-action | Let users calibrate independence **per task type, not globally** — map each task type to its spectrum (suggest-only → act-and-notify). | A per-task-type control surface: `segmented-ui` (suggest / confirm / auto) per row in a settings `list-ui`, or `select-ui` per task. Never one global toggle — that collapses the dimension the pattern exists to expose. |
| **Explainable rationale** | In-action | The agent grounds its action in user-set context: "Because you selected auto-pay, I charged your card on file." Specify when and where rationale shows. | Inline `text-ui variant="caption"` beneath the acted-on element, or an `alert-ui variant="info"` on the action result. The rationale cites the user's own prior choice, not model internals. |
| **Confidence signals** | In-action | Disclose uncertainty — specify how (score, copy, visual) and the threshold at which it's surfaced. | A `badge-ui` or `tag-ui` tone tied to a confidence band (never `--a-data-*` series colors — use semantic tones: `success` high, `warning` low); or a `progress-ui` meter for a continuous score. Below the disclosure threshold, escalate (last pattern) rather than proceed silently. |
| **Action audit & undo** | Post-action | Every agent action logged with a reversal option — specify the audit surface, undo scope, and time bounds. | A `feed-ui` / `list-ui` action log with a per-entry ghost `button-ui` "Undo" bounded to the reversal window; a `toast-ui` with an inline Undo affordance immediately after the action for the common case. |
| **Escalation pathway** | Post-action | Know when to hand off to a human — identify which decision types require human judgment, the hand-off surface, and the target escalation rate. | An `alert-ui variant="warning"` + a `button-ui` routing to the human path when confidence is below threshold or the decision type is flagged human-only. The escalation is a designed exit, not an error state. |

## Applying it

1. State the mental model (one sentence: "this is a delegate that acts within limits you set").
2. Walk the six patterns; for each, either place a concrete AdiaUI surface or write N/A + reason.
3. Pre-action patterns (preview, autonomy) gate the runtime **before** `gen-ui-wiring`'s trust
   gate serializes — the user's Proceed is upstream of `root.doc =`, not a post-render regret.
4. In-action + post-action patterns (rationale, confidence, audit/undo, escalation) are part
   of the generated or composed surface itself — they render alongside the agent's output.

## Boundary

This reference is the UX contract for the surface; it does **not** own the runtime lifecycle
(mount / validate / resolve / render — that's `gen-ui-wiring`'s own loop and trust gate) or the
generation pipeline (maintainer territory, `adia-forge`'s `a2ui-maintenance`). A preview surface the
user commits before generation serializes is this reference feeding `gen-ui-wiring`'s step 3, not
a replacement for it.

_Provenance: the six-pattern taxonomy is an industry synthesis (Smashing Magazine / Eleken,
2026); the AdiaUI realizations are this plugin's own mapping onto the current primitive
catalog — verify a named primitive against the live catalog (`mcp__a2ui__lookup_component`)
before relying on a specific prop._