useInterrupt
React hook for handling agent interrupt events and resuming execution with user input
Overview
useInterrupt shows your UI when the agent pauses for input. Call resolve(payload) to resume the run. Call cancel() to cancel it. The hook supports the AG-UI standard interrupt flow and the on_interrupt custom-event flow. See Behavior.
For a full walkthrough, see Pausing the Agent for Input. If your agent has no interrupt, use useHumanInTheLoop.
By default, interrupt UI is rendered inside <CopilotChat> automatically. If you set renderInChat: false, the hook returns the element so you can place it manually.
Signature
import { useInterrupt } from "@copilotkit/react-core/v2";
function useInterrupt<
TResult = never,
TRenderInChat extends boolean | undefined = undefined,
>(
config: UseInterruptConfig<any, TResult, TRenderInChat>,
): TRenderInChat extends false
? React.ReactElement | null
: TRenderInChat extends true | undefined
? void
: React.ReactElement | null | void;Parameters
Prop
Type
Return Value
Prop
Type
Usage
In-chat interrupt UI (default)
This sample reads a custom-event interrupt whose value holds a question field. For a standard interrupt, read interrupt.message instead, as in the AG-UI standard sample below.
function ApprovalInterrupt() {
useInterrupt({
render: ({ event, resolve }) => {
const value =
typeof event.value === "string" ? JSON.parse(event.value) : event.value;
return (
<div className="p-3 border rounded">
<p>{value.question}</p>
<div className="mt-2 flex gap-2">
<button onClick={() => resolve({ approved: true })}>Approve</button>
<button onClick={() => resolve({ approved: false })}>Reject</button>
</div>
</div>
);
},
});
return null;
}Manual placement with async preprocessing
function SidePanelInterrupt() {
const element = useInterrupt({
renderInChat: false,
enabled: (event) => event.value.startsWith("approval:"),
handler: async ({ event }) => ({ label: event.value.toUpperCase() }),
render: ({ event, result, resolve }) => (
<aside className="rounded border p-3">
<div className="font-medium">{result?.label ?? ""}</div>
<div className="mt-2">{event.value}</div>
<button className="mt-2" onClick={() => resolve({ accepted: true })}>
Continue
</button>
</aside>
),
});
return <>{element}</>;
}AG-UI standard interrupt (approve / cancel)
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;
}Behavior
- Standard interrupts are detected from
RUN_FINISHED(outcome.type === "interrupt", carrying aninterruptsarray); custom-event interrupts fromon_interruptcustom events. For standard interrupts,renderandhandlerreceiveinterrupt(the primary one) andinterrupts(the full open set). Standard takes precedence if both appear in the same run. resolve/cancelaccumulate one response per open interrupt; the resume run starts once every open interrupt is addressed. Standard resumes use a freshrunIdon the same thread and identify the pending interrupts throughresume[].interruptId.- Expired interrupts (past
expiresAt) are not resumed. The hook logs an error and clears pending state. - Interrupt UI is surfaced when the run finalizes.
- Starting a new run clears pending interrupt state.
render.resultis inferred fromhandlerreturn type and is alwaysTResult | null.- If
handlerthrows or rejects,resultis set tonull.
How is this guide?