# 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/deepagents/human-in-the-loop) instead.

## The backend: pause the run in your agent [#the-backend-pause-the-run-in-your-agent]

Deep Agents compile to LangGraph graphs, so they support both patterns.
`CopilotKitMiddleware` forwards a `useHumanInTheLoop` tool to the model, the
same way it forwards any frontend tool. For `useInterrupt`, call LangGraph's
native `interrupt()` from a middleware hook. Deep Agents has no live demo on
these pages yet, so the steps below carry the code.

<Steps>
  <Step>
    ### Call `interrupt` from a middleware hook

    A Deep Agent has no custom nodes, so put the pause in a middleware hook.
    This hook runs before the model call and asks the user to name the agent
    the first time. The middleware also declares the `agent_name` state field
    that stores the answer.

    <Tabs groupId="agent_language" items={['Python', 'TypeScript']} persist>
      <Tab value="Python">
        ```python title="agent.py"
        from typing import Any, NotRequired

        from copilotkit import CopilotKitMiddleware, CopilotKitState
        from deepagents import create_deep_agent
        from langchain_openai import ChatOpenAI
        from langchain.agents.middleware import AgentMiddleware
        from langgraph.runtime import Runtime
        from langgraph.types import interrupt

        class AgentState(CopilotKitState):
            agent_name: NotRequired[str]

        class AgentNameMiddleware(AgentMiddleware[AgentState, Any]):
            state_schema = AgentState

            def before_model(self, state: AgentState, runtime: Runtime[Any]) -> dict[str, Any] | None:
                if not state.get("agent_name"):
                    # Interrupt and wait for the user to respond with a name
                    name = interrupt("Before we start, what would you like to call me?")
                    return {"agent_name": name}
                return None

        agent = create_deep_agent(
            model=ChatOpenAI(model="gpt-6-luna", reasoning_effort="none"),
            middleware=[
                AgentNameMiddleware(),
                CopilotKitMiddleware(expose_state=["agent_name"]),
            ],
            system_prompt=(
                "You are a helpful assistant. After the user chooses a name, "
                "Current agent state contains agent_name. Use that value as your own name."
            ),
        )
        ```
      </Tab>
      <Tab value="TypeScript">
        ```ts title="agent.ts"
        import {
          createCopilotkitMiddleware,
          zodState,
        } from "@copilotkit/sdk-js/langgraph";
        import { createMiddleware } from "langchain";
        import { createDeepAgent } from "deepagents";
        import { interrupt } from "@langchain/langgraph";
        import { z } from "zod";

        const agentNameMiddleware = createMiddleware({
          name: "AgentState",
          stateSchema: z.object({
            // zodState keeps this custom field in AG-UI state snapshots.
            agentName: zodState(z.string().optional()),
          }),
          beforeModel: (state) => {
            if (!state.agentName) {
              // Interrupt and wait for the user to respond with a name
              const name: string = interrupt("Before we start, what would you like to call me?");
              return { agentName: name };
            }
          },
        });

        const stateAwareCopilotKitMiddleware = createCopilotkitMiddleware({
          exposeState: ["agentName"],
        });

        export const agent = createDeepAgent({
          model: "openai:gpt-6-luna",
          middleware: [
            agentNameMiddleware,
            stateAwareCopilotKitMiddleware,
          ],
          systemPrompt:
            "You are a helpful assistant. After the user chooses a name, " +
            "Current agent state contains agentName. Use that value as your own name.",
        });
        ```
      </Tab>
    </Tabs>

  </Step>
  <Step>
    ### Make the agent aware of the answer

    Resuming an interrupt and telling the model about the answer are separate
    steps. By default the model is not aware of the interaction: the run
    resumes, and the model never sees what the user chose.

    The custom middleware saves the answer in thread state. In TypeScript,
    `zodState` also keeps the custom field in the graph's output, so AG-UI can
    send it to the frontend. The CopilotKit middleware then adds only the
    allowlisted field (`expose_state` / `exposeState`) to each model request,
    and the system prompt says what that field means. State exposure is off by
    default, so without the allowlist the model never sees the name. Keep the
    allowlist narrow, and do not expose unrelated application state.

  </Step>
  <Step>
    ### Handle the interrupt in your frontend

    Give `useInterrupt` a component to render, and call `resolve` with the
    user's answer. Whatever you pass to `resolve` becomes the return value of
    `interrupt()`.

    ```tsx title="app/page.tsx"
    import { useInterrupt } from "@copilotkit/react-core/v2";
    // ...

    const YourMainContent = () => {
      // ...
      // styles omitted for brevity
      useInterrupt({
        render: ({ event, resolve }) => (
          <div>
            <p>{event.value}</p>
            <form onSubmit={(e) => {
              e.preventDefault();
              resolve((e.target as HTMLFormElement).response.value);
            }}>
              <input type="text" name="response" placeholder="Enter your response" />
              <button type="submit">Submit</button>
            </form>
          </div>
        )
      });
      // ...

      return <div>{/* ... */}</div>
    }
    ```

    The AG-UI LangGraph adapter sends an object interrupt value as a JSON
    string, so parse `event.value` before you read fields from it.

    When your app already selects an agent in its `CopilotKit` provider,
    `useInterrupt` uses that agent. Pass `agentId` only when this component
    must target a different agent in a multi-agent app.

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

> **Not available for Langchain DeepAgents yet.** This sample comes from the showcase's `gen-ui-interrupt` demo, and Langchain DeepAgents doesn't have it yet.

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/deepagents/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>
  );
}
```
