Resources
Guide · AI Agent UI

Human-in-the-Loop Approval UI for AI Agents

Human-in-the-loop UI is how an AI agent asks a person before it acts. Done well, people approve the right things quickly and say no in a way the agent can use. This guide covers five patterns, when to use each, and the React components for them.

By , product designer and creator of Liro
· 7 min read

An approval is a promise the interface makes: nothing happens until you say so, and what you see is what will happen. Most approval screens break that promise in small ways. They summarise instead of showing the thing itself, they offer only Yes and No, or they turn one “Always allow” into permission for everything. The fixes are mostly about what you show and how narrow the choices are.

The components in this guide are part of Liro Pro. Each code sample was typechecked against them.

Which pattern, when

Start from what the agent needs from the person:

Six rules for asking well

  • Show the thing itself. The email with its recipients, the record's fields before and after, the amount. Not “the agent wants to send an email”.
  • Make no useful. A bare “No” leaves the agent stuck or asking again. Offer reasons in one click and send them back to the agent.
  • Keep grants narrow. “Always” should mean always for this target, not for every target.
  • What cannot be undone always asks. Moving money, emailing outside the company and deleting should not be switchable to automatic.
  • Say the risk in words. Low risk, check first, high risk, with one sentence on why. Colour alone is not enough.
  • Failure keeps the question open. If your server fails to record the decision, the request should stay open with the error, not quietly look approved.

One action: ask before acting

For a single action, show what changes and what it will cost to get it wrong. This refund request uses every safeguard Approval Request has for high-risk actions:

components/approve-refund.tsx
import { ApprovalRequest } from "@/components/ui/approval-request";

export function ApproveRefund({
  approve,
  reject,
  sendBack,
}: {
  approve: () => Promise<void>;
  reject: (reason?: string) => Promise<void>;
  sendBack: (note: string) => Promise<void>;
}) {
  return (
    <ApprovalRequest
      title="Refund $1,240 to Orbit Labs?"
      description="Orbit was charged twice for October. The agent wants to refund the second charge."
      tool="payments.refund"
      risk="high"
      riskExplanation="Money leaves the account and the refund cannot be reversed from here."
      changes={[
        { label: "Invoice INV-2057", before: "Paid twice", after: "Paid once, $1,240 refunded" },
        { label: "Account balance", before: "$18,420", after: "$17,180" },
      ]}
      requireConfirmation
      expiresAt={Date.now() + 30 * 60 * 1000}
      reasons={["Wrong amount", "Check with finance first"]}
      onApprove={approve}
      onReject={reject}
      onRequestChanges={sendBack}
    />
  );
}
  • changes shows each field before and after, so the person checks numbers instead of trusting a sentence.
  • riskExplanation says why it is high risk, and requireConfirmation asks a second time before approving.
  • reasons turns Reject into one click with a reason; onRequestChanges adds a third answer that sends it back to the agent with a note.
  • expiresAt shows a countdown and settles as Expired by itself, so an old request cannot be approved after the moment has passed.

onApprove and onReject may return a promise. While it is pending the buttons wait; if it rejects, the request stays open and shows the error. Once decided, the card folds to a one-line record of the decision; pass decidedBy and decidedAt to say who and when.

A standing right: grant it narrowly

When an agent will need the same right again, asking every time trains people to click Allow without reading. Asking once with clear scopes is better:

components/grant-email.tsx
import { PermissionGrant, type GrantScope } from "@/components/ui/permission-grant";

export function GrantEmail({
  api,
}: {
  api: { grant: (scope: GrantScope) => Promise<void>; deny: (reason?: string) => Promise<void>; revoke: () => Promise<void> };
}) {
  return (
    <PermissionGrant
      agent="Renewal agent"
      tool="email.send"
      target="@vertically.com"
      why="Olivia asked for the signed renewal by email."
      risk="medium"
      allowAnyTarget={false}
      reasons={["Wrong recipient", "Not yet"]}
      onGrant={api.grant}
      onDeny={api.deny}
      onRevoke={api.revoke}
    />
  );
}

Permission Grant offers four scopes, and each says what it covers before it is pressed: once, for an hour, always for this target, and always for any target. The last one is off here with allowAnyTarget={false}; by default it sits behind the overflow menu, marked as wider. With risk="high", an Always grant needs a press and hold, which also works with Space or Enter.

Once granted, the card folds to one line with a live countdown and Revoke, and offers Undo for a few seconds. Pass grants instead and the same component lists every active grant, grouped by agent, each with Revoke.

A batch of changes: preview first

An agent that edits data should show the whole batch before any of it happens. Dry-Run Preview marks each change as create, update or delete, and diffs updates field by field:

components/review-cleanup.tsx
import { DryRunPreview, type DryRunPreviewData } from "@/components/ui/dry-run-preview";

const preview: DryRunPreviewData = {
  id: "cleanup-42",
  title: "Clean up the CRM",
  impactSummary: "3 records change; 1 is deleted.",
  changes: [
    { id: "c1", resource: "Ada Moss", resourceType: "contact", operation: "update", before: { stage: "Lead" }, after: { stage: "Customer" } },
    { id: "c2", resource: "Orbit Labs", resourceType: "company", operation: "update", before: { owner: "Sam" }, after: { owner: "Priya" } },
    { id: "c3", resource: "Test Account 7", resourceType: "company", operation: "delete", before: { plan: "Trial" }, warnings: ["Has 2 open tickets"] },
  ],
};

export function ReviewCleanup({ approve, apply }: { approve: (ids: string[]) => Promise<void>; apply: (ids: string[]) => Promise<void> }) {
  return <DryRunPreview preview={preview} selectable onApprove={approve} onApply={apply} />;
}

