copilotkit--copilotkit/skills/react-core/references/human-in-the-loop.md

CopilotKit Human-in-the-Loop (React)

This skill builds on copilotkit/provider-setup, copilotkit/client-side-tools, and copilotkit/rendering-tool-calls.

useHumanInTheLoop is useFrontendTool minus the handler plus a render that receives a respond function. The hook synthesizes a Promise-based handler — the Promise resolves when respond(result) is called. No respond call → infinite hang.

Status is camelCase: "inProgress" | "executing" | "complete". respond is undefined except during "executing".

UI-kit detection rule

Before writing the approval UI, check the consumer's package.json for a UI kit (shadcn AlertDialog, MUI Dialog, Chakra Modal, Ant Modal, Mantine Modal) and reuse it. Don't hand-roll an overlay.

Setup

"use client";
import { useHumanInTheLoop } from "@copilotkit/react-core/v2";
import { z } from "zod";
import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogTitle,
} from "@/components/ui/alert-dialog";

export function DeleteConfirmHITL() {
  useHumanInTheLoop({
    name: "confirmDelete",
    description: "Confirm a destructive delete with the user",
    parameters: z.object({ id: z.string(), label: z.string() }),
    render: ({ status, args, respond }) => (
      <AlertDialog open>
        <AlertDialogContent>
          <AlertDialogHeader>
            <AlertDialogTitle>Delete {args.label}?</AlertDialogTitle>
            <AlertDialogDescription>
              This action cannot be undone.
            </AlertDialogDescription>
          </AlertDialogHeader>
          <AlertDialogFooter>
            <AlertDialogCancel
              disabled={status !== "executing"}
              onClick={() => respond?.("denied")}
            >
              Cancel
            </AlertDialogCancel>
            <AlertDialogAction
              disabled={status !== "executing"}
              onClick={() => respond?.("approved")}
            >
              Delete
            </AlertDialogAction>
          </AlertDialogFooter>
        </AlertDialogContent>
      </AlertDialog>
    ),
  });
  return null;
}

Core Patterns

Always call respond in every branch

render: ({ status, args, respond }) => {
  if (status !== "executing" || !respond) {
    return <div>Awaiting decision…</div>;
  }
  return (
    <div>
      <button onClick={() => respond("approved")}>Approve</button>
      <button onClick={() => respond("denied")}>Reject</button>
      <button onClick={() => respond({ action: "skip", reason: "timeout" })}>
        Skip
      </button>
    </div>
  );
};

Abort the run on unmount so threads unlock

import { useAgent, UseAgentUpdate } from "@copilotkit/react-core/v2";
import { useEffect, useRef } from "react";

function HITLHost() {
  const { agent } = useAgent({
    agentId: "default",
    updates: [UseAgentUpdate.OnRunStatusChanged],
  });
  // Track isRunning in a ref so the unmount cleanup reads the latest value
  // without re-firing on every transition.
  const runningRef = useRef(false);
  useEffect(() => {
    runningRef.current = agent.isRunning;
  }, [agent.isRunning]);

  useEffect(() => {
    return () => {
      if (runningRef.current) agent.abortRun();
    };
  }, [agent]);

  return <DeleteConfirmHITL />;
}

useAgent returns { agent } only — run status lives on agent.isRunning. Depending the cleanup effect directly on agent.isRunning would fire the cleanup on every status flip (not just unmount), aborting active runs. The ref pattern captures the latest value while the cleanup runs only when the host component truly unmounts.

Collect structured user input mid-run

useHumanInTheLoop({
  name: "askUserForPriority",
  parameters: z.object({ taskId: z.string() }),
  render: ({ status, args, respond }) => {
    if (status !== "executing" || !respond) return <div>Waiting…</div>;
    return (
      <div>
        {["low", "medium", "high"].map((p) => (
          <button
            key={p}
            onClick={() => respond({ taskId: args.taskId, priority: p })}
          >
            {p}
          </button>
        ))}
      </div>
    );
  },
});

