# 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 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>

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.
