useInterrupt (LangGraph)

What is this?

LangGraph ships a first-class interrupt() primitive that lets a running node suspend itself and hand control to the client. The run is frozen server-side until the client resolves the interrupt with a payload, at which point the node resumes as if interrupt() had simply returned that payload.

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?

Reach for useInterrupt when the pause is a graph-enforced checkpoint — the code path must stop and wait for a human — rather than 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 interrupt(...) and resume with a payload

For LLM-initiated pauses — where the model decides on the fly to ask the user — prefer useHumanInTheLoop.

The backend: interrupt() inside a tool

The showcase gen-ui-interrupt cell exposes a schedule_meeting tool. When the model calls it, the tool issues a langgraph.interrupt(...) with the meeting context. The run freezes here until the client resolves — the resolution becomes the return value of interrupt(), which the tool then turns into a final string for the model:

@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.
    """
    # 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.
    response: Any = interrupt({"topic": topic, "attendee": attendee})

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

Two things to note:

• The payload ({"topic": topic, "attendee": attendee}) is what the frontend receives as event.value. 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

On the client you register a useInterrupt hook per agent. When the paused run arrives, its payload is handed to render as event.value, and resolve(...) is how you resume the run:

  useInterrupt({
    agentId: "gen-ui-interrupt",
    renderInChat: true,
    render: ({ event, resolve }) => {
      const payload = (event.value ?? {}) as {
        topic?: string;
        attendee?: string;
      };
      return (
        <TimePickerCard
          topic={payload.topic ?? "a call"}
          attendee={payload.attendee}
          slots={DEFAULT_SLOTS}
          onSubmit={(result) => resolve(result)}
        />
      );
    },
  });

Whatever you pass to resolve is round-tripped back to the agent as the return value of the matching interrupt(...) call.

Key props

• agentId — must match a runtime-registered agent. If omitted, the hook assumes "default". A mismatch means the interrupt never fires.
• render — receives { event, resolve }. event.value is the payload you passed to interrupt(...) on the server.
• renderInChat — when true (as above), the picker appears inline in the chat transcript, between the paused assistant turn and the still-pending continuation.

Multiple interrupts? Add a type and gate with enabled

If your graph 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:

useInterrupt({
  agentId: "gen-ui-interrupt",
  enabled: ({ eventValue }) => eventValue.type === "ask",
  render: ({ event, resolve }) => (
    <AskCard question={event.value.content} onAnswer={resolve} />
  ),
});

useInterrupt({
  agentId: "gen-ui-interrupt",
  enabled: ({ eventValue }) => eventValue.type === "approval",
  render: ({ event, resolve }) => (
    <ApproveCard content={event.value.content} onAnswer={resolve} />
  ),
});

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 short-circuit the UI, or return a value that render receives as result:

useInterrupt({
  agentId: "gen-ui-interrupt",
  handler: async ({ event, resolve }) => {
    const dept = await lookupUserDepartment();
    if (event.value.accessDepartment === dept || dept === "admin") {
      resolve({ code: "AUTH_BY_DEPARTMENT" });
      return; // skip render
    }
    return { dept };
  },
  render: ({ result, event, resolve }) => (
    <RequestAccessCard
      dept={result.dept}
      onRequest={() => resolve({ code: "REQUEST_AUTH" })}
      onCancel={() => resolve({ code: "CANCEL" })}
    />
  ),
});

Going further

• Tool-based HITL with useHumanInTheLoop — for LLM-initiated pauses.
• Headless interrupts — compose the lower-level primitives (useAgent, agent.subscribe, copilotkit.runAgent) to resolve interrupts outside a chat surface.