# 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/crewai-crews/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 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. This agent does it 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 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/crewai-crews/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>
  );
}
```
