Headless Interrupts

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

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?

  • 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 with the default renderInChat: true and the #interrupt slot.

The primitives

Install the CopilotKit LangGraph SDK

npm install @copilotkit/sdk-js

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.

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);

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

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

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

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

The component calling these composables must be below CopilotKitProvider:

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.

How is this guide?