# Headless Interrupts

> Resolve agent interrupts from any UI, without a chat interrupt slot.

## What is this? [#what-is-this]

Some approvals belong outside the chat, such as a dashboard button, a modal, or a test fixture. This page shows how to render the pending request anywhere in your Vue tree. The UI can be a button grid, a form, a modal, or a keyboard shortcut.

Set `renderInChat: false` on `useInterrupt` and render the pending interrupt anywhere. No chat needs to be mounted. On a native interrupt runtime, the backend pauses the run and sends the interrupt to the client. The Vue composable exposes it through `slotProps`, then `resolve(...)` or `cancel(...)` resumes the run using the AG-UI standard flow. The composable also supports custom `on_interrupt` events, which the LangGraph adapter sends by default. The differences between the two flows are below.

## When should I use this? [#when-should-i-use-this]

- **Testing / Playwright fixtures**: a deterministic, chat-less button grid is easier to drive than a picker that appears after an LLM call.
- **Non-chat UIs**: dashboards, side panels, inspector surfaces, or any place where you want the agent's interrupt without the transcript.
- **Custom flow control**: when you need to know exactly when the interrupt arrived and when it was resolved.
- **Research / debugging**: when you want to observe raw interrupt state without the chat abstraction.

If you just want a picker in chat, use [`useInterrupt`](./useInterrupt) with the default `renderInChat: true` and the `#interrupt` slot.

## The primitives [#the-primitives]

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

    <Tabs className="p-0 m-0" groupId="python-pm" items={['uv', 'poetry', 'pip', 'conda']} default="uv">
    <Tab value="uv">
    ```bash
    uv add copilotkit
    ```
    </Tab>
    <Tab value="poetry">
    ```bash
    poetry add copilotkit
    ```
    </Tab>

    <Tab value="pip">

    ```bash
    pip install copilotkit --extra-index-url https://copilotkit.gateway.scarf.sh/simple/
    ```
    </Tab>

    <Tab value="conda">
    ```bash
    conda install copilotkit -c copilotkit-channel
    ```
    </Tab>

</Tabs>

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

~~~~python title="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.

  </Step>
</Steps>

The simplest headless pattern uses `useInterrupt({ renderInChat: false })`. Instead of publishing the state into `<CopilotChat>`, the composable returns reactive refs that you place anywhere:

```vue title="src/components/ApprovalPanel.vue"
<script setup lang="ts">
import { useInterrupt } from "@copilotkit/vue/v2";

const { slotProps } = useInterrupt({
  agentId: "interrupt-headless",
  renderInChat: false,
});
</script>

<template>
  <section v-if="slotProps" class="approval-panel">
    <p>{{ slotProps.interrupt?.message ?? "Approve this action?" }}</p>
    <button @click="slotProps.resolve({ approved: true })">Approve</button>
    <button @click="slotProps.cancel()">Cancel</button>
  </section>
</template>
```

`interrupt` carries the primary AG-UI `Interrupt` object (`{ id, reason, message?, responseSchema?, expiresAt?, ... }`). `resolve(payload)` submits the user's response; `cancel()` submits a cancelled response. Both return a `Promise<RunAgentResult | void>`. The result is `void` while waiting on further interrupts when more than one is open.

Internally, `useInterrupt` composes two public APIs:

1. **`agent.subscribe({ onCustomEvent, onRunStartedEvent, onRunFinishedEvent, onRunFinalized, onRunFailed })`**: standard interrupts arrive on `onRunFinishedEvent` with `{ outcome: "interrupt", interrupts: [...] }`. Custom-event interrupts (the LangGraph adapter default) arrive as a custom event named `on_interrupt`.
2. **`copilotkit.runAgent({ agent, resume })`** for the standard transport, or **`copilotkit.runAgent({ agent, forwardedProps: { command: { resume, interruptEvent } } })`** for the custom-event transport. These are the same calls that `resolve()` and `cancel()` make.

The composable is careful to:

- Surface a standard interrupt only after the run finalizes, so the picker does not flash while the run is still streaming.
- Clear stale pending state when a new run starts.
- Drop staged state after a failed run so a transport error does not leave the UI stuck.

## Driving it from plain UI [#driving-it-from-plain-ui]

Combine `useAgent`, `useCopilotKit`, and the headless interrupt state when the same page needs to start the run and resolve its pause:

```vue title="src/components/HeadlessInterruptPanel.vue"
<script setup lang="ts">
import { toRaw } from "vue";
import { useAgent, useCopilotKit, useInterrupt } from "@copilotkit/vue/v2";

const { agent } = useAgent({ agentId: "interrupt-headless" });
const { copilotkit } = useCopilotKit();
const { slotProps } = useInterrupt({
  agentId: "interrupt-headless",
  renderInChat: false,
});

async function kickOff(prompt: string) {
  const current = agent.value;
  if (!current || current.isRunning) return;

  current.addMessage({
    id: crypto.randomUUID(),
    role: "user",
    content: prompt,
  });
  await copilotkit.value.runAgent({ agent: toRaw(current) });
}
</script>

<template>
  <section v-if="slotProps">
    <p>{{ slotProps.interrupt?.message ?? "Pick an option" }}</p>
    <button @click="slotProps.resolve({ choice: 'approve' })">Approve</button>
    <button @click="slotProps.cancel()">Cancel</button>
  </section>
  <button v-else @click="kickOff('Prepare the governed action.')">
    Start
  </button>
</template>
```

If you need custom accumulation logic or a deterministic test fixture, subscribe to the agent directly. For ordinary product UI, the public `useInterrupt` composable already handles standard and custom-event transports, multiple interrupts, cleanup, and resume submission.

## Provider setup [#provider-setup-1]

The component calling these composables must be below `CopilotKitProvider`:

```vue title="src/App.vue"
<script setup lang="ts">
import { CopilotKitProvider } from "@copilotkit/vue/v2";
import HeadlessInterruptPanel from "./components/HeadlessInterruptPanel.vue";
</script>

<template>
  <CopilotKitProvider runtime-url="/api/copilotkit">
    <HeadlessInterruptPanel />
  </CopilotKitProvider>
</template>
```

Click **Start**. The agent pauses, and the panel shows **Approve** and **Cancel**. Click **Approve**, and the run continues.
