# useInterrupt

> Vue 3 composable for handling agent interrupt events and resuming execution with user input

## Overview [#overview]

`useInterrupt` is a Vue 3 composable for handling agent interrupts. It supports both the AG-UI standard interrupt flow and the `on_interrupt` custom-event flow, then exposes the active interrupt as reactive state plus `resolve` and `cancel` methods for resuming execution.

By default, the composable publishes its state into [`CopilotChat`](/reference/vue/components/CopilotChat) so you can render the interrupt through the chat's `#interrupt` slot. Set `renderInChat: false` if you want to place the UI yourself.

For an `on_interrupt` custom event, `event.value` is the event value, typed by the `TValue` type parameter, which defaults to `unknown`. For a standard AG-UI interrupt, `event.value` is the first `Interrupt` object (`{ id, reason, message?, metadata? }`), the same object as `interrupt`. Read the agent's data from `interrupt.message` or `interrupt.metadata`. Narrow `event.value` in your `handler` and `enabled` callbacks, or pass an explicit `TValue` when you call the composable.

<Callout type="info">
  `resolve` and `cancel` are the primary methods. `resolveInterrupt` and
  `cancelInterrupt` remain as aliases for back-compat.
</Callout>

## Signature [#signature]

```ts
import { useInterrupt } from "@copilotkit/vue/v2";

function useInterrupt<TValue = unknown, TResult = never>(
  config?: UseInterruptConfig<TValue, TResult>,
): UseInterruptResult<TValue, TResult>;
```

## Parameters [#parameters]

<PropertyReference name="config" type="UseInterruptConfig<TValue, TResult>">
  Optional interrupt configuration.

  <PropertyReference name="handler" type="(props: InterruptHandlerProps<TValue>) => TResult | PromiseLike<TResult>">
    Optional preprocessing callback. It runs when an interrupt becomes pending
    and can return sync or async data that is exposed as `result`. `TResult` is
    inferred from the handler's return type, with promises unwrapped. If the
    handler returns a rejected promise, `result` becomes `null`. A synchronous
    `throw` is not caught and leaves `result` unchanged.

    The callback receives:

    - `event`: the interrupt event (`{ name, value }`). For an `on_interrupt`
      custom event, `value` is the event value, typed as `TValue`. For a
      standard AG-UI interrupt, `value` is the same object as `interrupt`.
    - `interrupt`: the primary interrupt object when the standard AG-UI flow
      is active, otherwise `null`.
    - `interrupts`: the full standard interrupt set, or `[]` for the
      custom-event flow.
    - `resolve(response)`: resumes the agent.
    - `cancel()`: cancels the current interrupt when the standard flow is
      active.
  </PropertyReference>

  <PropertyReference name="enabled" type="(event: InterruptEvent<TValue>) => boolean">
    Optional filter. Return `false` to ignore matching interrupts for this
    composable instance. When it returns `false`, `result` and `slotProps` stay
    `null` and nothing is published to chat.
  </PropertyReference>

  <PropertyReference name="agentId" type="string">
    Optional agent id. Defaults to the agent that [`useAgent`](/reference/vue/hooks/useAgent) resolves for the current chat.
  </PropertyReference>

  <PropertyReference name="renderInChat" type="boolean" default="true">
    Controls whether interrupt state is published into `<CopilotChat>`:
    - `true` (default): publishes `slotProps` into `<CopilotChat>` for
      rendering via the `#interrupt` slot.
    - `false`: skips publishing; render the interrupt yourself from the
      returned refs.
  </PropertyReference>
</PropertyReference>

## Return Value [#return-value]

