# 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>
    ### Install the CrewAI AG-UI package

    ```bash
    pip install ag-ui-crewai litellm
    ```

  </Step>
  <Step>
    ### Give `useHumanInTheLoop` tools to the model

    A Flow makes its own model call, so it must pass the tools itself:

    - Type the Flow on `CopilotKitState`. A tool registered with
      `useHumanInTheLoop` arrives in `self.state.copilotkit.actions`.
    - Pass the actions as `tools`, inside `copilotkit_stream`, so the tool call
      reaches the browser as it streams.
    - The run ends when the model calls the tool. After the user answers,
      CopilotKit runs the Flow again with the answer as the last message, with
      `role: "tool"`. Read it in the `@start()` step to decide what happens
      next.

    ```python title="agent.py"
    from typing import Any, cast

    from crewai.flow.flow import Flow, listen, start
    from litellm import acompletion

    from ag_ui_crewai import CopilotKitState, copilotkit_stream


    class AgentState(CopilotKitState):
        pass


    class SampleAgentFlow(Flow[AgentState]):
        @start()
        async def check_for_user_feedback(self):
            if not self.state.messages:
                return

            last_message = cast(Any, self.state.messages[-1])

            # The result of the useHumanInTheLoop tool (SEND or CANCEL)
            if last_message["role"] == "tool":
                if last_message.get("content") == "SEND":
                    self.state.messages.append({
                        "role": "assistant",
                        "content": "✅ Great! Sending your essay via email.",
                    })
                    return

                if last_message.get("content") == "CANCEL":
                    self.state.messages.append({
                        "role": "assistant",
                        "content": "❌ Okay, we can improve the draft. What would you like to change?",
                    })
                    return

        @listen(check_for_user_feedback)
        async def chat(self):
            system_message = {
                "role": "system",
                "content": (
                    "You write essays. Use your tools to write an essay; "
                    "don't just write it in plain text."
                ),
            }

            response = await copilotkit_stream(
                await acompletion(
                    reasoning_effort="none",
                    allowed_openai_params=["reasoning_effort"],
                    model="openai/gpt-6-luna",
                    messages=[system_message, *self.state.messages],
                    tools=self.state.copilotkit.actions,
                    stream=True,
                )
            )

            self.state.messages.append(response.choices[0].message)
    ```

  </Step>
  <Step>
    ### Pause the Flow for `useInterrupt`

    To pause at a fixed step in your code instead, decorate the step with
    CrewAI's `@human_feedback` and the AG-UI feedback provider. The step's
    return value is the interrupt payload. The listening step receives the
    user's answer as a `HumanFeedbackResult`.

    ```python title="src/agents/interrupt_flow.py"
    import json
    from typing import Any

    from crewai.flow import Flow, HumanFeedbackResult, human_feedback, listen, start

    from ag_ui_crewai import CopilotKitState, agui_feedback_provider


    class InterruptFlow(Flow[CopilotKitState]):
        @start()
        @human_feedback(
            message="Choose a meeting time or cancel the request.",
            llm=None,
            provider=agui_feedback_provider,
        )
        async def request_schedule(self) -> dict[str, Any]:
            # ... call the model, then return what the picker needs:
            return {"topic": topic, "attendee": attendee, "slots": slots}

        @listen("request_schedule")
        async def confirm_schedule(self, result: HumanFeedbackResult) -> None:
            feedback_text = result.feedback or ""
            # A cancelled interrupt resumes with an empty feedback string.
            cancelled = not feedback_text.strip()
            feedback = {} if cancelled else json.loads(feedback_text)
    ```

    Register the endpoint so it emits standard AG-UI interrupts:

    ```python title="src/agent_server.py"
    add_crewai_flow_fastapi_endpoint(
        app,
        interrupt_flow,
        "/interrupt",
        emit_interrupt_outcome=True,
        enable_legacy_on_interrupt_event=False,
    )
    ```

    For a Conversational Flow, pass these
    two flags in addition to `conversational=True`. On the frontend, read the
    payload from `interrupt.metadata.crewai.output`. See
    `src/agents/interrupt_flow.py` for the full Flow.

  </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" />
