Interactive components
Create approval flows where the agent pauses and waits for human input.
"""LangGraph agent for the Human-in-the-Loop (Interrupt-based) booking demo.Defines a backend tool `schedule_meeting(topic, attendee)` that usesLangGraph's `interrupt()` primitive to pause the run and surface astructured booking payload to the frontend. The frontend `useInterrupt`renderer shows a time picker inline in the chat and resolves with`{chosen_time, chosen_label}` or `{cancelled: true}`, which this toolturns into a human-readable result the agent uses to confirm the booking."""from __future__ import annotationsfrom datetime import datetime, time, timedeltafrom typing import Any, List, Optionalfrom zoneinfo import ZoneInfofrom langchain.agents import create_agentfrom langchain_core.tools import toolfrom langchain_openai import ChatOpenAIfrom langgraph.types import interruptfrom copilotkit import CopilotKitMiddlewareSYSTEM_PROMPT = ( "You are a scheduling assistant. Whenever the user asks you to book a " "call / schedule a meeting, you MUST call the `schedule_meeting` tool. " "Pass a short `topic` describing the purpose and `attendee` describing " "who the meeting is with. After the tool returns, confirm briefly " "whether the meeting was scheduled and at what time, or that the user " "cancelled.")# Demo-only fixed timezone. A real app would use the user's calendar +# locale (e.g. zoneinfo.ZoneInfo(user.timezone) and Google Calendar /# Outlook availability); we hardcode Pacific so screenshots are stable._DEMO_TZ = ZoneInfo("America/Los_Angeles")def _candidate_slots() -> List[dict]: """Upcoming candidate slots, relative to "now" so the picker never shows stale dates.""" now = datetime.now(_DEMO_TZ) tomorrow = (now + timedelta(days=1)).date() # Skip a week when the result would collide with `tomorrow` — i.e. # today is Mon (0 days away, picker would show two slots both # labelled "Monday") or Sun (1 day away, picker would show # "Tomorrow" and "Monday" both pointing at the same date). days_to_monday = (7 - now.weekday()) % 7 if days_to_monday <= 1: days_to_monday += 7 next_monday = (now + timedelta(days=days_to_monday)).date() candidates = [ ("Tomorrow 10:00 AM", tomorrow, time(10, 0)), ("Tomorrow 2:00 PM", tomorrow, time(14, 0)), ("Monday 9:00 AM", next_monday, time(9, 0)), ("Monday 3:30 PM", next_monday, time(15, 30)), ] return [ {"label": label, "iso": datetime.combine(d, t, _DEMO_TZ).isoformat()} for label, d, t in candidates ]@tooldef 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. """ # `interrupt()` pauses the LangGraph run and forwards a structured # payload to the client. The frontend v2 `useInterrupt` hook renders # the picker inline in the chat, then calls `resolve(...)` with the # user's selection — that value comes back here as `response`. response: Any = interrupt( { "topic": topic, "attendee": attendee, "slots": _candidate_slots(), } ) 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}"model = ChatOpenAI(model="gpt-5.4")graph = create_agent( model=model, tools=[schedule_meeting], middleware=[CopilotKitMiddleware()], system_prompt=SYSTEM_PROMPT,)What is this?#
Interactive generative UI creates flows where the agent pauses execution and waits for user input before continuing. This enables approval workflows, confirmation dialogs, and any scenario where human judgment is needed mid-execution.
When should I use this?#
Use interactive generative UI when you need:
- Approval/rejection flows (e.g. "Run this command?")
- User decisions that the agent should know about
- Confirmation dialogs with structured responses
- Any flow where the agent pauses for human judgment
How it works in code#
On the frontend, register an interrupt renderer with useInterrupt. When the
agent pauses, your component mounts inline in the chat, captures the user's
choice, and resumes the run with that input.
import { CopilotKit, CopilotChat, useInterrupt,} from "@copilotkit/react-core/v2";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(); // `useInterrupt` is the low-level primitive for handling LangGraph // `interrupt(...)` events. The backend's `schedule_meeting` tool surfaces // a structured payload — `{ topic, attendee, slots }` — which we render // inline in the chat as a message bubble. Calling `resolve(...)` resumes // the LangGraph run with the user's selection. useInterrupt({ agentId: "gen-ui-interrupt", renderInChat: true, render: ({ event, resolve }) => { // The AG-UI adapter JSON-stringifies interrupt values, so parse // when needed to extract the structured payload. const raw = event.value ?? {}; const payload = (typeof raw === "string" ? JSON.parse(raw) : raw) as { topic?: string; attendee?: string; slots?: TimeSlot[]; }; const slots = payload.slots && payload.slots.length > 0 ? payload.slots : generateFallbackSlots(); return ( <TimePickerCard topic={payload.topic ?? "a call"} attendee={payload.attendee} slots={slots} onSubmit={(result) => { // Defer resolve so React commits the picked/cancelled state // before useInterrupt clears the interrupt element. A single // requestAnimationFrame is not reliable — rAF fires before // React's commit in some scheduling scenarios. Using a short // setTimeout ensures the commit lands first and the user sees // the "Booked"/"Cancelled" badge before the card unmounts. setTimeout(() => resolve(result), 500); }} /> ); }, });On the backend, the agent calls into the interrupt primitive and waits for the resumed response before continuing the graph.
from __future__ import annotationsfrom datetime import datetime, time, timedeltafrom typing import Any, List, Optionalfrom zoneinfo import ZoneInfofrom langchain.agents import create_agentfrom langchain_core.tools import toolfrom langchain_openai import ChatOpenAIfrom langgraph.types import interruptfrom copilotkit import CopilotKitMiddlewareSYSTEM_PROMPT = ( "You are a scheduling assistant. Whenever the user asks you to book a " "call / schedule a meeting, you MUST call the `schedule_meeting` tool. " "Pass a short `topic` describing the purpose and `attendee` describing " "who the meeting is with. After the tool returns, confirm briefly " "whether the meeting was scheduled and at what time, or that the user " "cancelled.")# Demo-only fixed timezone. A real app would use the user's calendar +# locale (e.g. zoneinfo.ZoneInfo(user.timezone) and Google Calendar /# Outlook availability); we hardcode Pacific so screenshots are stable._DEMO_TZ = ZoneInfo("America/Los_Angeles")def _candidate_slots() -> List[dict]: """Upcoming candidate slots, relative to "now" so the picker never shows stale dates.""" now = datetime.now(_DEMO_TZ) tomorrow = (now + timedelta(days=1)).date() # Skip a week when the result would collide with `tomorrow` — i.e. # today is Mon (0 days away, picker would show two slots both # labelled "Monday") or Sun (1 day away, picker would show # "Tomorrow" and "Monday" both pointing at the same date). days_to_monday = (7 - now.weekday()) % 7 if days_to_monday <= 1: days_to_monday += 7 next_monday = (now + timedelta(days=days_to_monday)).date() candidates = [ ("Tomorrow 10:00 AM", tomorrow, time(10, 0)), ("Tomorrow 2:00 PM", tomorrow, time(14, 0)), ("Monday 9:00 AM", next_monday, time(9, 0)), ("Monday 3:30 PM", next_monday, time(15, 30)), ] return [ {"label": label, "iso": datetime.combine(d, t, _DEMO_TZ).isoformat()} for label, d, t in candidates ]@tooldef 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. """ # `interrupt()` pauses the LangGraph run and forwards a structured # payload to the client. The frontend v2 `useInterrupt` hook renders # the picker inline in the chat, then calls `resolve(...)` with the # user's selection — that value comes back here as `response`. response: Any = interrupt( { "topic": topic, "attendee": attendee, "slots": _candidate_slots(), } ) 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}"