# Pausing the Agent for Input

> Pause an agent run, hand control to a custom Vue component, and resume with the user's answer.

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

Some agent steps need a person's answer before the run can continue, such as approving a payment or picking a meeting time. `useInterrupt` pauses the run, shows your Vue component, and resumes the run with the answer. How the pause works depends on your agent framework.

LangGraph ships a first-class [`interrupt()`](https://docs.langchain.com/oss/python/langgraph/interrupts) primitive that lets a running node suspend itself and hand control to the client. The run is frozen server-side until the client resolves the interrupt with a payload, at which point the node resumes as if `interrupt()` had returned that payload.

CopilotKit's `useInterrupt` is the frontend half of that contract: it subscribes to the paused run, exposes reactive interrupt state, and resumes the agent with the user's answer.

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

Reach for `useInterrupt` when the pause is a **graph-enforced checkpoint** where the code path _must_ stop and wait for a human, not an LLM-initiated tool call. Typical cases:

- A sensitive action (payments, irreversible writes) must be approved
- A required piece of state isn't known and can only be collected from the user
- The agent explicitly reaches an approval node in a longer workflow
- You want the server-side contract to be `interrupt(...)` and resume with a payload

For LLM-initiated pauses where the model decides on the fly to ask the user, prefer [`useHumanInTheLoop`](../human-in-the-loop).

## The backend: `interrupt()` inside a tool [#the-backend-interrupt-inside-a-tool]

<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

    For `useHumanInTheLoop` tool-based HITL, the tool is defined entirely on
    the frontend and forwarded to the agent. `CopilotKitMiddleware` is what
    forwards it — drop it into your `create_agent` call.

~~~~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 `useInterrupt` graph-paused pattern, you'll also use LangGraph's
    native `interrupt(...)` primitive inside a graph node — no extra
    CopilotKit setup beyond the middleware above.

  </Step>
  <Step>
    ### Using a custom graph instead of `create_agent`

    `CopilotKitMiddleware` only works with `create_agent`. In a graph where you
    define the nodes and edges yourself, inherit your state from
    `CopilotKitState` and bind the forwarded tools from
    `state["copilotkit"]["actions"]` to the model, or it can never call the
    `useHumanInTheLoop` tool:

    ```python title="agent.py"
    from copilotkit import CopilotKitState
    from langchain_core.runnables import RunnableConfig
    from langchain_openai import ChatOpenAI

    class AgentState(CopilotKitState):
        pass

    async def agent_node(state: AgentState, config: RunnableConfig):
        # Access the tools from the copilotkit property
        tools = state.get("copilotkit", {}).get("actions", [])
        model = ChatOpenAI(model="gpt-6-luna", reasoning_effort="none").bind_tools(tools)

        # ...
    ```

  </Step>
</Steps>

The agent can expose a `schedule_meeting` tool that issues an interrupt with the meeting context. The run stops until the client resolves the interrupt. The resolve payload becomes the return value of `interrupt()`. The tool turns that value into a result for the model.

Two things to note:

- The payload, for example `{ "topic": topic, "attendee": attendee }`, is what the Vue frontend receives as `event.value`. The LangGraph adapter sends it as a JSON string, so parse it before you read fields. Keep it a plain, serializable object containing the pause-time context the UI needs.
- The return-side contract, such as `{ chosen_label, chosen_time }` or `{ cancelled: true }`, is entirely yours. The client can send any serializable resolve payload; the tool gives it meaning and must validate it before a side effect.

## The frontend: `useInterrupt` and the chat slot [#the-frontend-useinterrupt-and-the-chat-slot]

Register `useInterrupt` in a descendant component. With the default `renderInChat: true`, the composable publishes the pending interrupt to `CopilotChat`; render it through the `#interrupt` scoped slot and call `resolve(...)` to resume:

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

type MeetingPayload = { topic?: string; attendee?: string };

// The LangGraph adapter sends the interrupt value as a JSON string.
function readValue(value: unknown): MeetingPayload {
  if (typeof value !== "string") return (value ?? {}) as MeetingPayload;
  try {
    return JSON.parse(value) as MeetingPayload;
  } catch {
    return {};
  }
}

useInterrupt({
  agentId: "gen-ui-interrupt",
});
</script>

<template>
  <CopilotChat agent-id="gen-ui-interrupt">
    <template #interrupt="{ event, resolve }">
      <section>
        <p>Pick a time for {{ readValue(event.value).topic ?? "a call" }}</p>
        <button
          @click="resolve({ chosen_label: 'Tomorrow', chosen_time: '2026-09-01T09:00:00Z' })"
        >
          Tomorrow at 09:00
        </button>
        <button @click="resolve({ cancelled: true })">Cancel</button>
      </section>
    </template>
  </CopilotChat>
</template>
```

Whatever you pass to `resolve` is round-tripped back to the agent as the return value of the matching interrupt.

Ask the agent to book a call. The picker appears in the chat. Click **Tomorrow at 09:00**, and the agent confirms the booked time.

### Key props [#key-props]

- **`agentId`**: must match a runtime-registered agent. If omitted, the composable uses the agent of the surrounding chat configuration, then `"default"`. A mismatch means the interrupt never appears.
- **`renderInChat`**: when `true`, `slotProps` are published to the chat's `#interrupt` slot. Set it to `false` when your own component renders the returned refs elsewhere. See [Headless interrupts](/vue/human-in-the-loop/headless).
- **`handler`**: optionally preprocesses the interrupt, can resolve it early, and exposes its return value as `result`.
- **`enabled`**: filters interrupt shapes before they are surfaced.

The Vue `#interrupt` slot receives `{ event, result, resolve }`. For the complete standard-interrupt surface (including `interrupt`, `interrupts`, and `cancel`), use the composable's returned `slotProps` with `renderInChat: false`.

## Multiple interrupts? Add a type and gate with `enabled` [#multiple-interrupts-add-a-type-and-gate-with-enabled]

If your graph issues more than one kind of interrupt, tag each payload with a `type` field and install one `useInterrupt` per shape, each gated by `enabled`:

```ts
// The LangGraph adapter sends the interrupt value as a JSON string.
function readValue(value: unknown): Record<string, unknown> {
  if (typeof value !== "string") return (value ?? {}) as Record<string, unknown>;
  try {
    return JSON.parse(value) as Record<string, unknown>;
  } catch {
    return {};
  }
}

useInterrupt({
  agentId: "gen-ui-interrupt",
  enabled: (event) => readValue(event.value).type === "ask",
});

useInterrupt({
  agentId: "gen-ui-interrupt",
  enabled: (event) => readValue(event.value).type === "approval",
});
```

## Preprocess with `handler` [#preprocess-with-handler]

For cases where the interrupt can sometimes be resolved _without_ user input, pass a `handler` that runs before the UI is rendered. The handler can call `resolve(...)` itself to resume the agent early, or return a value exposed as `result`:

```ts
const { slotProps } = useInterrupt({
  agentId: "gen-ui-interrupt",
  renderInChat: false,
  handler: async ({ event, resolve }) => {
    const department = await lookupUserDepartment();
    // readValue is the helper from the previous sample.
    const required = readValue(event.value).accessDepartment;

    if (required === department || department === "admin") {
      await resolve({ code: "AUTH_BY_DEPARTMENT" });
      return;
    }

    return { department };
  },
});
```

## AG-UI standard interrupt flow vs. legacy [#ag-ui-standard-interrupt-flow-vs-legacy]

This section is a reference for developers who write interrupt UI for their own agent. The [Vue `useInterrupt` reference](/reference/vue/hooks/useInterrupt) lists every option. `useInterrupt` handles two kinds of interrupt, and your agent framework decides which kind it sends.

### Standard flow (`RUN_FINISHED` with `outcome.type === "interrupt"`) [#standard-flow-run_finished-with-outcometype--interrupt]

When the agent backend conforms to the AG-UI protocol, it signals an interrupt by emitting a `RUN_FINISHED` event whose outcome carries the interrupts array:

```text
outcome.type === "interrupt"
outcome.interrupts  // Interrupt[]
```

The composable detects this on `onRunFinishedEvent` and exposes the interrupts after `onRunFinalized` fires. `slotProps.value` contains:

- **`interrupt`**: the primary `Interrupt` (`interrupts[0]`), with shape `{ id, reason, message?, toolCallId?, responseSchema?, expiresAt?, metadata? }`.
- **`interrupts`**: the full open set.
- **`resolve(payload?, interruptId?)`**: records a resolved response for the targeted interrupt. The run resumes once every open interrupt has a response.
- **`cancel(interruptId?)`**: records a cancelled response for the targeted interrupt. The same accumulate-then-submit logic applies.

### Legacy flow (`on_interrupt` custom event) [#legacy-flow-on_interrupt-custom-event]

Agents can emit a custom `on_interrupt` event. The LangGraph adapter does this by default. The composable exposes its payload in `event.value`, with `interrupt` set to `null` and `interrupts` to `[]`. Calling `resolve(payload)` resumes via `forwardedProps.command`. `cancel()` dismisses the interrupt without resuming because the custom-event flow has no cancel response.

### Priority [#priority]

If both signals appear on the same run, the standard flow wins.

### Approve / Cancel example [#approve--cancel-example]

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

const { slotProps } = useInterrupt({ renderInChat: false });
</script>

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

Both methods return the `RunAgentResult` once the run restarts, or `void` while waiting for responses to other open interrupts.

### Multi-interrupt behavior [#multi-interrupt-behavior]

Some agents issue more than one interrupt in a single run. Each interrupt has its own `id`; address them individually:

```vue
<template>
  <ul v-if="slotProps">
    <li v-for="item in slotProps.interrupts" :key="item.id">
      {{ item.message }}
      <button @click="slotProps.resolve({ ok: true }, item.id)">Approve</button>
      <button @click="slotProps.cancel(item.id)">Cancel</button>
    </li>
  </ul>
</template>
```

The agent run resumes only after **every** open interrupt has been addressed. If you omit `interruptId`, the primary interrupt is targeted; Vue warns when several are open.

### `responseSchema`: surface only, no client-side validation [#responseschema-surface-only-no-client-side-validation]

The `Interrupt` type exposes a `responseSchema` JSON Schema that the agent can use to describe the expected payload. `useInterrupt` surfaces it on `interrupt.responseSchema` for your UI to read, but it does **not** validate `resolve` payloads against it. Validation is the agent's responsibility on resume.

## Provider setup [#provider-setup]

The component calling `useInterrupt` must be a descendant of `CopilotKitProvider`:

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

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