Headless Interrupts
Resolve agent interrupts from any UI, without a useInterrupt render slot.
Not available for agent-spec yet
The code on this page comes from the showcase's
interrupt-headless demo, and agent-spec doesn't have it yet. See this page for CopilotKit's Built-in Agent, LangGraph (Python), LangGraph (TypeScript).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.
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.
How is this guide?