# Governed Action Approval UI

> Gate side-effecting agent actions with an approval UI before they execute.

## What is this? [#what-is-this]

Some agent actions are safe to run immediately, while others should be
blocked or paused for user approval before they create side effects. A
governed action approval UI gives the user a clear checkpoint:

- **What** the agent wants to do
- **Why** it wants to do it
- **Which reference or policy decision** produced the verdict
- **What happens next** if the user approves or rejects it

Use this pattern when the agent proposes an action such as sending an
email, updating a record, creating a ticket, applying a discount, or
calling any write API.

## Action envelope [#action-envelope]

Keep the approval payload small, serializable, and vendor-neutral. The
agent or backend can attach any policy engine result to the action as long
as the UI receives the same basic envelope:

```ts
type GovernedAction = {
  id: string;
  summary: string;
  tool: string;
  reference: string;
  verdict: "allow" | "deny" | "require_approval";
  arguments: Record<string, unknown>;
};
```

The frontend should handle each verdict deterministically:

| Verdict | UI behavior |
| --- | --- |
| `allow` | Execute the action without asking again, optionally showing an audit note. |
| `deny` | Do not execute the action. Close the request without asking the user. |
| `require_approval` | Render a user approval card. Execute only if the user approves. |

## Inline approval with `useInterrupt` [#inline-approval-with-useinterrupt]

If your runtime can pause an agent run, model the approval as an interrupt.
The agent proposes the action, the UI renders the checkpoint, and the run
resumes with the user's decision:

```tsx
import { useEffect } from "react";
import { useInterrupt } from "@copilotkit/react-core/v2";

function GovernedActionApproval() {
  useInterrupt({
    render: ({ event, interrupt, resolve, cancel }) => {
      const action = (interrupt?.metadata?.action ??
        parseInterruptValue(event.value)?.action) as GovernedAction | undefined;

      if (!action) {
        return null;
      }

      return (
        <GovernedActionCard
          action={action}
          onApprove={() =>
            resolve({
              approved: true,
              actionId: action.id,
              reference: action.reference,
            })
          }
          onReject={() =>
            resolve({
              approved: false,
              actionId: action.id,
              reference: action.reference,
            })
          }
          onBlock={() => cancel()}
        />
      );
    },
  });

  return null;
}

// A custom-event interrupt can send its value as a JSON string.
function parseInterruptValue(value: unknown): { action?: unknown } | undefined {
  if (typeof value !== "string") return value as { action?: unknown } | undefined;
  try {
    return JSON.parse(value);
  } catch {
    return undefined;
  }
}

function GovernedActionCard({
  action,
  onApprove,
  onReject,
  onBlock,
}: {
  action: GovernedAction;
  onApprove: () => void;
  onReject: () => void;
  onBlock: () => void;
}) {
  useEffect(() => {
    if (action.verdict === "allow") onApprove();
    if (action.verdict === "deny") onBlock();
  }, [action.id, action.verdict]);

  const status =
    action.verdict === "allow"
      ? "Allowed by policy"
      : action.verdict === "deny"
        ? "Blocked by policy"
        : "User approval required";

  return (
    <section className="rounded-lg border p-4 shadow-sm">
      <div className="space-y-1">
        <p className="text-sm font-medium">{status}</p>
        <h3 className="text-base font-semibold">{action.summary}</h3>
        <p className="text-sm text-muted-foreground">Tool: {action.tool}</p>
        <p className="text-sm text-muted-foreground">
          Reference: {action.reference}
        </p>
      </div>

      <pre className="mt-3 overflow-auto rounded bg-muted p-3 text-xs">
        {JSON.stringify(action.arguments, null, 2)}
      </pre>

      {action.verdict === "require_approval" && (
        <div className="mt-4 flex gap-2">
          <button type="button" onClick={onApprove}>
            Approve and run
          </button>
          <button type="button" onClick={onReject}>
            Reject
          </button>
        </div>
      )}
    </section>
  );
}
```

