Pausing the Agent for Input
Pause an agent run mid-tool, hand control to a custom React component, and resume with the user's answer.
What is this?
Some agent steps need a person's answer before the run can continue, such as
approving a payment or picking a meeting time. useInterrupt pauses the run,
shows your React component, and resumes the run with the answer. How the pause
works depends on your agent framework.
Some agent frameworks cannot pause a run mid-tool the way LangGraph's
interrupt() does, so this demo registers schedule_meeting with
useHumanInTheLoop instead. The agent calls schedule_meeting like
any other tool. The picker renders in the chat, and respond(...) sends
the user's choice back to the agent as the tool result.
The user sees the same flow: the agent pauses, the user answers, and the
agent continues. Only the mechanism is different.
When should I use this?
Reach for useInterrupt when the pause is a checkpoint in your
agent code where the code path must stop and wait for a human,
not an LLM-initiated tool call. Typical cases:
- A sensitive action (payments, irreversible writes) must be approved
- A required piece of state isn't known and can only be collected from the user
- The agent explicitly reaches an approval node in a longer workflow
- You want the server-side contract to be an interrupt that resumes with a payload
For LLM-initiated pauses where the model decides on the fly to ask
the user, prefer useHumanInTheLoop.
The frontend: useHumanInTheLoop renders the picker
useHumanInTheLoop registers schedule_meeting as a frontend tool and
renders the picker inline in the chat. When the user picks a slot or
cancels, respond(...) sends the choice back as the tool result. This is
the frontend-tool equivalent of
useInterrupt's event / resolve pair:
import {
CopilotKit,
CopilotChat,
useInterrupt,
} from "@copilotkit/react-core/v2";
import type { TimeSlot } from "./_components/time-picker-card";
import { TimePickerCard } from "./_components/time-picker-card";
import { generateFallbackSlots } from "../_shared/interrupt-fallback-slots";
import { useGenUiInterruptSuggestions } from "./suggestions";
export default function GenUiInterruptDemo() {
return (
<CopilotKit runtimeUrl="/api/copilotkit" agent="gen-ui-interrupt">
<div className="flex justify-center items-center h-screen w-full">
<div className="h-full w-full max-w-4xl">
<Chat />
</div>
</div>
</CopilotKit>
);
}
function Chat() {
useGenUiInterruptSuggestions();
// The Claude backend surfaces a structured scheduling payload —
// `{ topic, attendee, slots }` — which we render inline in the chat as a
// message bubble. Calling `resolve(...)` sends the user's selection back
// through the AG-UI resume path.
useInterrupt({
agentId: "gen-ui-interrupt",
renderInChat: true,
render: ({ event, resolve }) => {
// The AG-UI adapter JSON-stringifies interrupt values, so parse
// when needed to extract the structured payload.
const raw = event.value ?? {};
const payload = (typeof raw === "string" ? JSON.parse(raw) : raw) as {
topic?: string;
attendee?: string;
slots?: TimeSlot[];
};
const slots =
payload.slots && payload.slots.length > 0
? payload.slots
: generateFallbackSlots();
return (
<TimePickerCard
topic={payload.topic ?? "a call"}
attendee={payload.attendee}
slots={slots}
onSubmit={(result) => {
// Defer resolve so React commits the picked/cancelled state
// before useInterrupt clears the interrupt element. A single
// requestAnimationFrame is not reliable — rAF fires before
// React's commit in some scheduling scenarios. Using a short
// setTimeout ensures the commit lands first and the user sees
// the "Booked"/"Cancelled" badge before the card unmounts.
setTimeout(() => resolve(result), 500);
}}
/>
);
},
});The backend: agent instructed to call the frontend tool
The agent has no local schedule_meeting implementation. The tool is
registered entirely on the frontend. The backend's only job is to
instruct the model to call schedule_meeting whenever the user wants
to book a meeting. AG-UI routes the tool call to the client, where
the Promise-returning handler takes over:
SYSTEM_PROMPT = dedent("""
You are a scheduling assistant. Whenever the user asks you to book a call
or schedule a meeting, you MUST call the `schedule_meeting` tool. Pass a
short `topic` describing the purpose of the meeting and, if known, an
`attendee` describing who the meeting is with.
The `schedule_meeting` tool is implemented on the client: it surfaces a
time-picker UI to the user and returns the user's selection. After the
tool returns, briefly confirm whether the meeting was scheduled and at
what time, or note that the user cancelled. Do NOT ask for approval
yourself — always call the tool and let the picker handle the decision.
Keep responses short and friendly. After you finish executing tools,
always send a brief final assistant message summarizing what happened so
the message persists.
""").strip()Ask the agent to book a call. The time picker appears in the chat. Pick a slot, and the agent confirms the booked time.
AG-UI standard interrupt flow vs. custom-event flow
This section is a reference for developers who write render code for their
own agent. The useInterrupt reference lists
every option. useInterrupt handles two kinds of interrupt, and your agent
framework decides which kind it sends.
Standard flow (RUN_FINISHED with outcome.type === "interrupt")
When the agent backend conforms to the AG-UI protocol, it signals an interrupt
by emitting a RUN_FINISHED event whose outcome carries the interrupts array:
outcome.type === "interrupt"
outcome.interrupts // Interrupt[]The hook detects this on onRunFinishedEvent and exposes the interrupts on the
render props after onRunFinalized fires. Your render function receives:
interrupt: the primaryInterrupt(interrupts[0]), with shape{ id, reason, message?, toolCallId?, responseSchema?, expiresAt?, metadata? }.interrupts: the full open set (usually one, but multi-interrupt is supported, as described below).resolve(payload?, interruptId?): records{ status: "resolved", payload }for the targeted interrupt (defaults to the primary). The agent run resumes once every open interrupt has a response.cancel(interruptId?): records{ status: "cancelled" }for the targeted interrupt. Same accumulate-then-submit logic applies.
Each resume entry carries the interrupt id, the status, and your payload.
resolve and cancel send no metadata.
Custom-event flow (on_interrupt)
Agents that emit a custom on_interrupt event use this flow. The LangGraph
adapter emits this event by default. The hook detects this on onCustomEvent and sets
interrupt to null and interrupts to []. The payload is in
event.value. Calling resolve(payload) resumes via forwardedProps.command
(the custom-event resume mechanism). cancel() dismisses the interrupt without
resuming. The agent never receives a response.
Priority
If both signals appear on the same run, the standard flow wins.
Approve / Cancel example
function ApprovalInterrupt() {
useInterrupt({
render: ({ interrupt, resolve, cancel }) => (
<div className="p-3 border rounded">
<p>{interrupt?.message ?? "Approve this action?"}</p>
<div className="mt-2 flex gap-2">
<button onClick={() => resolve({ approved: true })}>Approve</button>
<button onClick={() => cancel()}>Cancel</button>
</div>
</div>
),
});
return null;
}resolve({ approved: true }) records a resolved entry and submits the resume
array to the agent. cancel() records a cancelled entry and does the same.
Both return the RunAgentResult once the run restarts.
Multi-interrupt behavior
Some agents issue more than one interrupt in a single run (e.g. two independent
approvals). Each interrupt has its own id. Address them individually:
useInterrupt({
render: ({ interrupts, resolve, cancel }) => (
<ul>
{interrupts.map((i) => (
<li key={i.id}>
{i.message}
<button onClick={() => resolve({ ok: true }, i.id)}>Approve</button>
<button onClick={() => cancel(i.id)}>Cancel</button>
</li>
))}
</ul>
),
});The agent run only resumes once every open interrupt has been addressed.
Calling resolve or cancel with a specific interruptId marks that interrupt
done; the hook auto-submits the accumulated responses when the last one is
addressed. If you omit interruptId, the primary interrupt (interrupts[0])
is targeted.
responseSchema: surface only, no client-side validation
The Interrupt type exposes a responseSchema field (a JSON Schema object)
that the agent can use to describe the expected payload shape. useInterrupt
surfaces this field on interrupt.responseSchema for your UI to read
(e.g. to drive a form), but it does not validate resolve payloads against
it. Validation is the agent's responsibility on resume.
How is this guide?