How to design an agent approval flow users actually understand

Approval flows are where AI agent products earn or lose user trust. When an agent proposes to send an email to 5,000 customers, or delete a database record, or submit a form on a user's behalf, the moment of approval is a test. Does the user understand what they're approving? Do they feel in control? Do they trust the outcome?

Most teams design approval flows that fail this test — not because they don't care, but because approval UI is surprisingly hard to get right. Here's a breakdown of the key design decisions and the patterns that work.

The fundamental challenge: decision quality under uncertainty

When a human approves an agent action, they're making a decision with incomplete information and time pressure. They don't know all the context the agent had. They may not be experts in the domain. And they're probably being asked mid-task, without full attention.

Good approval UX minimizes this decision-quality problem. It surfaces the right context at the right level of detail, makes the consequences of each choice legible, and structures the decision so the default action is the safer one when in doubt.

What every approval card must communicate

Before thinking about layout or visual design, establish what information the user needs:

The proposed action, in plain language. Not "execute_campaign(segment='churned', template='winback-v3')" — that's the function signature. Write "Send win-back email to 2,400 churned customers." If your users are engineers, you can add the technical details — but lead with the human-readable description.

The scope and scale. How many records? How many dollars? How many messages? The answer to "what does approving this do?" should be answerable in a single glance at a number. "2,400 emails" is scannable. "all churned customers in the Q3 cohort" requires the user to calculate. Show the number.

The context that triggered it. Why is the agent proposing this action? What user request or workflow step led here? This context is what lets the approver check whether the agent understood correctly.

What happens if they approve. Immediate and downstream effects, clearly stated.

What happens if they reject. Does the agent continue with a different approach? Does it stop? Does it ask for clarification? Rejection shouldn't feel like a dead end.

The three-second rule

A well-designed approval card should be legible in three seconds. If a user needs more than three seconds to understand what they're being asked to approve, the design has failed.

Test your approval cards with the three-second rule: show the card to someone unfamiliar with the current context for three seconds, then hide it. Can they tell you what action they were being asked to approve? What the scale is? Whether they'd approve or reject?

If not, the card needs more hierarchy, clearer labeling, or less information. Often it's all three.

Visual design principles

Yellow, not red. Red approval cards feel alarming, which introduces anxiety that distorts decision-making. Yellow (amber) communicates "attention required" without panic. Reserve red for genuinely destructive actions (deleting data, sending to a blocked list, actions that can't be reversed).

The action should be the largest text. The hierarchy of the card: action (largest) → scope/scale → context → consequences → buttons. Most teams invert this: they lead with a badge or label, bury the action in body text, and make the buttons enormous. This forces the user to work harder to extract the key information.

Approve should be visually heavier than reject. For actions the agent is confident about, the approve button should be more visually prominent. This is intentional design: it reflects the agent's confidence while leaving the user in control. For genuinely ambiguous cases, the buttons should be equal weight.

Good approval UX doesn't just prevent mistakes — it builds calibrated trust. Users who understand what they're approving become better judges of their agent over time.

State management

Approval cards have states that need careful handling:

• Pending: Awaiting user action. Should feel active and requiring attention.
• Approved: User approved. Show confirmation and outcome clearly. Don't leave the card empty after approval.
• Rejected: User rejected. Show what the agent will do next. Don't leave a void.
• Expired: The window for approval passed. Show when it expired and what happened as a result.
• Superseded: The action is no longer relevant because something else changed. Explain why and clean up the card.

Most implementations only handle Pending and Approved. The other states are where users get confused and trust erodes.

When to require approval vs. proceed automatically

Not every agent action needs human approval. The question is how to decide which ones do. A useful framework:

• Require approval if the action is irreversible, high-scale, has downstream effects, or involves external parties (emails, payments, API calls to third-party services).
• Proceed automatically if the action is reversible, low-scale, internal only, and the agent's confidence is high.
• Log but proceed for actions that are automatically executed but should be auditable.

The approval threshold should be configurable by users. What a risk-tolerant power user wants to auto-approve is different from what a cautious enterprise user wants. Build the configuration surface; don't hard-code the defaults.