# 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-typescript/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 CopilotKit LangGraph SDK

    ```bash
    npm install @copilotkit/sdk-js
    ```

  </Step>
  <Step>
    ### Wire CopilotKit state + tools into your graph

    Tool-based HITL (`useHumanInTheLoop`) registers the tool on the frontend
    and forwards it via `state.copilotkit.actions` — the same wiring as
    frontend tools. The graph-paused pattern (`useInterrupt`) uses
    LangGraph's native `interrupt(...)` primitive inside a node.

~~~~typescript title="frontend-tools.ts"
import type { RunnableConfig } from "@langchain/core/runnables";
import { SystemMessage } from "@langchain/core/messages";
import { MemorySaver, START, StateGraph } from "@langchain/langgraph";
import { ChatOpenAI } from "@langchain/openai";
import {
  convertActionsToDynamicStructuredTools,
  CopilotKitStateAnnotation,
} from "@copilotkit/sdk-js/langgraph";

// CopilotKit forwards frontend tools to the agent via
// `state.copilotkit.actions`. `CopilotKitStateAnnotation` adds that
// channel to your graph's state; `convertActionsToDynamicStructuredTools`
// turns the forwarded action schemas into LangChain tools you can bind
// at model-invocation time.
const AgentStateAnnotation = CopilotKitStateAnnotation;
export type AgentState = typeof AgentStateAnnotation.State;

const SYSTEM_PROMPT = "You are a helpful, concise assistant.";

async function runChatNode(
  state: AgentState,
  config: RunnableConfig,
  model: ChatOpenAI,
) {
  const modelWithTools = model.bindTools!([
    ...convertActionsToDynamicStructuredTools(state.copilotkit?.actions ?? []),
  ]);

  const response = await modelWithTools.invoke(
    [new SystemMessage({ content: SYSTEM_PROMPT }), ...state.messages],
    config,
  );

  return { messages: response };
}

async function chatNode(state: AgentState, config: RunnableConfig) {
  return runChatNode(
    state,
    config,
    new ChatOpenAI({
      modelKwargs: { reasoning_effort: "none" },
      temperature: 0,
      model: "gpt-6-luna",
    }),
  );
}

function compileGraph(node: typeof chatNode) {
  return new StateGraph(AgentStateAnnotation)
    .addNode("chat_node", node)
    .addEdge(START, "chat_node")
    .addEdge("chat_node", "__end__")
    .compile({ checkpointer: new MemorySaver() });
}

export const graph = compileGraph(chatNode);
~~~~

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

```typescript title="src/agent/interrupt-agent.ts"
import { z } from "zod";
import type { RunnableConfig } from "@langchain/core/runnables";
import { tool } from "@langchain/core/tools";
import { ToolNode } from "@langchain/langgraph/prebuilt";
import type { AIMessage } from "@langchain/core/messages";
import { SystemMessage } from "@langchain/core/messages";
import {
  MemorySaver,
  START,
  StateGraph,
  Annotation,
  interrupt,
} from "@langchain/langgraph";
import {
  convertActionsToDynamicStructuredTools,
  CopilotKitStateAnnotation,
} from "@copilotkit/sdk-js/langgraph";

// Demo-only fixed timezone offset (Pacific = UTC-7 in PDT, UTC-8 in PST).
// A real app would use the user's calendar + locale; we hardcode Pacific so
// screenshots are stable. Mirrors interrupt_agent.py.
const DEMO_TZ_OFFSET_HOURS = -7; // PDT

interface TimeSlot {
  label: string;
  iso: string;
}

function candidateSlots(): TimeSlot[] {
  const now = new Date();
  // "Tomorrow"
  const tomorrow = new Date(now);
  tomorrow.setDate(now.getDate() + 1);

  // "Monday" — at least 2 days away to avoid collisions with "Tomorrow"
  const dayOfWeek = now.getDay(); // 0=Sun, 1=Mon, ..., 6=Sat
  let daysToMonday = (1 - dayOfWeek + 7) % 7;
  if (daysToMonday <= 1) daysToMonday += 7;
  const nextMonday = new Date(now);
  nextMonday.setDate(now.getDate() + daysToMonday);

  const fmt = (d: Date, hour: number, minute = 0): string => {
    // Build an ISO-like string with the demo timezone offset
    const sign = DEMO_TZ_OFFSET_HOURS >= 0 ? "+" : "-";
    const absOffset = Math.abs(DEMO_TZ_OFFSET_HOURS);
    const hh = String(absOffset).padStart(2, "0");
    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}T${String(hour).padStart(2, "0")}:${String(minute).padStart(2, "0")}:00${sign}${hh}:00`;
  };

  return [
    { label: "Tomorrow 10:00 AM", iso: fmt(tomorrow, 10) },
    { label: "Tomorrow 2:00 PM", iso: fmt(tomorrow, 14) },
    { label: "Monday 9:00 AM", iso: fmt(nextMonday, 9) },
    { label: "Monday 3:30 PM", iso: fmt(nextMonday, 15, 30) },
  ];
}

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

const AgentStateAnnotation = Annotation.Root({
  ...CopilotKitStateAnnotation.spec,
});

export type AgentState = typeof AgentStateAnnotation.State;

const scheduleMeeting = tool(
  async ({ topic, attendee }: { topic: string; attendee?: string | null }) => {
    // langgraph's `interrupt()` pauses execution and forwards the payload to
    // the client. The frontend v2 `useInterrupt` hook renders the picker and
    // calls `resolve(...)` with the user's selection, which comes back here.
    const response: unknown = interrupt({
      topic,
      attendee: attendee ?? null,
      slots: candidateSlots(),
    });

    if (response && typeof response === "object") {
      const resp = response as Record<string, unknown>;
      if (resp.cancelled) {
        return `User cancelled. Meeting NOT scheduled: ${topic}`;
      }
      const chosenLabel =
        (resp.chosen_label as string | undefined) ??
        (resp.chosen_time as string | undefined);
      if (chosenLabel) {
        return `Meeting scheduled for ${chosenLabel}: ${topic}`;
      }
    }

    return `User did not pick a time. Meeting NOT scheduled: ${topic}`;
  },
  {
    name: "schedule_meeting",
    description:
      "Ask the user to pick a time slot for a call, via an in-chat picker.",
    schema: z.object({
      topic: z
        .string()
        .describe("Short human-readable description of the call's purpose."),
      attendee: z
        .string()
        .nullable()
        .optional()
        .describe("Who the call is with (optional)."),
    }),
  },
);
```

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