# HITL Overview

> Allow your agent and users to collaborate on complex tasks.

> **Not available for agent-spec yet.** The code on this page comes from the showcase's `hitl-in-chat` demo, and agent-spec doesn't have it yet. See this page for [CopilotKit's Built-in Agent](/human-in-the-loop), [LangGraph (Python)](/langgraph-python/human-in-the-loop), [LangGraph (TypeScript)](/langgraph-typescript/human-in-the-loop).

<Callout type="info" title="See this in Inspector">
  Open Inspector on localhost. Go to **Inspect**, then **Frontend Tools**.
  Your tool and its schema are listed.

  More detail: [Inspector](/agent-spec/inspector).
</Callout>

## What is this? [#what-is-this]

Human-in-the-loop (HITL) lets an agent pause mid-run to collect input,
confirmation, or a choice from the user, then resume with that answer
folded back into its reasoning. It's what turns an autonomous workflow
into a collaborative one: the agent keeps its context, the user keeps
the steering wheel.

<video
  src="https://cdn.copilotkit.ai/docs/copilotkit/images/coagents/human-in-the-loop-example.mp4"
  className="rounded-lg shadow-xl"
  loop
  playsInline
  controls
  autoPlay
  muted
/>

## When should I use this? [#when-should-i-use-this]

Use HITL when you need:

- **Quality control**: a human gate at high-stakes decision points.
- **Missing input**: the agent needs a value only the user knows, such as a meeting time.
- **Risky actions**: the agent must get a yes before it sends, pays, or deletes.
- **Expert input**: the user supplies domain knowledge the model lacks.

## Two patterns for HITL in CopilotKit [#two-patterns-for-hitl-in-copilotkit]

CopilotKit ships two complementary ways to pause an agent turn and ask
the human something. They look similar from the outside (the chat
pauses, a custom component appears, the user answers, the run resumes)
but they're wired differently on the backend, and each has its own niche.

| Pattern | Who decides to pause? | Backend surface |
| --- | --- | --- |
| `useHumanInTheLoop` | The **LLM**, by calling a registered client-side tool | A frontend-only tool description (Zod schema + `render`) |
| `useInterrupt` | Your **agent code**, at a step that must stop for a person | An interrupt your agent emits, for example LangGraph `interrupt()` or Mastra `suspend()` |

**Pick `useHumanInTheLoop`** when the pause is an _agent-initiated_
decision (the model chose to ask the user) and you want the picker UI
inlined into the normal tool-call flow.

**Pick `useInterrupt`** when the pause is a checkpoint in your agent code:
the code path always requires a human answer, and the server-side contract is
an interrupt. On the Built-in Agent, interrupts are temporarily unavailable, so
use `useHumanInTheLoop` there.

<Callout type="warn" title="Use useHumanInTheLoop with Agent Spec">
  Agent Spec agents have no interrupts, so `useInterrupt` does not apply. A
  human-in-the-loop step in Agent Spec is a frontend tool: the agent declares
  it as a `ClientTool`, and the browser renders it with `useHumanInTheLoop`.
</Callout>

Open Agent Spec has no live demo on these pages yet, so the steps below carry
the code.

<Steps>
  <Step>
    ### Create a frontend human-in-the-loop tool

    Register the tool with `useHumanInTheLoop`. Its `render` shows two
    buttons, and the user's click becomes the tool result. In this example,
    the agent offers two options and waits for the user to pick one.

    ```tsx title="page.tsx"
    import { useHumanInTheLoop } from "@copilotkit/react-core/v2"
    import { z } from "zod"

    export function Page() {
      // ...

      useHumanInTheLoop({
        name: "offerOptions",
        description: "Give the user a choice between two options and have them select one.",
        parameters: z.object({
          option_1: z.string().describe("The first option"),
          option_2: z.string().describe("The second option"),
        }),
        render: ({ args, respond }) => {
          if (!respond) return <></>;
          return (
            <div>
              <button onClick={() => respond(`${args.option_1} was selected`)}>{args.option_1}</button>
              <button onClick={() => respond(`${args.option_2} was selected`)}>{args.option_2}</button>
            </div>
          );
        },
      });

      // ...
    }
    ```

  </Step>
  <Step>
    ### Declare the tool in your agent

    Declare the same tool as a `ClientTool` in your Agent Spec config. The
    name must match the `name` in `useHumanInTheLoop`:

    ```python title="agent.py"
    from pyagentspec.property import Property
    from pyagentspec.tools import ClientTool

    offer_options_tool = ClientTool(
        name="offerOptions",
        description="Give the user a choice between two options and have them select one.",
        inputs=[
            Property(title="option_1", json_schema={"title": "option_1", "type": "string"}),
            Property(title="option_2", json_schema={"title": "option_2", "type": "string"}),
        ],
    )
    ```

    Add `offer_options_tool` to the `tools` list of your `Agent`. The agent
    declares the tool, and the browser runs it.

  </Step>
  <Step>
    ### Try it out

    Ask: `Can you show me two good options for a restaurant name?` The two
    options appear as buttons in the chat. After you pick one, the agent
    continues with your choice.

  </Step>
</Steps>

## Pattern 1: `useHumanInTheLoop` (tool-based) [#pattern-1-usehumanintheloop-tool-based]

Register a HITL tool in your React app with `useHumanInTheLoop`.
When the LLM calls that tool, CopilotKit routes the call through your
`render` function, which shows a custom component and calls `respond`
with the user's answer. The agent sees the answer as the tool result and
continues from there.

The sample imports `TimePickerCard` from its own file. The card renders the
slots and calls `onSubmit` with the user's choice. These are its props:

Each slot button calls `onSubmit({ chosen_time: s.iso, chosen_label: s.label })`.
The "None of these work" button calls `onSubmit({ cancelled: true })`. The full
file is in the Code view of the demo at the top of this page.

The picker UI is fed a static list of candidate slots. This is just
data the demo page owns, so you can swap in real availability, a
calendar API, or anything else:

## Pattern 2: `useInterrupt` (agent-paused) [#pattern-2-useinterrupt-agent-paused]

With an interrupt, your agent code enforces the pause, for example with
LangGraph's `interrupt()`:

1. A node calls `interrupt({...})`, and the run stops.
2. The client receives the payload and renders your UI.
3. The user answers, and the run resumes with the answer.

CopilotKit's `useInterrupt` hook is the render contract.

See the [`useInterrupt` deep dive](/agent-spec/human-in-the-loop/useInterrupt) for
the full walkthrough, including the backend tool and render-prop wiring.

## Going headless [#going-headless]

Both patterns above ship with a `render` prop. CopilotKit handles the
"when to show the picker" logic for you. If you want to drive
interrupt resolution from a custom UI that lives anywhere in the tree
(not necessarily inside a chat), see the
[headless interrupts guide](/agent-spec/human-in-the-loop/headless). It shows
how to compose `useAgent`, `agent.subscribe`, and `copilotkit.runAgent`
to build your own `useInterrupt` equivalent.

<IntegrationGrid path="human-in-the-loop" />
