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 LangGraph Python SDK

uv add copilotkit

Wire CopilotKit middleware 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 one-line CopilotKitMiddleware setup.

frontend_tools.py
from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
from copilotkit import CopilotKitMiddleware

graph = create_agent(
    model=ChatOpenAI(reasoning_effort="none", model="gpt-6-luna"),
    tools=[],
    middleware=[CopilotKitMiddleware()],
    system_prompt="You are a helpful, concise assistant.",
)

For the headless useInterrupt pattern, also use LangGraph's native interrupt(...) inside a graph node and resume with forwardedProps: { command: { resume, interruptEvent } } from the frontend.

This panel starts the run itself, then shows the slot buttons while the agent waits:

src/HeadlessInterruptPanel.tsx
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?