Pausing the Agent for Input
Pause an agent run mid-tool, hand control to a custom React component, and resume with the user's answer.
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 component, and resumes the run with the answer. How the pause
works depends on your agent framework.
Some agent frameworks cannot pause a run mid-tool the way LangGraph's
interrupt() does, so this demo registers schedule_meeting with
useHumanInTheLoop instead. The agent calls schedule_meeting like
any other tool. The picker renders in the chat, and respond(...) sends
the user's choice back to the agent as the tool result.
The user sees the same flow: the agent pauses, the user answers, and the
agent continues. Only the mechanism is different.
When should I use this?
Reach for useInterrupt when the pause is a checkpoint in your
agent code where the code path must stop and wait for a human,
not 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 an interrupt that resumes with a payload
For LLM-initiated pauses where the model decides on the fly to ask
the user, prefer useHumanInTheLoop.
The frontend: useHumanInTheLoop renders the picker
useHumanInTheLoop registers schedule_meeting as a frontend tool and
renders the picker inline in the chat. When the user picks a slot or
cancels, respond(...) sends the choice back as the tool result. This is
the frontend-tool equivalent of
useInterrupt's event / resolve pair:
import {
CopilotKit,
CopilotChat,
useHumanInTheLoop,
} from "@copilotkit/react-core/v2";
import { z } from "zod";
import type { TimeSlot } from "./_components/time-picker-card";
import { TimePickerCard } from "./_components/time-picker-card";
import { generateFallbackSlots } from "../_shared/interrupt-fallback-slots";
import { useGenUiInterruptSuggestions } from "./suggestions";
export default function GenUiInterruptDemo() {
return (
<CopilotKit runtimeUrl="/api/copilotkit" agent="gen-ui-interrupt">
<div className="flex justify-center items-center h-screen w-full">
<div className="h-full w-full max-w-4xl">
<Chat />
</div>
</div>
</CopilotKit>
);
}
function Chat() {
useGenUiInterruptSuggestions();
// MS Agent Framework has no `interrupt()` primitive, so the LangGraph
// showcase's `useInterrupt({ renderInChat: true })` hook is silently dead
// here — it listens for AG-UI `interrupt` events that the MAF backend
// never emits, leaving the chat stuck on the "[Scheduling...]" tool-call
// placeholder.
//
// `interrupt_agent.py` instead exposes `schedule_meeting` as a tool the
// model is instructed to call; the frontend registers a matching
// `useHumanInTheLoop` here, renders the picker inline, and resolves the
// call via `respond(...)`. UX matches LGP's interrupt-rendered card; the
// mechanism differs.
useHumanInTheLoop({
agentId: "gen-ui-interrupt",
name: "schedule_meeting",
description:
"Ask the user to pick a meeting time. The picker renders inline in " +
"the chat; the chosen slot is returned to the agent so it can confirm.",
parameters: z.object({
topic: z
.string()
.describe("What the meeting is about (e.g. 'Intro with sales')"),
attendee: z
.string()
.optional()
.describe("Who the meeting is with (e.g. 'Alice')"),
}),
render: ({ args, respond }: any) => {
// `TimePickerCard` here is the gen-ui-interrupt-specific variant
// (under `_components/`) that gates buttons on its own internal
// `picked`/`cancelled` state — it doesn't take a `status` prop like
// the hitl-in-chat version. That's fine: the buttons stay clickable
// until the user makes a choice and `respond(...)` resolves the
// tool call.
const topic = (args?.topic as string | undefined) ?? "a call";
const attendee = args?.attendee as string | undefined;
const slots = generateFallbackSlots();
return (
<TimePickerCard
topic={topic}
attendee={attendee}
slots={slots}
onSubmit={(result) => respond?.(result)}
/>
);
},
});The backend: agent instructed to call the frontend tool
The agent has no local schedule_meeting implementation. The tool is
registered entirely on the frontend. The backend's only job is to
instruct the model to call schedule_meeting whenever the user wants
to book a meeting. AG-UI routes the tool call to the client, where
the Promise-returning handler takes over:
public AIAgent CreateInterruptAgent()
{
var chatClient = _openAiClient.GetChatClient("gpt-6-luna").AsLunaChatClient();
// No backend fallback tool is registered. If the frontend tool is
// missing, the demo should fail visibly instead of bypassing the
// picker with a server-side response.
var harnessAgent = chatClient.AsHarnessAgent(
HarnessMaxContextWindowTokens,
HarnessMaxOutputTokens,
new HarnessAgentOptions
{
Name = "InterruptAgent",
Description = "Interrupt scheduling assistant (NOT-SUPPORTED) powered by Microsoft Agent Harness over Microsoft Agent Framework.",
ChatOptions = new ChatOptions
{
Instructions = SystemPrompt,
MaxOutputTokens = HarnessMaxOutputTokens,
Tools = [],
},
});
return new SharedStateAgent(harnessAgent, _jsonSerializerOptions, _loggerFactory.CreateLogger<SharedStateAgent>());
}Ask the agent to book a call. The time picker appears in the chat. Pick a slot, and the agent confirms the booked time.
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 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")
When the agent backend conforms to the AG-UI protocol, it signals an interrupt
by emitting a RUN_FINISHED event whose outcome carries the interrupts array:
outcome.type === "interrupt"
outcome.interrupts // Interrupt[]The hook detects this on onRunFinishedEvent and exposes the interrupts on the
render props after onRunFinalized fires. Your render function receives:
interrupt: the primaryInterrupt(interrupts[0]), with shape{ id, reason, message?, toolCallId?, responseSchema?, expiresAt?, metadata? }.interrupts: the full open set (usually one, but multi-interrupt is supported, as described below).resolve(payload?, interruptId?): records{ status: "resolved", payload }for the targeted interrupt (defaults to the primary). The agent run resumes once every open interrupt has a response.cancel(interruptId?): records{ status: "cancelled" }for the targeted interrupt. Same accumulate-then-submit logic applies.
Each resume entry carries the interrupt id, the status, and your payload.
resolve and cancel send no metadata.
Custom-event flow (on_interrupt)
Agents that emit a custom on_interrupt event use this flow. The LangGraph
adapter emits this event by default. The hook detects this on onCustomEvent and sets
interrupt to null and interrupts to []. The payload is in
event.value. Calling resolve(payload) resumes via forwardedProps.command
(the custom-event resume mechanism). cancel() dismisses the interrupt without
resuming. The agent never receives a response.
Priority
If both signals appear on the same run, the standard flow wins.
Approve / Cancel example
function ApprovalInterrupt() {
useInterrupt({
render: ({ interrupt, resolve, cancel }) => (
<div className="p-3 border rounded">
<p>{interrupt?.message ?? "Approve this action?"}</p>
<div className="mt-2 flex gap-2">
<button onClick={() => resolve({ approved: true })}>Approve</button>
<button onClick={() => cancel()}>Cancel</button>
</div>
</div>
),
});
return null;
}resolve({ approved: true }) records a resolved entry and submits the resume
array to the agent. cancel() records a cancelled entry and does the same.
Both return the RunAgentResult once the run restarts.
Multi-interrupt behavior
Some agents issue more than one interrupt in a single run (e.g. two independent
approvals). Each interrupt has its own id. Address them individually:
useInterrupt({
render: ({ interrupts, resolve, cancel }) => (
<ul>
{interrupts.map((i) => (
<li key={i.id}>
{i.message}
<button onClick={() => resolve({ ok: true }, i.id)}>Approve</button>
<button onClick={() => cancel(i.id)}>Cancel</button>
</li>
))}
</ul>
),
});The agent run only resumes once every open interrupt has been addressed.
Calling resolve or cancel with a specific interruptId marks that interrupt
done; the hook auto-submits the accumulated responses when the last one is
addressed. If you omit interruptId, the primary interrupt (interrupts[0])
is targeted.
responseSchema: surface only, no client-side validation
The Interrupt type exposes a responseSchema field (a JSON Schema object)
that the agent can use to describe the expected payload shape. useInterrupt
surfaces this field on interrupt.responseSchema for your UI to read
(e.g. to drive a form), but it does not validate resolve payloads against
it. Validation is the agent's responsibility on resume.
How is this guide?