useInterrupt
React hook for handling agent interrupt events and resuming execution with user input
Overview
useInterrupt handles agent interrupts and resumes execution with user input. It supports two interrupt flows:
- AG-UI standard:
RUN_FINISHEDwithoutcome.type === "interrupt", carrying aninterruptsarray. - Custom event: an
on_interruptcustom event.
In your render callback, call resolve(payload) to resume or cancel() to cancel. See render for every prop it receives. For a pause that is a tool call, use useHumanInTheLoop.
Re-exported from @copilotkit/react-core/v2. It is identical to the React (V2) useInterrupt; only the import path differs.
The prebuilt CopilotChat and CopilotModal from @copilotkit/react-native/components draw the in-chat interrupt element after the last message. The headless CopilotChat, CopilotPopup, and CopilotSidebar do not. With those, pass renderInChat: false, and the hook returns the element so you can render it in your own view. The element returned by render is a React Native element.
event.value is typed as any since the interrupt payload shape depends on your agent. Type-narrow it in your callbacks (e.g. handler, enabled, render) as needed.
Signature
import { useInterrupt } from "@copilotkit/react-native";
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
Interrupt UI in your chat view
import { Text, TouchableOpacity, View } from "react-native";
import { useInterrupt } from "@copilotkit/react-native";
function ApprovalInterrupt() {
const element = useInterrupt({
renderInChat: false,
render: ({ event, resolve }) => (
<View style={{ padding: 12, borderWidth: 1, borderRadius: 8 }}>
<Text>{event.value.question}</Text>
<View style={{ marginTop: 8, flexDirection: "row", gap: 8 }}>
<TouchableOpacity onPress={() => resolve({ approved: true })}>
<Text>Approve</Text>
</TouchableOpacity>
<TouchableOpacity onPress={() => resolve({ approved: false })}>
<Text>Reject</Text>
</TouchableOpacity>
</View>
</View>
),
});
return <>{element}</>;
}AG-UI standard interrupt (approve / cancel)
import { Text, TouchableOpacity, View } from "react-native";
import { useInterrupt } from "@copilotkit/react-native";
function ApprovalInterrupt() {
const element = useInterrupt({
renderInChat: false,
render: ({ interrupt, resolve, cancel }) => (
<View style={{ padding: 12, borderWidth: 1, borderRadius: 8 }}>
<Text>{interrupt?.message ?? "Approve this action?"}</Text>
<View style={{ marginTop: 8, flexDirection: "row", gap: 8 }}>
<TouchableOpacity onPress={() => resolve({ approved: true })}>
<Text>Approve</Text>
</TouchableOpacity>
<TouchableOpacity onPress={() => cancel()}>
<Text>Cancel</Text>
</TouchableOpacity>
</View>
</View>
),
});
return <>{element}</>;
}Manual placement with async preprocessing
import { Text, TouchableOpacity, View } from "react-native";
import { useInterrupt } from "@copilotkit/react-native";
function SidePanelInterrupt() {
const element = useInterrupt({
renderInChat: false,
enabled: (event) => event.value.startsWith("approval:"),
handler: async ({ event }) => ({ label: event.value.toUpperCase() }),
render: ({ event, result, resolve }) => (
<View style={{ borderWidth: 1, borderRadius: 8, padding: 12 }}>
<Text style={{ fontWeight: "500" }}>{result?.label ?? ""}</Text>
<Text style={{ marginTop: 8 }}>{event.value}</Text>
<TouchableOpacity style={{ marginTop: 8 }} onPress={() => resolve({ accepted: true })}>
<Text>Continue</Text>
</TouchableOpacity>
</View>
),
});
return <>{element}</>;
}Behavior
- Standard interrupts are detected from
RUN_FINISHED(outcome.type === "interrupt"); custom-event interrupts fromon_interruptevents. resolve/cancelaccumulate one response per open interrupt; the resume run starts once every open interrupt is addressed.- Expired interrupts (past
expiresAt) are not resumed. - Interrupt UI is surfaced when the run finalizes.
- Starting a new run clears pending interrupt state.
event.valueisany; type-narrow in your callbacks as needed. For standard interrupts,event.valueis the primaryInterrupt.render.resultis inferred fromhandlerreturn type and is alwaysTResult | null.- If
handlerthrows or rejects,resultis set tonull.
How is this guide?