<PropertyReference name="object" type="UseInterruptResult<TValue, TResult>">
  Reactive interrupt state and resume/cancel helpers.

  <PropertyReference name="interrupt" type="Ref<InterruptEvent<TValue> | null>">
    The latest pending interrupt event (`{ name, value }`), or `null` when
    there is none. Cleared when a new run starts or when resolved.
  </PropertyReference>

  <PropertyReference name="result" type="Ref<TResult | null>">
    The value returned by `handler`, or `null` when there is no handler, the
    handler returned a rejected promise, or `enabled` filtered the interrupt
    out.
  </PropertyReference>

  <PropertyReference name="hasInterrupt" type="ComputedRef<boolean>">
    `true` when an interrupt is pending and passes the optional `enabled`
    filter, otherwise `false`.
  </PropertyReference>

  <PropertyReference name="resolve" type="InterruptResolveFn">
    Primary resume method.

    - Custom-event flow: resumes with `command.resume = payload` and forwards the
      originating interrupt event.
    - Standard flow: records the response for the addressed interrupt. When
      multiple interrupts are open, responses accumulate and the agent resumes
      only after all are addressed. If you omit `interruptId` while more than
      one interrupt is open, the hook warns and defaults to the first one.
    - Expired standard interrupts are not resumed.
  </PropertyReference>

  <PropertyReference name="resolveInterrupt" type="InterruptResolveFn">
    Back-compat alias of `resolve`.
  </PropertyReference>

  <PropertyReference name="cancel" type="InterruptCancelFn">
    Cancels the pending interrupt.

    - Standard flow: records a cancellation for the addressed interrupt.
      Multiple open interrupts accumulate responses until all are addressed.
      If you omit `interruptId` while more than one interrupt is open, the hook
      warns and defaults to the first one.
    - Custom-event flow: dismisses the interrupt without resuming.
  </PropertyReference>

  <PropertyReference name="cancelInterrupt" type="InterruptCancelFn">
    Back-compat alias of `cancel`.
  </PropertyReference>

  <PropertyReference name="slotProps" type="ComputedRef<InterruptRenderProps<TValue, TResult | null> | null>">
    The props published to the `<CopilotChat>` `#interrupt` slot, or `null`
    when there is no active interrupt. Shape: `{ event, interrupt, interrupts,
    result, resolve, cancel }`. The typed `#interrupt` slot declares only
    `event`, `result`, and `resolve`, so read the others from `slotProps`.
  </PropertyReference>
</PropertyReference>

## Usage [#usage]

### In-chat interrupt UI [#in-chat-interrupt-ui]

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

interface Approval {
  question: string;
}

useInterrupt<Approval>();
</script>

<template>
  <CopilotChat>
    <template #interrupt="{ event, resolve }">
      <div class="rounded border p-3">
        <p>{{ (event.value as Approval).question }}</p>
        <div class="mt-2 flex gap-2">
          <button @click="resolve({ approved: true })">Approve</button>
          <button @click="resolve({ approved: false })">Reject</button>
        </div>
      </div>
    </template>
  </CopilotChat>
</template>
```

### Manual placement with async preprocessing [#manual-placement-with-async-preprocessing]

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

const { interrupt, result, hasInterrupt, resolve } = useInterrupt<
  string,
  { label: string }
>({
  renderInChat: false,
  enabled: (event) =>
    typeof event.value === "string" && event.value.startsWith("approval:"),
  handler: async ({ event }) => ({ label: event.value.toUpperCase() }),
});
</script>

<template>
  <aside v-if="hasInterrupt" class="rounded border p-3">
    <div class="font-medium">{{ result?.label ?? "" }}</div>
    <div class="mt-2">{{ interrupt?.value }}</div>
    <button class="mt-2" @click="resolve({ accepted: true })">Continue</button>
  </aside>
</template>
```

### Reading reactive state in script [#reading-reactive-state-in-script]

```ts
import { useInterrupt } from "@copilotkit/vue/v2";

const { interrupt, hasInterrupt, result, cancel, resolve } = useInterrupt({
  handler: ({ event }) => ({ label: String(event.value) }),
});

// `interrupt` and `result` are reactive refs; `hasInterrupt` is a computed.
// Call `resolve(response)` or `cancel()` to address the interrupt.
```

## Behavior [#behavior]

- Interrupts are collected from AG-UI standard interrupt events and from `on_interrupt` custom events.
- Standard interrupts win if both flows appear for the same run.
- The pending interrupt is surfaced when the run finalizes.
- Starting a new run clears pending interrupt state, and a failed run discards the in-flight interrupt.
- When multiple standard interrupts are open, `resolve(payload, interruptId)` and `cancel(interruptId)` accumulate responses until every interrupt is addressed, then resume once.
- Omitting `interruptId` while multiple standard interrupts are open defaults to the first interrupt and logs a warning.
- Expired standard interrupts are not resumed.
- `result` is inferred from the `handler` return type and is always `TResult | null`.
- When `enabled` returns `false`, the interrupt is ignored: `result` and `slotProps` stay `null` and nothing is published to chat.
- With `renderInChat` omitted or `true`, `slotProps` is published into `<CopilotChat>` for the `#interrupt` slot. With `renderInChat: false`, no chat publishing occurs and you render from the returned refs.
- `cancel()` on custom-event interrupts just dismisses without resuming.
