# 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 CrewAI AG-UI package

    ```bash
    pip install ag-ui-crewai litellm
    ```

  </Step>
  <Step>
    ### Give `useHumanInTheLoop` tools to the model

    A Flow makes its own model call, so it must pass the tools itself:

    - Type the Flow on `CopilotKitState`. A tool registered with
      `useHumanInTheLoop` arrives in `self.state.copilotkit.actions`.
    - Pass the actions as `tools`, inside `copilotkit_stream`, so the tool call
      reaches the browser as it streams.
    - The run ends when the model calls the tool. After the user answers,
      CopilotKit runs the Flow again with the answer as the last message, with
      `role: "tool"`. Read it in the `@start()` step to decide what happens
      next.

    ```python title="agent.py"
    from typing import Any, cast

    from crewai.flow.flow import Flow, listen, start
    from litellm import acompletion

    from ag_ui_crewai import CopilotKitState, copilotkit_stream


    class AgentState(CopilotKitState):
        pass


    class SampleAgentFlow(Flow[AgentState]):
        @start()
        async def check_for_user_feedback(self):
            if not self.state.messages:
                return

            last_message = cast(Any, self.state.messages[-1])

            # The result of the useHumanInTheLoop tool (SEND or CANCEL)
            if last_message["role"] == "tool":
                if last_message.get("content") == "SEND":
                    self.state.messages.append({
                        "role": "assistant",
                        "content": "✅ Great! Sending your essay via email.",
                    })
                    return

                if last_message.get("content") == "CANCEL":
                    self.state.messages.append({
                        "role": "assistant",
                        "content": "❌ Okay, we can improve the draft. What would you like to change?",
                    })
                    return

        @listen(check_for_user_feedback)
        async def chat(self):
            system_message = {
                "role": "system",
                "content": (
                    "You write essays. Use your tools to write an essay; "
                    "don't just write it in plain text."
                ),
            }

            response = await copilotkit_stream(
                await acompletion(
                    reasoning_effort="none",
                    allowed_openai_params=["reasoning_effort"],
                    model="openai/gpt-6-luna",
                    messages=[system_message, *self.state.messages],
                    tools=self.state.copilotkit.actions,
                    stream=True,
                )
            )

            self.state.messages.append(response.choices[0].message)
    ```

  </Step>
  <Step>
    ### Pause the Flow for `useInterrupt`

    To pause at a fixed step in your code instead, decorate the step with
    CrewAI's `@human_feedback` and the AG-UI feedback provider. The step's
    return value is the interrupt payload. The listening step receives the
    user's answer as a `HumanFeedbackResult`.

    ```python title="src/agents/interrupt_flow.py"
    import json
    from typing import Any

    from crewai.flow import Flow, HumanFeedbackResult, human_feedback, listen, start

    from ag_ui_crewai import CopilotKitState, agui_feedback_provider


    class InterruptFlow(Flow[CopilotKitState]):
        @start()
        @human_feedback(
            message="Choose a meeting time or cancel the request.",
            llm=None,
            provider=agui_feedback_provider,
        )
        async def request_schedule(self) -> dict[str, Any]:
            # ... call the model, then return what the picker needs:
            return {"topic": topic, "attendee": attendee, "slots": slots}

        @listen("request_schedule")
        async def confirm_schedule(self, result: HumanFeedbackResult) -> None:
            feedback_text = result.feedback or ""
            # A cancelled interrupt resumes with an empty feedback string.
            cancelled = not feedback_text.strip()
            feedback = {} if cancelled else json.loads(feedback_text)
    ```

    Register the endpoint so it emits standard AG-UI interrupts:

    ```python title="src/agent_server.py"
    add_crewai_flow_fastapi_endpoint(
        app,
        interrupt_flow,
        "/interrupt",
        emit_interrupt_outcome=True,
        enable_legacy_on_interrupt_event=False,
    )
    ```

    For a Conversational Flow, pass these
    two flags in addition to `conversational=True`. On the frontend, read the
    payload from `interrupt.metadata.crewai.output`. See
    `src/agents/interrupt_flow.py` for the full Flow.

  </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_flow.py"
class InterruptState(CopilotKitState):
    pending_tool_call_id: str | None = None
    meeting: dict[str, Any] = Field(default_factory=dict)


