Governed Action Approval UI
Gate side-effecting agent actions with an approval UI before they execute.
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
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:
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
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:
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_interruptevent:interruptisnull, andevent.valueholds the value from the agent. A LangGraph agent sends this event by default, with the value that the graph passed tointerrupt()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:
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 for how each one emits an interrupt.
Tool-call approval with useHumanInTheLoop
For LLM-initiated pauses, register the approval checkpoint as a
human-in-the-loop frontend tool. To compare this pattern
with interrupts, see the HITL Overview. The model asks to call approve_governed_action,
your UI renders the card, and the tool result tells the agent whether it
may continue:
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
- Check policy on the server before presenting the approval, not only in the browser.
- Include a stable
action.idandreferenceso the approval cannot be replayed for a different action. - Show the exact action arguments before the user approves.
- Treat
denyas 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.
How is this guide?