# Pausing the Agent for Input

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

<!-- interactive demo: gen-ui-interrupt -->

## 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 React component, and resumes the run with the answer. How the pause
works depends on your agent framework.

This framework ships a first-class interrupt primitive that lets running
work suspend itself and hand control to the client: `interrupt()` in
[LangGraph](https://docs.langchain.com/oss/python/langgraph/interrupts),
[interrupts in AWS Strands](https://strandsagents.com/docs/user-guide/concepts/interrupts/),
a tool that returns `suspend()` in Mastra, or a `@human_feedback` step in a
CrewAI Flow.
The run is frozen server-side until the client resolves the interrupt with a
payload. Then the run resumes, and the agent receives that payload as the
answer.

CopilotKit's `useInterrupt` is the frontend half of that contract: it
subscribes to the paused run, renders whatever component you give it,
and calls the agent back with the user's answer.

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

Reach for `useInterrupt` when the pause is a **checkpoint in your
agent code** 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 an interrupt that resumes 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: pause the run in your agent [#the-backend-pause-the-run-in-your-agent]

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

In the tool or step that needs the user's answer, call your framework's
interrupt primitive with the data your UI needs: `interrupt()` in LangGraph,
`suspend()` in Mastra, or a `@human_feedback` step in a CrewAI Flow. The
example agent does this in its `schedule_meeting` tool:

```python title="src/agents/interrupt_agent.py"
from __future__ import annotations

from datetime import datetime, time, timedelta
from typing import Any, List, Optional
from zoneinfo import ZoneInfo

from langchain.agents import create_agent
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
from langgraph.types import interrupt
from copilotkit import CopilotKitMiddleware


SYSTEM_PROMPT = (
    "You are a scheduling assistant. Whenever the user asks you to book a "
    "call / schedule a meeting, you MUST call the `schedule_meeting` tool. "
    "Pass a short `topic` describing the purpose and `attendee` describing "
    "who the meeting is with. After the tool returns, confirm briefly "
    "whether the meeting was scheduled and at what time, or that the user "
    "cancelled."
)

# Demo-only fixed timezone. A real app would use the user's calendar +
# locale (e.g. zoneinfo.ZoneInfo(user.timezone) and Google Calendar /
# Outlook availability); we hardcode Pacific so screenshots are stable.
_DEMO_TZ = ZoneInfo("America/Los_Angeles")


def _candidate_slots() -> List[dict]:
    """Upcoming candidate slots, relative to "now" so the picker never
    shows stale dates."""
    now = datetime.now(_DEMO_TZ)
    tomorrow = (now + timedelta(days=1)).date()
    # Skip a week when the result would collide with `tomorrow` — i.e.
    # today is Mon (0 days away, picker would show two slots both
    # labelled "Monday") or Sun (1 day away, picker would show
    # "Tomorrow" and "Monday" both pointing at the same date).
    days_to_monday = (7 - now.weekday()) % 7
    if days_to_monday <= 1:
        days_to_monday += 7
    next_monday = (now + timedelta(days=days_to_monday)).date()
    candidates = [
        ("Tomorrow 10:00 AM", tomorrow, time(10, 0)),
        ("Tomorrow 2:00 PM", tomorrow, time(14, 0)),
        ("Monday 9:00 AM", next_monday, time(9, 0)),
        ("Monday 3:30 PM", next_monday, time(15, 30)),
    ]
    return [
        {"label": label, "iso": datetime.combine(d, t, _DEMO_TZ).isoformat()}
        for label, d, t in candidates
    ]


@tool
def schedule_meeting(topic: str, attendee: Optional[str] = None) -> str:
    """Ask the user to pick a time slot for a call, via an in-chat picker.

    Args:
        topic: Short human-readable description of the call's purpose.
        attendee: Who the call is with (optional).

    Returns:
        Human-readable result string describing the chosen slot or
        indicating the user cancelled.
    """
    # `interrupt()` pauses the LangGraph run and forwards a structured
    # payload to the client. The frontend v2 `useInterrupt` hook renders
    # the picker inline in the chat, then calls `resolve(...)` with the
    # user's selection — that value comes back here as `response`.
    response: Any = interrupt(
        {
            "topic": topic,
            "attendee": attendee,
            "slots": _candidate_slots(),
        }
    )

    if isinstance(response, dict):
        if response.get("cancelled"):
            return f"User cancelled. Meeting NOT scheduled: {topic}"
        chosen_label = response.get("chosen_label") or response.get("chosen_time")
        if chosen_label:
            return f"Meeting scheduled for {chosen_label}: {topic}"

    return f"User did not pick a time. Meeting NOT scheduled: {topic}"

```

The run stops here until the client resolves the interrupt. The resolve
payload comes back to the agent as the answer: the return value of
`interrupt()` in LangGraph, `resumeData` in Mastra, or the
`HumanFeedbackResult` that the next step of a CrewAI Flow receives. The
example turns that value into a string for the model.

Two things to note:

- The payload (`{"topic": topic, "attendee": attendee}`) is what the
  frontend reads off the interrupt. Keep it a plain, serializable object.
  It's the "pause-time context" the UI needs to render.
- The return-side contract (`{chosen_label, chosen_time}` or
  `{cancelled: true}`) is entirely yours. The client can send anything
  as the resolve payload; the tool is the one that gives it meaning.

## The frontend: `useInterrupt` render prop [#the-frontend-useinterrupt-render-prop]

On the client you register a `useInterrupt` hook per agent. When the
paused run arrives, `render` receives both the raw `event` and the
`interrupt` itself, and `resolve(...)` is how you resume the run. Your agent
framework decides where the payload sits:

- Custom-event interrupt (`on_interrupt`): `event.value`.
- Standard AG-UI interrupt: `interrupt.metadata`, or a JSON string in
  `interrupt.message`.

```typescript title="src/app/demos/gen-ui-interrupt/page.tsx"
import {
  CopilotKit,
  CopilotChat,
  useInterrupt,
} from "@copilotkit/react-core/v2";
import type { TimeSlot } from "./_components/time-picker-card";
import { TimePickerCard } from "./_components/time-picker-card";
import { generateFallbackSlots } from "../_shared/interrupt-fallback-slots";
import { useGenUiInterruptSuggestions } from "./suggestions";

export default function GenUiInterruptDemo() {
  return (
    <CopilotKit runtimeUrl="/api/copilotkit" agent="gen-ui-interrupt">
      <div className="flex justify-center items-center h-screen w-full">
        <div className="h-full w-full max-w-4xl">
          <Chat />
        </div>
      </div>
    </CopilotKit>
  );
}

function Chat() {
  useGenUiInterruptSuggestions();

  // `useInterrupt` is the low-level primitive for handling LangGraph
  // `interrupt(...)` events. The backend's `schedule_meeting` tool surfaces
  // a structured payload — `{ topic, attendee, slots }` — which we render
  // inline in the chat as a message bubble. Calling `resolve(...)` resumes
  // the LangGraph run with the user's selection.
  useInterrupt({
    agentId: "gen-ui-interrupt",
    renderInChat: true,
    render: ({ event, resolve }) => {
      // The AG-UI adapter JSON-stringifies interrupt values, so parse
      // when needed to extract the structured payload.
      const raw = event.value ?? {};
      const payload = (typeof raw === "string" ? JSON.parse(raw) : raw) as {
        topic?: string;
        attendee?: string;
        slots?: TimeSlot[];
      };
      const slots =
        payload.slots && payload.slots.length > 0
          ? payload.slots
          : generateFallbackSlots();
      return (
        <TimePickerCard
          topic={payload.topic ?? "a call"}
          attendee={payload.attendee}
          slots={slots}
          onSubmit={(result) => {
            // Defer resolve so React commits the picked/cancelled state
            // before useInterrupt clears the interrupt element. A single
            // requestAnimationFrame is not reliable — rAF fires before
            // React's commit in some scheduling scenarios. Using a short
            // setTimeout ensures the commit lands first and the user sees
            // the "Booked"/"Cancelled" badge before the card unmounts.
            setTimeout(() => resolve(result), 500);
          }}
        />
      );
    },
  });
```

Whatever you pass to `resolve` is sent back to the agent as the answer to
the matching interrupt, for example the return value of `interrupt(...)` in
LangGraph.

Ask the agent to book a call. The time picker appears in the chat. Pick a
slot, and the agent confirms the booked time.

### Key props [#key-props]

- **`agentId`**: must match a runtime-registered agent. If omitted, the
  hook uses the agent of the surrounding chat configuration, then the
  `agentId` set on `CopilotKitProvider`, then `"default"`. A mismatch
  means the interrupt never fires.
- **`render`**: receives `{ event, interrupt, resolve }`.
- **`renderInChat`**: when `true` (as above), the picker appears inline
  in the chat transcript, between the paused assistant turn and the
  still-pending continuation. To show it outside the chat, see
  [Headless interrupts](./headless).

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

If your agent issues more than one kind of interrupt (e.g. `"ask"` vs
`"approval"`), tag each with a `type` field on the payload and install
one `useInterrupt` per shape, each gated by an `enabled` predicate:

```tsx
// The LangGraph adapter sends `event.value` as a JSON string.
const readValue = (value: unknown) =>
  typeof value === "string" ? JSON.parse(value) : value;

useInterrupt({
  agentId: "gen-ui-interrupt",
  enabled: (event) => readValue(event.value).type === "ask",
  render: ({ event, resolve }) => (
    <AskCard question={readValue(event.value).content} onAnswer={resolve} />
  ),
});

useInterrupt({
  agentId: "gen-ui-interrupt",
  enabled: (event) => readValue(event.value).type === "approval",
  render: ({ event, resolve }) => (
    <ApproveCard content={readValue(event.value).content} onAnswer={resolve} />
  ),
});
```

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

For cases where the interrupt can sometimes be resolved _without_ user
input (e.g. the current user already has permission), pass a `handler`
that runs before `render`. The handler can call `resolve(...)` itself
to resume the agent early. The interrupt card unmounts when the resume
run starts. Or return a value that `render` receives as `result`:

```tsx
useInterrupt({
  agentId: "gen-ui-interrupt",
  handler: async ({ event, resolve }) => {
    const value =
      typeof event.value === "string" ? JSON.parse(event.value) : event.value;
    const dept = await lookupUserDepartment();
    if (value.accessDepartment === dept || dept === "admin") {
      resolve({ code: "AUTH_BY_DEPARTMENT" });
      return; // agent will resume; card unmounts when the run starts
    }
    return { dept };
  },
  render: ({ result, event, resolve }) => (
    <RequestAccessCard
      dept={result?.dept}
      onRequest={() => resolve({ code: "REQUEST_AUTH" })}
      onCancel={() => resolve({ code: "CANCEL" })}
    />
  ),
});
```

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

This section is a reference for developers who write `render` code for their
own agent. The [`useInterrupt` reference](/reference/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:

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

The hook detects this on `onRunFinishedEvent` and exposes the interrupts on the
render props **after** `onRunFinalized` fires. Your `render` function receives:

- **`interrupt`**: the primary `Interrupt` (`interrupts[0]`), with shape
  `{ id, reason, message?, toolCallId?, responseSchema?, expiresAt?, metadata? }`.
- **`interrupts`**: the full open set (usually one, but multi-interrupt is
  supported, as described below).
- **`resolve(payload?, interruptId?)`**: records `{ status: "resolved", payload }`
  for the targeted interrupt (defaults to the primary). The agent run resumes
  once every open interrupt has a response.
- **`cancel(interruptId?)`**: records `{ status: "cancelled" }` for the
  targeted interrupt. Same accumulate-then-submit logic applies.

Each resume entry carries the interrupt `id`, the status, and your payload.
`resolve` and `cancel` send no `metadata`.

### Custom-event flow (`on_interrupt`) [#custom-event-flow-on_interrupt]

Agents that emit a custom `on_interrupt` event use this flow. The LangGraph
adapter emits this event by default. The hook detects this on `onCustomEvent` and sets
`interrupt` to `null` and `interrupts` to `[]`. The payload is in
`event.value`. Calling `resolve(payload)` resumes via `forwardedProps.command`
(the custom-event resume mechanism). `cancel()` dismisses the interrupt without
resuming. The agent never receives a response.

### Priority [#priority]

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

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

```tsx
function ApprovalInterrupt() {
  useInterrupt({
    render: ({ interrupt, resolve, cancel }) => (
      <div className="p-3 border rounded">
        <p>{interrupt?.message ?? "Approve this action?"}</p>
        <div className="mt-2 flex gap-2">
          <button onClick={() => resolve({ approved: true })}>Approve</button>
          <button onClick={() => cancel()}>Cancel</button>
        </div>
      </div>
    ),
  });
  return null;
}
```

`resolve({ approved: true })` records a resolved entry and submits the `resume`
array to the agent. `cancel()` records a cancelled entry and does the same.
Both return the `RunAgentResult` once the run restarts.

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

Some agents issue more than one interrupt in a single run (e.g. two independent
approvals). Each interrupt has its own `id`. Address them individually:

```tsx
useInterrupt({
  render: ({ interrupts, resolve, cancel }) => (
    <ul>
      {interrupts.map((i) => (
        <li key={i.id}>
          {i.message}
          <button onClick={() => resolve({ ok: true }, i.id)}>Approve</button>
          <button onClick={() => cancel(i.id)}>Cancel</button>
        </li>
      ))}
    </ul>
  ),
});
```

The agent run only resumes once **every** open interrupt has been addressed.
Calling `resolve` or `cancel` with a specific `interruptId` marks that interrupt
done; the hook auto-submits the accumulated responses when the last one is
addressed. If you omit `interruptId`, the primary interrupt (`interrupts[0]`)
is targeted.

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

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