Interactive components

Create approval flows where the agent pauses and waits for human input.

In-Chat HITL (useInterrupt — low-level primitive)

Waking up the demo

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

Nothing to declare on the agent

The agent has no tool of its own for a useHumanInTheLoop tool. Pydantic AI's AG-UI adapter gives the model the frontend tools on every run. When the model calls one, the chat shows your component, and the user's answer returns to the agent as the tool result. Tell the model when to call the tool:

agent.py
from pydantic_ai import Agent
from pydantic_ai.ui.ag_ui import AGUIAdapter
from starlette.applications import Starlette
from starlette.requests import Request
from starlette.responses import Response
from starlette.routing import Route

agent = Agent(
    "openai:gpt-6-luna",
    instructions=(
        "When the user asks for an essay, call the write_essay tool with the full draft. "
        "Wait for the user's answer before you continue."
    ),
)


async def run_agent(request: Request) -> Response:
    return await AGUIAdapter.dispatch_request(request, agent=agent)


app = Starlette(routes=[Route("/", run_agent, methods=["POST"])])

This framework registers schedule_meeting as a frontend tool with useHumanInTheLoop. The agent calls the tool, and the chat renders the picker. The tool call resolves when the picker calls respond(...), after the user chooses a slot or cancels.

page.tsx
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();

  // This framework has no LangGraph-style `interrupt()` primitive, so the
  // LangGraph showcase's `useInterrupt({ renderInChat: true })` hook is
  // silently dead here — it listens for AG-UI `interrupt` events that this
  // backend never emits, leaving the chat stuck on the "[Scheduling...]"
  // tool-call placeholder.
  //
  // The backend instead exposes `schedule_meeting` as a tool the model is
  // instructed to call (Strategy B); 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)}
        />
      );
    },
  });
interrupt_agent.py
SYSTEM_PROMPT = dedent(
    """
    You are a scheduling assistant. Whenever the user asks you to book a call
    or schedule a meeting, you MUST call the `schedule_meeting` tool. Pass a
    short `topic` describing the purpose of the meeting and, if known, an
    `attendee` describing who the meeting is with.

    The `schedule_meeting` tool is implemented on the client: it surfaces a
    time-picker UI to the user and returns the user's selection. After the
    tool returns, briefly confirm whether the meeting was scheduled and at
    what time, or note that the user cancelled. Do NOT ask for approval
    yourself -- always call the tool and let the picker handle the decision.

    Keep responses short and friendly. After you finish executing tools,
    always send a brief final assistant message summarizing what happened so
    the message persists.
    """.strip()
)


agent = Agent(
    model=OpenAIResponsesModel("gpt-6-luna"),
    system_prompt=SYSTEM_PROMPT,
)

Ask the agent to book a call, for example Book an intro call with the sales team to discuss pricing. The time picker appears in the chat. Pick a slot, and the agent confirms the booked time.

How is this guide?