Headless Interrupts

Resolve agent interrupts from any UI, without a useInterrupt render slot.

Headless Interrupt (testing)

Waking up the demo

What is this?

Sometimes the agent's question belongs outside the chat, in a dashboard, a side panel, or a modal. A headless interrupt lets any component show the question and resume the run with the answer. No chat needs to be mounted.

This page shows how to resolve an interrupt without the chat. You build the resolver from the same hooks that useInterrupt uses. It can be a button grid, a form, a modal, or a keyboard shortcut.

For promise-based agent frameworks there is no native interrupt primitive, so the headless variant uses useFrontendTool with a Promise-based handler. The handler exposes its pending payload via React state, so a separate "app surface" can render the picker outside the chat. It resolves the Promise once the user interacts. Same UX, different mechanism.

When should I use this?

  • Testing / Playwright fixtures: a deterministic, chat-less button grid is easier to drive than a chat surface where the picker only appears after an LLM call.
  • Non-chat UIs: dashboards, side panels, inspector surfaces, or any place where you want the agent's interrupt without the chat transcript.
  • Custom flow control: when you need to know exactly when the interrupt arrived (e.g. to gate other UI) and when it was resolved.
  • Research / debugging: when you want to observe the raw AG-UI custom events without the abstraction layer.

If you just want "a picker in chat", just use useInterrupt. For pauses that the model decides on, use useHumanInTheLoop.

The primitives

The render callback intentionally returns null. The picker UI lives in the app surface, not in the chat transcript. The handler's pending state drives whether the picker is shown:

page.tsx
  useFrontendTool({
    name: "schedule_meeting",
    description:
      "Ask the user to pick a time slot for a meeting via a picker popup " +
      "that appears outside the chat. Blocks until the user chooses a " +
      "slot or cancels.",
    parameters: z.object({
      topic: z
        .string()
        .describe("Short human-readable description of the meeting."),
      attendee: z
        .string()
        .optional()
        .describe("Who the meeting is with (optional)."),
    }),
    // Async handler: sets the pending payload so the popup renders, then
    // returns a Promise that only resolves once the user interacts with the
    // popup. This is the MS Agent shim for the LangGraph headless interrupt
    // `resume` flow.
    handler: async ({
      topic,
      attendee,
    }: {
      topic: string;
      attendee?: string;
    }): Promise<string> => {
      setPending({ topic, attendee });
      const result = await new Promise<PickerResult>((resolve) => {
        resolverRef.current = resolve;
      });
      setPending(null);
      if ("cancelled" in result && result.cancelled) {
        return "User cancelled. Meeting NOT scheduled.";
      }
      if ("chosen_label" in result) {
        return `Meeting scheduled for ${result.chosen_label}.`;
      }
      return "User did not pick a time. Meeting NOT scheduled.";
    },
    // Render nothing inside the chat — the UI lives in the app surface.
    render: () => null,
  });

A few things this pattern is careful about:

  • The handler stages its resolve callback in a ref keyed by tool-call id, so concurrent tool calls don't trample each other's resolvers.
  • setPending is called from inside the handler so the app surface re-renders the picker as soon as the agent calls the tool, and again with null after the user interacts so the picker disappears.
  • render: () => null keeps the chat transcript clean. The headless variant deliberately bypasses inline rendering.

How is this guide?