# Headless Interrupts

> Answer agent interrupts from any React Native view, outside the chat.

## What is this? [#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? [#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`](/react-native/langgraph-typescript/human-in-the-loop/useInterrupt) with the default `renderInChat: true`. For pauses that the model decides on, use [`useHumanInTheLoop`](/react-native/langgraph-typescript/human-in-the-loop).

## Use `useInterrupt` without the chat [#use-useinterrupt-without-the-chat]

<Steps>
  <Step>
    ### Install the CopilotKit LangGraph SDK

    ```bash
    npm install @copilotkit/sdk-js
    ```

  </Step>
  <Step>
    ### Wire 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.

~~~~typescript title="frontend-tools.ts"
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);
~~~~

  </Step>
</Steps>

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

```tsx title="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({ // [!code highlight:15]
    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 [#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](/react-native/langgraph-typescript/programmatic-control#resolving-a-langgraph-interrupt-from-a-button). It shows a complete `useHeadlessInterrupt` hook for the `on_interrupt` custom event.