Deletes are loud on purpose: each one is red, they are counted at the top, and they are confirmed again before they go. With selectable, people untick the changes they disagree with instead of rejecting the whole batch. Passing both onApprove and onApply makes approving and applying two separate steps, and each change then shows its own result, so a batch that partly failed says exactly which changes did not land.

In settings: how much it may do alone

Per-action approvals work best when the person has also decided, in advance, what the agent may do without asking. Two components cover that:

components/billing-agent-settings.tsx
"use client";

import * as React from "react";
import { AutonomyDial, type AutonomyAction, type AutonomyLevel } from "@/components/ui/autonomy-dial";
import { AgentPermissions, type AgentPermission } from "@/components/ui/agent-permissions";

const actions: AutonomyAction[] = [
  { id: "read", label: "Read invoices and customers", risk: 1 },
  { id: "draft", label: "Draft reminder emails", risk: 2 },
  { id: "note", label: "Add notes to customer records", risk: 2 },
  { id: "send", label: "Email customers", risk: 3, irreversible: "An email cannot be unsent" },
  { id: "refund", label: "Issue refunds", risk: 3, irreversible: "Money leaves the account" },
];

const permissions: AgentPermission[] = [
  { id: "inv-read", resource: "invoices", label: "Read invoices", capability: "read", requested: true, granted: true, riskLevel: "low" },
  { id: "crm-write", resource: "crm", label: "Edit customer records", capability: "write", requested: true, granted: true, riskLevel: "medium" },
  { id: "pay-admin", resource: "payments", label: "Manage payments", capability: "admin", requested: true, granted: false, riskLevel: "high" },
];

export function BillingAgentSettings({ save }: { save: (changes: { id: string; granted: boolean }[]) => Promise<void> }) {
  const [level, setLevel] = React.useState<AutonomyLevel>("balanced");
  return (
    <div className="grid gap-6">
      <AutonomyDial actions={actions} value={level} onChange={setLevel} />
      <AgentPermissions agentName="Billing agent" permissions={permissions} onSave={save} />
    </div>
  );
}

Autonomy Dial has three positions: cautious, balanced and autonomous. Underneath, the agent's actions sit in two columns, “runs on its own” and “asks you first”, so moving the dial shows exactly what changes. Actions marked irreversible stay in “asks you first” at every position, each with its reason. The dial only moves what can be undone.

Agent Permissions keeps what the agent asked for apart from what it is allowed. Nothing is switched on just because the agent requested it, and before Save a summary counts what you are granting and removing. If you need per-tool Off, Ask and Allow switches instead, see Agent Settings.

Many agents: one inbox

Once several agents run in the background, the problem changes from “how do I ask” to “which question is going cold”. Agent Inbox puts tasks that need a person first, oldest wait first, then failures, running, queued and done:

components/approvals-inbox.tsx
import { AgentInbox, type InboxTask } from "@/components/ui/agent-inbox";

export function ApprovalsInbox({
  tasks,
  api,
}: {
  tasks: InboxTask[];
  api: { approve: (id: string) => Promise<void>; reject: (id: string) => Promise<void>; retry: (id: string) => Promise<void> };
}) {
  return (
    <AgentInbox
      tasks={tasks}
      onApprove={api.approve}
      onReject={api.reject}
      onRetry={api.retry}
      onOpen={(id) => window.location.assign(`/runs/${id}`)}
      slowAfter={5}
      staleAfter={30}
    />
  );
}

The clock on each row counts how long the task has waited on a person, not how long it has run. It turns amber after slowAfter minutes and red after staleAfter; 5 and 30 are the defaults, written out here so they are easy to change. Approve, Reject, Retry and Open work in the row.

The server decides

Every component here asks. None of them enforces. A grant shown as “for 1 hour” only expires if your server stops honouring it after an hour, and an approval only protects anything if the tool refuses to run without one. Keep grants on the server, check them right before each tool call, and record every use:

lib/grants.ts
/* Server side. The interface asks; this decides. */

export type Scope = "once" | "hour" | "always-target" | "always-any";

export interface StoredGrant {
  id: string;
  agentId: string;
  tool: string;
  /** "@vertically.com", or "*" for an always-any grant. */
  target: string;
  scope: Scope;
  expiresAt?: number;
  usedAt?: number;
  revokedAt?: number;
}

export function findGrant(
  grants: StoredGrant[],
  call: { agentId: string; tool: string; target: string },
  now = Date.now(),
): StoredGrant | undefined {
  return grants.find(
    (g) =>
      g.agentId === call.agentId &&
      g.tool === call.tool &&
      (g.target === "*" || call.target.endsWith(g.target)) &&
      !g.revokedAt &&
      !(g.expiresAt !== undefined && g.expiresAt <= now) &&
      !(g.scope === "once" && g.usedAt !== undefined),
  );
}

/** Run a tool only if a live grant covers it; otherwise ask a person. */
export async function runTool<T>(
  grants: StoredGrant[],
  call: { agentId: string; tool: string; target: string },
  execute: () => Promise<T>,
  ask: () => Promise<StoredGrant | null>,
  record: (grant: StoredGrant, outcome: "used" | "failed") => Promise<void>,
): Promise<T | "denied"> {
  const grant = findGrant(grants, call) ?? (await ask());
  if (!grant) return "denied";
  try {
    const result = await execute();
    await record(grant, "used");
    return result;
  } catch (error) {
    await record(grant, "failed");
    throw error;
  }
}
Treat the browser as untrusted. Whatever the interface shows, the check that matters is the one in the code that runs the tool.

Components used in this guide

Each one runs live on its page, with its source, props and every state it draws.