Common Mistakes

CRITICAL — Never calling respond()

Wrong:

useHumanInTheLoop({
  name: "confirmDelete",
  parameters: z.object({ id: z.string() }),
  render: ({ args, status, respond }) => (
    <div>
      <p>Delete {args.id}?</p>
      <button>OK</button>
    </div>
  ),
});

Correct:

useHumanInTheLoop({
  name: "confirmDelete",
  parameters: z.object({ id: z.string() }),
  render: ({ args, status, respond }) => (
    <div>
      <p>Delete {args.id}?</p>
      <button onClick={() => respond?.("approved")}>OK</button>
      <button onClick={() => respond?.("denied")}>Cancel</button>
    </div>
  ),
});

The synthesized handler returns a Promise that resolves only when respond is called. Never calling it (including reject / cancel paths) hangs the run indefinitely and leaves the thread locked on the server.

Source: packages/react-core/src/v2/hooks/use-human-in-the-loop.tsx:13-26

CRITICAL — Writing a custom overlay when the app has a Dialog primitive

Wrong:

render: ({ respond }) => (
  <div style={{ position: "fixed", inset: 0, background: "rgba(0,0,0,0.5)" }}>
    …
  </div>
);

Correct:

import {
  AlertDialog,
  AlertDialogContent,
  AlertDialogAction,
} from "@/components/ui/alert-dialog";

render: ({ respond }) => (
  <AlertDialog open>
    <AlertDialogContent>
      …
      <AlertDialogAction onClick={() => respond?.("approved")}>
        OK
      </AlertDialogAction>
    </AlertDialogContent>
  </AlertDialog>
);

Check package.json for shadcn / MUI / Chakra / Ant / Mantine before writing an overlay. Their dialog primitives handle focus trapping, escape-to-close, and accessibility — raw JSX skips all of that.

Source: maintainer interview (Phase 2c)

HIGH — Calling respond during inProgress or complete

Wrong:

render: ({ status, respond }) => (
  <button onClick={() => (respond as any)("yes")}>Yes</button>
);

Correct:

render: ({ status, respond }) =>
  status === "executing" && respond ? (
    <button onClick={() => respond("yes")}>Yes</button>
  ) : (
    <p>Waiting…</p>
  );

respond is undefined outside status === "executing". Widening it to any silently no-ops — the button click appears to work, but nothing resolves the Promise.

Source: packages/react-core/src/v2/types/human-in-the-loop.ts:8-32

HIGH — Unmounting the render mid-executing

Wrong:

// User clicks away to a different route while the agent is waiting on respond()

Correct:

// Keep the HITL prompt at a layout level that persists across route changes, OR abort on unmount:
const { agent } = useAgent({
  agentId: "default",
  updates: [UseAgentUpdate.OnRunStatusChanged],
});
const runningRef = useRef(false);
useEffect(() => {
  runningRef.current = agent.isRunning;
}, [agent.isRunning]);
useEffect(
  () => () => {
    if (runningRef.current) agent.abortRun();
  },
  [agent],
);

useHumanInTheLoop removes its renderer on unmount (unlike useFrontendTool, which keeps renderers for history). If the renderer unmounts mid-executing, the pending Promise is abandoned and the run hangs. Either lift the HITL UI to a layout-level component, or abort the run on unmount.

Source: packages/react-core/src/v2/hooks/use-human-in-the-loop.tsx:76-80

MEDIUM — Using hyphenated "in-progress" status

Wrong:

render: ({ status }) => (status === "in-progress" ? <Spinner /> : <Form />);

Correct:

render: ({ status }) => (status === "inProgress" ? <Spinner /> : <Form />);

Same camelCase rule as rendering-tool-calls: the discriminated union only matches "inProgress" | "executing" | "complete".

Source: packages/react-core/src/v2/types/human-in-the-loop.ts:8-32