class InterruptFlow(Flow[InterruptState]):
    """Pause after schedule_meeting and continue from a spec resume entry."""

    @start()
    @human_feedback(
        message="Choose a meeting time or cancel the request.",
        llm=None,
        provider=agui_feedback_provider,
    )
    async def request_schedule(self) -> dict[str, Any]:
        response = await copilotkit_stream(
            await acompletion(
                allowed_openai_params=["reasoning_effort"],
                reasoning_effort="none",
                model="openai/gpt-6-luna",
                messages=[
                    {"role": "system", "content": SYSTEM_PROMPT},
                    *self.state.messages,
                ],
                tools=[SCHEDULE_MEETING_TOOL],
                tool_choice={
                    "type": "function",
                    "function": {"name": "schedule_meeting"},
                },
                parallel_tool_calls=False,
                stream=True,
            )
        )
        message = response.choices[0].message
        self.state.messages.append(message)
        tool_calls = message.get("tool_calls") or []
        schedule_call = next(
            (
                call
                for call in tool_calls
                if call.get("function", {}).get("name") == "schedule_meeting"
            ),
            None,
        )
        if schedule_call is None:
            return {
                "topic": "Meeting",
                "attendee": None,
                "slots": candidate_slots(),
            }

        try:
            arguments = json.loads(
                schedule_call.get("function", {}).get("arguments") or "{}"
            )
        except (TypeError, json.JSONDecodeError):
            arguments = {}
        self.state.pending_tool_call_id = schedule_call.get("id")
        slots = arguments.get("slots")
        return {
            "topic": arguments.get("topic") or "Meeting",
            "attendee": arguments.get("attendee"),
            "slots": slots if isinstance(slots, list) and slots else candidate_slots(),
        }

    @listen("request_schedule")
    async def confirm_schedule(self, result: HumanFeedbackResult) -> None:
        feedback_text = result.feedback or ""
        try:
            feedback = json.loads(feedback_text or "{}")
        except (TypeError, json.JSONDecodeError):
            feedback = {}
        if not isinstance(feedback, dict):
            feedback = {}
        output = result.output if isinstance(result.output, dict) else {}
        # The AG-UI CrewAI provider resumes a cancelled protocol interrupt
        # with an empty feedback string. Submitted choices are JSON objects,
        # so an empty payload is the package's authoritative cancel signal.
        cancelled = not feedback_text.strip() or bool(feedback.get("cancelled"))
        self.state.meeting = {
            "topic": output.get("topic") or "Meeting",
            "attendee": output.get("attendee"),
            "time": None if cancelled else feedback.get("chosen_time"),
            "label": None if cancelled else feedback.get("chosen_label"),
            "cancelled": cancelled,
        }

        if self.state.pending_tool_call_id:
            result_content = json.dumps(self.state.meeting)
            self.state.messages.append(
                {
                    "role": "tool",
                    "tool_call_id": self.state.pending_tool_call_id,
                    "content": result_content,
                }
            )
            await copilotkit_emit_tool_result(
                self.state.pending_tool_call_id, result_content
            )
        response = await copilotkit_stream(
            await acompletion(
                allowed_openai_params=["reasoning_effort"],
                reasoning_effort="none",
                model="openai/gpt-6-luna",
                messages=[
                    {
                        "role": "system",
                        "content": (
                            f"{SYSTEM_PROMPT}\nScheduling outcome: "
                            f"{json.dumps(self.state.meeting)}"
                        ),
                    },
                    *self.state.messages,
                ],
                tools=[SCHEDULE_MEETING_TOOL],
                parallel_tool_calls=False,
                stream=True,
            )
        )
        self.state.messages.append(response.choices[0].message)
```

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

type SchedulingPayload = {
  topic?: string;
  attendee?: string;
  slots?: TimeSlot[];
};

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({
    agentId: "gen-ui-interrupt",
    renderInChat: true,
    render: ({ event, interrupt, resolve }) => {
      const metadata = interrupt?.metadata as
        | { crewai?: { output?: SchedulingPayload } }
        | undefined;
      const raw = event.value ?? {};
      const fallback = (typeof raw === "string" ? JSON.parse(raw) : raw) as
        | SchedulingPayload
        | { metadata?: { crewai?: { output?: SchedulingPayload } } };
      const payload: SchedulingPayload =
        metadata?.crewai?.output ??
        ("metadata" in fallback
          ? fallback.metadata?.crewai?.output
          : (fallback as SchedulingPayload)) ??
        {};
      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) => setTimeout(() => resolve(result), 500)}
        />
      );
    },
  });

  return (
    <CopilotChat agentId="gen-ui-interrupt" className="h-full rounded-2xl" />
  );
}
```

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.
