# HITL Overview

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

## 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 information**: the agent asks the user for a value it cannot find.
- **Expert input**: the user supplies domain knowledge the model lacks.

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

<Steps>
  <Step>
    ### `useHumanInTheLoop`: no frontend-tool code on the agent

    `AGUIStream` turns every tool the client declares into a client-side tool,
    so a tool you register with `useHumanInTheLoop` reaches the model through
    the AG-UI request. Do not declare it on the AG2 agent. Name it in the
    agent's `prompt` so the model calls it.

    To keep the user's answer, have a backend tool write it to
    `context.variables`. When a tool changes the variables, `AGUIStream` sends
    a `STATE_SNAPSHOT` at the end of the run:

    ```python title="agent.py"
    from typing import Annotated

    from fastapi import FastAPI, Header
    from fastapi.responses import StreamingResponse
    from pydantic import Field

    from ag2 import Agent, Context, tool
    from ag2.ag_ui import AGUIStream, RunAgentInput
    from ag2.config import OpenAIResponsesConfig

    @tool
    def store_user_choice(
        choice: Annotated[str, Field(description="The option selected by the user")],
        context: Context,
    ) -> str:
        """Store the latest user choice in shared state."""
        context.variables["hitl"] = {"latest_choice": choice}
        return f"Stored choice: {choice}"

    agent = Agent(
        name="assistant",
        prompt=(
            "When you need the user to choose, call the frontend tool `offerOptions`. "
            "After it returns, call `store_user_choice` with the selected value."
        ),
        config=OpenAIResponsesConfig(model="gpt-6-luna"),
        tools=[store_user_choice],
    )

    stream = AGUIStream(agent)
    app = FastAPI()

    @app.post("/chat")
    async def run_agent(
        message: RunAgentInput,
        accept: str | None = Header(None),
    ) -> StreamingResponse:
        return StreamingResponse(
            stream.dispatch(message, accept=accept),
            media_type=accept or "text/event-stream",
        )
    ```

  </Step>
  <Step>
    ### Approve a tool call with interrupts

    AG2 can also pause a run on the **backend**. A tool wrapped in
    `ApprovalRequired` is held until the user approves or rejects the call.
    AG2 sends the held call to the client as an AG-UI interrupt, and
    CopilotKit's `useInterrupt` renders it.

    ```python title="tools.py"
    from typing import Annotated

    from pydantic import Field

    from ag2 import Context, tool
    from ag2.middleware.builtin.tools.approval import ApprovalRequired

    @tool(
        description="Save a city to the user's favorites. The user confirms before anything is saved.",
        middleware=[
            ApprovalRequired("Save this city to your favorites?\n{tool_arguments}", allow_always=False)
        ],
    )
    async def save_favorite_city(
        context: Context,
        city: Annotated[str, Field(description="The city name to save, e.g. 'Lisbon'")],
    ) -> list[str]:
        favorites = list(context.variables.get("favorites", []))
        if city not in favorites:
            favorites.append(city)
        context.variables["favorites"] = favorites
        return favorites
    ```

    Serve the agent with `AGUIStream` as usual. Do not set a `hitl_hook` on
    the agent. With one, AG2 asks in-process and no interrupt reaches the
    browser.

    The run ends with an interrupt of reason `tool_call`. The backend reads the
    answer as a boolean, so `resolve(true)` approves the call and
    `resolve(false)` refuses it. A refusal does not fail the run: the model is
    told the call was refused and carries on.

    ```tsx title="page.tsx"
    import { useInterrupt } from "@copilotkit/react-core/v2";

    export function Page() {
      useInterrupt({
        render: ({ interrupt, resolve }) => (
          <div>
            <p>{interrupt?.message ?? "The assistant needs your confirmation."}</p>
            <button onClick={() => resolve(true)}>Approve</button>
            <button onClick={() => resolve(false)}>Reject</button>
          </div>
        ),
      });

      // ...
    }
    ```

    Ask `Save Lisbon to my favorites`. The approval card appears in the chat.
    Approve it, and the city shows up in the shared state.

    <Callout type="warn">
      `useInterrupt().resolve()` and `.cancel()` send no `metadata` in the
      resume entry. That is enough for a gated tool call like the one above,
      but not for an AG2 server built with `require_resume_proof=True`, which
      needs the interrupt's `metadata` copied into the resume entry. See
      <a href="https://docs.ag2.ai/docs/user-guide/ag-ui/overview#asking-the-human-a-question" target="_blank">Asking the human a question</a>
      in the AG2 docs.
    </Callout>

    A held turn lives in the AG2 process that served the run, so the resuming
    run must reach that same process. See
    <a href="https://docs.ag2.ai/docs/user-guide/ag-ui/overview#deployment-a-held-turn-lives-in-one-process" target="_blank">the AG2 deployment notes</a>
    before you run several replicas.

  </Step>
</Steps>

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 the agent emits, for example `interrupt()` in a LangGraph node |

**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.

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

The app registers a HITL tool on the client with `useHumanInTheLoop`. When the LLM calls that tool, CopilotKit renders your Vue component and gives it a `respond` callback during the executing phase. The agent sees the answer as the tool result and continues from there.

```vue title="src/components/MeetingApproval.vue"
<script setup lang="ts">
import { z } from "zod";
import { useHumanInTheLoop } from "@copilotkit/vue/v2";
import TimePickerCard from "./TimePickerCard.vue";

useHumanInTheLoop({
  name: "schedule_meeting",
  description: "Ask the user to select a meeting time.",
  parameters: z.object({
    topic: z.string(),
    attendee: z.string(),
  }),
  render: TimePickerCard,
});
</script>

<template><p>Meeting approval tool registered.</p></template>
```

`TimePickerCard.vue` receives the tool arguments and a `respond` callback. `respond` is defined only while the tool call is executing:

```vue title="src/components/TimePickerCard.vue"
<script setup lang="ts">
const props = defineProps<{
  args: { topic?: string; attendee?: string };
  respond?: (result: unknown) => Promise<void>;
}>();
</script>

<template>
  <section>
    <p>Pick a time for {{ props.args.topic ?? "the meeting" }}</p>
    <button
      :disabled="!props.respond"
      @click="props.respond?.({ chosen_time: '09:00' })"
    >
      Tomorrow at 09:00
    </button>
  </section>
</template>
```

The picker UI can use static candidate slots, live availability, a calendar API, or any other application data. Mount the registration component beneath `CopilotKitProvider` so the composable can reach the runtime.

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

With a runtime interrupt, your agent code enforces the pause:

1. The agent interrupts with a serializable payload.
2. The run stops.
3. The client renders your UI with the payload.
4. The user answers, and the client resumes the run with the answer.

CopilotKit's `useInterrupt` composable and `CopilotChat`'s `#interrupt` slot form the Vue render contract.

See the [`useInterrupt` deep dive](/vue/human-in-the-loop/useInterrupt) for the full walkthrough, including the backend contract and Vue slot wiring.

## Going headless [#going-headless]

Both patterns above can drive custom UI. For runtime interrupts, set `renderInChat: false` and use the reactive state returned by `useInterrupt`; for a frontend-tool pause, let the Promise-returning HITL tool drive application state. See the [headless interrupts guide](/vue/human-in-the-loop/headless) for the interrupt path.

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