The sample reads the action from either interrupt shape:

- A standard AG-UI interrupt: the agent puts the action in
  `interrupt.metadata.action`.
- A custom `on_interrupt` event: `interrupt` is `null`, and `event.value`
  holds the value from the agent. A LangGraph agent sends this event by
  default, with the value that the graph passed to `interrupt()` as JSON.

On resume, the agent executes only when it receives an approved response for
the same action id and reference. In a LangGraph Python agent, the tool calls
`interrupt()` with the action and checks the resume value:

```python title="agent.py"
import hashlib
import json

from langchain_core.tools import tool
from langgraph.types import interrupt


@tool
def send_email(to: str, subject: str, body: str) -> str:
    """Send an email. The user must approve it first."""
    arguments = {"to": to, "subject": subject, "body": body}
    action = {
        # Derive the id from the arguments: LangGraph runs the tool again on resume.
        "id": hashlib.sha256(json.dumps(arguments, sort_keys=True).encode()).hexdigest()[:16],
        "summary": f"Send an email to {to}",
        "tool": "send_email",
        "reference": "policy:outbound-email",
        "verdict": "require_approval",
        "arguments": arguments,
    }

    response = interrupt({"action": action})

    if (
        isinstance(response, dict)
        and response.get("approved")
        and response.get("actionId") == action["id"]
        and response.get("reference") == action["reference"]
    ):
        deliver_email(to, subject, body)  # your own email client
        return f"Email sent to {to}."

    return "The user did not approve this action. The email was not sent."
```

For other agent frameworks, see [Pausing the Agent for Input](./useInterrupt)
for how each one emits an interrupt.

## Tool-call approval with `useHumanInTheLoop` [#tool-call-approval-with-usehumanintheloop]

For LLM-initiated pauses, register the approval checkpoint as a
human-in-the-loop [frontend tool](../frontend-tools). To compare this pattern
with interrupts, see the [HITL Overview](../human-in-the-loop). The model asks to call `approve_governed_action`,
your UI renders the card, and the tool result tells the agent whether it
may continue:

```tsx
import { ToolCallStatus, useHumanInTheLoop } from "@copilotkit/react-core/v2";
import { z } from "zod";

const governedActionSchema = z.object({
  id: z.string(),
  summary: z.string(),
  tool: z.string(),
  reference: z.string(),
  verdict: z.enum(["allow", "deny", "require_approval"]),
  arguments: z.record(z.unknown()),
});

function GovernedActionTool() {
  useHumanInTheLoop(
    {
      name: "approve_governed_action",
      description:
        "Ask the user to approve a governed side-effect action before it runs.",
      parameters: governedActionSchema,
      render: ({ args, status, respond }) => {
        if (status !== ToolCallStatus.Executing || !respond) {
          return null;
        }

        return (
          <GovernedActionCard
            action={args}
            onApprove={() =>
              respond({
                approved: true,
                actionId: args.id,
                reference: args.reference,
              })
            }
            onReject={() =>
              respond({
                approved: false,
                actionId: args.id,
                reference: args.reference,
              })
            }
            onBlock={() =>
              respond({
                approved: false,
                actionId: args.id,
                reference: args.reference,
              })
            }
          />
        );
      },
    },
    [],
  );

  return null;
}
```

Ask the agent to send an email. The approval card shows the tool, the
reference, and the arguments. Click **Reject**, and the agent replies that it
did not send the email.

## Recommended guardrails [#recommended-guardrails]

- Check policy on the server before presenting the approval, not only in
  the browser.
- Include a stable `action.id` and `reference` so the approval cannot be
  replayed for a different action.
- Show the exact action arguments before the user approves.
- Treat `deny` as terminal for that proposed action; do not execute a
  denied side effect from a later UI callback.
- Log the proposal, verdict, user decision, and execution result so the
  action is auditable.
