# Pausing the Agent for Input

> Pause an agent run, hand control to a React Native 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 React Native component, and resumes the run with the answer. How the pause works depends on your agent framework.

Your agent framework has a native pause primitive, such as LangGraph's [`interrupt()`](https://docs.langchain.com/oss/python/langgraph/interrupts). A running step suspends itself and hands control to the app. The run stays frozen on the server until the app answers with a payload. Then the step resumes as if `interrupt()` had returned that payload.

CopilotKit's `useInterrupt` is the frontend half of that contract: it receives the paused run, renders your UI, and resumes the agent with the user's answer.

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

Use `useInterrupt` when the pause is a **checkpoint in your agent code**, where the code path _must_ stop and wait for a human. It is not for a tool call the model decides to make. Typical cases:

- A sensitive action (payments, irreversible writes) must be approved
- A required value isn't known and only the user can give it
- The agent reaches an approval step in a longer workflow
- You want the server-side contract to be an interrupt that resumes with a payload

When the model decides on the fly to ask the user, use [`useHumanInTheLoop`](/react-native/langgraph-python/human-in-the-loop) instead.

## 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. This agent does it 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 app 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.

Two things to note:

- The payload (`{ "topic": topic, "attendee": attendee }`) is what the app reads from the interrupt. Keep it a plain, serializable object with the context your UI needs.
- The answer's shape (`{ chosen_label, chosen_time }` or `{ cancelled: true }`) is up to you. The app can send any serializable payload, and the tool gives it meaning. Validate it in the tool before any side effect.

## The frontend: `useInterrupt` in the rendered chat [#the-frontend-useinterrupt-in-the-rendered-chat]

Register `useInterrupt` in a component under `CopilotKitProvider`. When the paused run arrives, `render` receives the `event`, the `interrupt`, and `resolve(...)`, which resumes the run. Your agent framework decides where the payload is:

- Custom-event interrupt (`on_interrupt`): in `event.value`. The LangGraph adapter sends it as a JSON string.
- Standard AG-UI interrupt: in `interrupt.metadata`, or as a JSON string in `interrupt.message`.

```tsx title="src/MeetingChat.tsx"
import { Pressable, Text, View } from "react-native";
import { useInterrupt, type Interrupt } from "@copilotkit/react-native/headless";
import { CopilotChat } from "@copilotkit/react-native/components";

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

// Read the payload from either interrupt shape. JSON strings are parsed.
function readPayload(eventValue: unknown, interrupt: Interrupt | null): MeetingPayload {
  const raw = interrupt ? (interrupt.metadata ?? interrupt.message) : eventValue;
  if (typeof raw !== "string") return (raw ?? {}) as MeetingPayload;
  try {
    return JSON.parse(raw) as MeetingPayload;
  } catch {
    return {};
  }
}

export function MeetingChat() {
  useInterrupt({ // [!code highlight:16]
    agentId: "gen-ui-interrupt",
    render: ({ event, interrupt, resolve }) => (
      <View style={{ padding: 12, borderRadius: 12, backgroundColor: "#f4f4f8", gap: 8 }}>
        <Text style={{ fontWeight: "600" }}>
          Pick a time for {readPayload(event.value, interrupt).topic ?? "a call"}
        </Text>
        <Pressable
          onPress={() => resolve({ chosen_label: "Tomorrow", chosen_time: "2026-11-11T09:00:00Z" })}
        >
          <Text>Tomorrow at 09:00</Text>
        </Pressable>
        <Pressable onPress={() => resolve({ cancelled: true })}>
          <Text>Cancel</Text>
        </Pressable>
      </View>
    ),
  });

  return <CopilotChat agentName="gen-ui-interrupt" />;
}
```

The rendered `CopilotChat` and `CopilotModal` from `/components` draw the element after the last message. Whatever you pass to `resolve` goes back to the agent as the answer to the matching interrupt.

<Callout type="warn" title="Match the agent on both sides">
  The rendered chat picks its agent with `agentName`, and it doesn't pass that agent to the hooks around it. Without an `agentId`, `useInterrupt` listens to the agent named `"default"`. Give `useInterrupt` the same agent as the chat, or the interrupt never appears.
</Callout>

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

### Key props [#key-props]

- **`agentId`**: must match a runtime-registered agent. If you leave it out, the hook uses the agent of the surrounding chat configuration, then `"default"`. The root `CopilotChat` sets that configuration for its children. The rendered chat from `/components` doesn't. A mismatch means the interrupt never appears.
- **`render`**: receives `{ event, interrupt, interrupts, result, resolve, cancel }` and returns a React Native element.
- **`renderInChat`**: `true` by default, which hands the element to the rendered chat. Set it to `false` to get the element back from the hook and place it yourself. See [Headless Interrupts](/react-native/langgraph-python/human-in-the-loop/headless).
- **`handler`**: runs before `render`. It can resolve the interrupt early, or return a value that `render` receives as `result`.
- **`enabled`**: filters which interrupts this hook handles.

