Headless Interrupts
Answer agent interrupts from any React Native view, outside the chat.
What is this?
Sometimes the agent's question belongs outside the chat: on a dashboard, in a bottom sheet, or in a native alert. A headless interrupt lets any view show the question and resume the run with the answer. No chat needs to be mounted.
On React Native this is also how a custom chat shows interrupts. The root CopilotChat, CopilotPopup, and CopilotSidebar don't draw them, so your own UI places them.
Set renderInChat: false on useInterrupt, and the hook returns the interrupt element instead of handing it to the chat. Render that element wherever you like. resolve(...) and cancel(...) resume the run. The hook handles both the standard AG-UI interrupt and the on_interrupt custom event that the LangGraph adapter sends by default.
When should I use this?
- Non-chat screens: dashboards, settings, forms, or anywhere you want the agent's question without the transcript.
- Your own chat: the question appears as a row in your
FlatList, or as its footer. - Testing: a fixed button grid is easier to drive from Detox or Maestro than a picker that appears after a model call.
- Custom flow control: you need to know exactly when the interrupt arrived (for example, to disable other controls) and when it was answered.
If you just want a picker in the rendered chat, use useInterrupt with the default renderInChat: true. For pauses that the model decides on, use useHumanInTheLoop.
Use useInterrupt without the chat
Install the CopilotKit LangGraph SDK
npm install @copilotkit/sdk-jsWire CopilotKit state + tools into your graph
Programmatic control (copilotkit.runAgent, agent.subscribe,
agent.addMessage) drives runs through the same agent your chat UI
uses, so the backend wiring is the same CopilotKitStateAnnotation
setup.
import type { RunnableConfig } from "@langchain/core/runnables";
import { SystemMessage } from "@langchain/core/messages";
import { MemorySaver, START, StateGraph } from "@langchain/langgraph";
import { ChatOpenAI } from "@langchain/openai";
import {
convertActionsToDynamicStructuredTools,
CopilotKitStateAnnotation,
} from "@copilotkit/sdk-js/langgraph";
// CopilotKit forwards frontend tools to the agent via
// `state.copilotkit.actions`. `CopilotKitStateAnnotation` adds that
// channel to your graph's state; `convertActionsToDynamicStructuredTools`
// turns the forwarded action schemas into LangChain tools you can bind
// at model-invocation time.
const AgentStateAnnotation = CopilotKitStateAnnotation;
export type AgentState = typeof AgentStateAnnotation.State;
const SYSTEM_PROMPT = "You are a helpful, concise assistant.";
async function runChatNode(
state: AgentState,
config: RunnableConfig,
model: ChatOpenAI,
) {
const modelWithTools = model.bindTools!([
...convertActionsToDynamicStructuredTools(state.copilotkit?.actions ?? []),
]);
const response = await modelWithTools.invoke(
[new SystemMessage({ content: SYSTEM_PROMPT }), ...state.messages],
config,
);
return { messages: response };
}
async function chatNode(state: AgentState, config: RunnableConfig) {
return runChatNode(
state,
config,
new ChatOpenAI({
modelKwargs: { reasoning_effort: "none" },
temperature: 0,
model: "gpt-6-luna",
}),
);
}
function compileGraph(node: typeof chatNode) {
return new StateGraph(AgentStateAnnotation)
.addNode("chat_node", node)
.addEdge(START, "chat_node")
.addEdge("chat_node", "__end__")
.compile({ checkpointer: new MemorySaver() });
}
export const graph = compileGraph(chatNode);This panel starts the run itself, then shows the slot buttons while the agent waits:
import { Button, Text, View } from "react-native";
import {
useAgent,
useCopilotKit,
useInterrupt,
} from "@copilotkit/react-native/headless";
const SLOTS = [
{ iso: "2026-11-17T15:00:00Z", label: "Tue 3 PM" },
{ iso: "2026-11-18T10:00:00Z", label: "Wed 10 AM" },
];
export function HeadlessInterruptPanel() {
const { copilotkit } = useCopilotKit();
const { agent } = useAgent({ agentId: "interrupt-headless" });
const kickOff = (prompt: string) => {
agent.addMessage({ id: `user-${Date.now()}`, role: "user", content: prompt });
void copilotkit.runAgent({ agent });
};
const interruptElement = useInterrupt({
agentId: "interrupt-headless",
renderInChat: false,
render: ({ interrupt, resolve, cancel }) => (
<View style={{ gap: 8 }}>
<Text>Pick a slot for {interrupt?.message ?? "a call"}:</Text>
{SLOTS.map((slot) => (
<Button
key={slot.iso}
title={slot.label}
onPress={() => resolve({ chosen_time: slot.iso, chosen_label: slot.label })}
/>
))}
<Button title="Cancel" onPress={() => cancel()} />
</View>
),
});
if (interruptElement) {
return interruptElement;
}
return <Button title="Book call" onPress={() => kickOff("Book a call with sales.")} />;
}interrupt is the primary AG-UI Interrupt object ({ id, reason, message?, responseSchema?, expiresAt?, ... }) for a standard interrupt, and null for a custom event. For a custom event, read the payload from event.value instead. resolve(payload) sends the user's answer and resumes the agent. cancel() cancels a standard interrupt and resumes. Both return a Promise.
Tap Book call. When the agent pauses, the slot buttons replace it. Tap a slot. The run resumes, and Book call comes back.
In your own chat, render the element as the ListFooterComponent of your message list. That's where the rendered chat from /components puts it.
Subscribe to the interrupt yourself
useInterrupt is built from two public APIs: agent.subscribe(...) to receive the pause, and copilotkit.runAgent(...) to resume. To build your own version, for test fixtures or custom logic, see Resolving a LangGraph interrupt from a button. It shows a complete useHeadlessInterrupt hook for the on_interrupt custom event.
How is this guide?