## 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, tag each payload with a `type` field and install one `useInterrupt` per shape, each gated by `enabled`:

```tsx
// The LangGraph adapter sends `event.value` as a JSON string.
const readValue = (value: unknown): { type?: string; content?: string } =>
  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} />
  ),
});
```

`AskCard` and `ApproveCard` are your own components. For a standard interrupt, `event.value` is the primary `Interrupt` object, so read your tag from its `metadata` instead.

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

When an interrupt can sometimes be answered without the user (for example, the current user already has permission), pass a `handler`. It runs before `render`. It can call `resolve(...)` to resume the agent early, 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 department = await lookupUserDepartment(); // your own lookup
    if (value.accessDepartment === department || department === "admin") {
      await resolve({ code: "AUTH_BY_DEPARTMENT" });
      return;
    }
    return { department };
  },
  render: ({ result, resolve }) => (
    <RequestAccessCard
      department={result?.department}
      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/react-native/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]

An agent that follows the AG-UI protocol signals an interrupt with a `RUN_FINISHED` event whose outcome carries the interrupts:

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

The hook shows the interrupts after the run finalizes. `render` receives:

- **`interrupt`**: the primary `Interrupt` (`interrupts[0]`), with shape `{ id, reason, message?, toolCallId?, responseSchema?, expiresAt?, metadata? }`.
- **`interrupts`**: every open interrupt.
- **`resolve(payload?, interruptId?)`**: records an answer for the targeted interrupt. The run resumes once every open interrupt has an answer.
- **`cancel(interruptId?)`**: records a cancellation for the targeted interrupt. The run also resumes once every open interrupt is addressed.

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

Agents can emit a custom `on_interrupt` event. The LangGraph adapter does this by default. `render` gets its payload in `event.value`, with `interrupt` set to `null` and `interrupts` to `[]`. `resolve(payload)` resumes the run right away, through `forwardedProps.command`. `cancel()` only dismisses the interrupt without resuming, because this flow has no cancel answer.

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

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

```tsx
import { Button, Text, View } from "react-native";
import { useInterrupt } from "@copilotkit/react-native/headless";

function ApprovalPanel() {
  const element = useInterrupt({
    renderInChat: false,
    render: ({ interrupt, resolve, cancel }) => (
      <View style={{ padding: 12, gap: 8 }}>
        <Text>{interrupt?.message ?? "Approve this action?"}</Text>
        <Button title="Approve" onPress={() => resolve({ approved: true })} />
        <Button title="Cancel" onPress={() => cancel()} />
      </View>
    ),
  });

  return element;
}
```

Both methods return the run result once the run restarts, or nothing while other open interrupts still wait for an answer.

### More than one open interrupt [#more-than-one-open-interrupt]

Some agents issue more than one interrupt in a single run. Each has its own `id`, so answer them one by one:

```tsx
render: ({ interrupts, resolve, cancel }) => (
  <View>
    {interrupts.map((item) => (
      <View key={item.id} style={{ flexDirection: "row", gap: 8 }}>
        <Text>{item.message}</Text>
        <Button title="Approve" onPress={() => resolve({ ok: true }, item.id)} />
        <Button title="Cancel" onPress={() => cancel(item.id)} />
      </View>
    ))}
  </View>
),
```

The run resumes only after **every** open interrupt is addressed. If you leave out `interruptId`, the primary interrupt is targeted, and the hook logs a warning when several are open.

### `responseSchema` is not validated [#responseschema-is-not-validated]

An `Interrupt` can carry a `responseSchema`, a JSON Schema that describes the answer the agent expects. `useInterrupt` passes it to `render` as `interrupt.responseSchema`, but it does **not** check your `resolve` payload against it. The agent validates the answer when it resumes.

## Provider setup [#provider-setup]

The component that calls `useInterrupt` or `useHumanInTheLoop` must be under `CopilotKitProvider`:

```tsx title="App.tsx"
import { CopilotKitProvider } from "@copilotkit/react-native/headless";
import { MeetingChat } from "./src/MeetingChat";

const runtimeUrl = "http://localhost:8200/api/copilotkit";

export default function App() {
  return (
    <CopilotKitProvider runtimeUrl={runtimeUrl}>
      <MeetingChat />
    </CopilotKitProvider>
  );
}
```
