# useHumanInTheLoop

> Vue 3 composable for interactive tools that pause agent execution and wait for user input

## Overview [#overview]

`useHumanInTheLoop` registers an interactive frontend tool that pauses agent execution until the user responds through your custom UI. Unlike [`useFrontendTool`](/reference/vue/hooks/useFrontendTool), you do not supply a `handler`. Instead, the composable manages an internal status machine (`InProgress` -> `Executing` -> `Complete`) and passes a `respond` callback to your render component while the tool is in the `executing` phase. The agent stays paused until `respond` is called with the user's input.

Internally the composable wraps `useFrontendTool`. The composable generates a handler that returns a promise. The composable keeps the `resolve` function of that promise. When your UI calls `respond`, the promise resolves, the result goes to the agent, and the run continues. Use it for confirmation dialogs, approval workflows, form collection, or any scenario where a human must provide input before the agent can continue.

<Callout type="info">
  `useHumanInTheLoop` must be called within a component that has access to the
  CopilotKit instance provided by [`CopilotKitProvider`](/reference/vue/components/CopilotKitProvider). Like all Vue
  composables, call it synchronously inside `<script setup>` or a `setup()`
  function so its reactive scope is bound to the component lifecycle. The tool
  is unregistered automatically on scope cleanup.
</Callout>

## Signature [#signature]

```ts
import { useHumanInTheLoop } from "@copilotkit/vue/v2";

function useHumanInTheLoop<T extends Record<string, unknown>>(
  tool: VueHumanInTheLoop<T>,
  deps?: WatchSource<unknown>[],
): void;
```

## Parameters [#parameters]

<PropertyReference name="tool" type="VueHumanInTheLoop<T>" required>
  The interactive tool definition. It accepts the same fields as a frontend
  tool except `handler` (which is managed internally), plus a required `render`
  component.

<PropertyReference name="name" type="string" required>
  A unique name for the tool. The agent references this name when it needs human
  input.
</PropertyReference>

<PropertyReference name="description" type="string">
  A natural-language description that tells the agent what the tool does and
  when to call it (e.g., "Ask the user to confirm before deleting records").
</PropertyReference>

<PropertyReference name="parameters" type="StandardSchemaV1 (e.g. z.ZodSchema)">
  A schema (typically a Zod schema) defining the arguments the agent passes to
  the tool. These arguments are forwarded to the render component as the `args`
  prop so you can build context-aware UI.
</PropertyReference>

  <PropertyReference name="render" type="VueHumanInTheLoopRenderFn<T>" required>
    A Vue component (or render function) that drives the human interaction. It receives the following props, whose shape depends on the current `status`:

    **Always present:**
    - `name: string` -- the tool name
    - `description: string` -- the tool description (an empty string when the tool defines none)
    - `toolCallId: string` -- the unique id of this tool call
    - `agentId?: string` -- the `agentId` of the tool, when the tool has one
    - `status: ToolCallStatus` -- the current phase (`"inProgress"`, `"executing"`, or `"complete"`)

    **When `status` is `ToolCallStatus.InProgress` (`"inProgress"`):**
    - `args: Partial<T>` -- partially streamed arguments
    - `result: undefined`
    - `respond: undefined` -- not yet available

    **When `status` is `ToolCallStatus.Executing` (`"executing"`):**
    - `args: T` -- fully resolved arguments
    - `result: undefined`
    - `respond: (result: unknown) => Promise<void>` -- call this to send the user's response back to the agent and resume execution

    **When `status` is `ToolCallStatus.Complete` (`"complete"`):**
    - `args: T` -- the original arguments
    - `result: string` -- the serialized result
    - `respond: undefined` -- no longer available

  </PropertyReference>

  <PropertyReference name="available" type="boolean" default="true">
    Whether the tool is available to the agent. Set to `false` to hide the tool from the agent without unregistering it.
  </PropertyReference>

  <PropertyReference name="agentId" type="string">
    Optional agent ID to constrain this tool to a specific agent. If specified, the tool is only available to that agent.
  </PropertyReference>

  <PropertyReference name="followUp" type="boolean">
    Whether the agent should automatically follow up after the tool responds.
  </PropertyReference>
</PropertyReference>

<PropertyReference name="deps" type="WatchSource<unknown>[]">
  An optional array of reactive watch sources (refs, getters, etc.). When
  provided, the tool registration is refreshed whenever any source changes.
</PropertyReference>

## Usage [#usage]

Define the render component as a separate Vue SFC, then register it with `useHumanInTheLoop`. The component receives `status`, `args`, `respond`, `name`, and `description` as props.

### Confirmation Dialog [#confirmation-dialog]

A common pattern where the agent asks the user to confirm a destructive action.

`ConfirmDeletion.vue` (the render component):

```vue
<script setup lang="ts">
import { ToolCallStatus } from "@copilotkit/vue/v2";

defineProps<{
  status: ToolCallStatus;
  args: { itemName?: string; itemCount?: number };
  name: string;
  description: string;
  result?: string;
  respond?: (result: unknown) => Promise<void>;
}>();
</script>

<template>
  <div v-if="status === ToolCallStatus.InProgress" class="p-4 text-gray-500">
    Preparing confirmation...
  </div>

  <div
    v-else-if="status === ToolCallStatus.Executing && respond"
    class="p-4 border rounded"
  >
    <p>Are you sure you want to delete {{ args.itemCount }} {{ args.itemName }}(s)?</p>
    <div class="flex gap-2 mt-4">
      <button
        class="bg-red-500 text-white px-4 py-2 rounded"
        @click="respond({ confirmed: true })"
      >
        Delete
      </button>
      <button
        class="bg-gray-300 px-4 py-2 rounded"
        @click="respond({ confirmed: false })"
      >
        Cancel
      </button>
    </div>
  </div>

  <div
    v-else-if="status === ToolCallStatus.Complete && result"
    class="p-2 text-sm text-gray-600"
  >
    {{ JSON.parse(result).confirmed ? "Items deleted." : "Deletion cancelled." }}
  </div>
</template>
```

Register it from a component in scope of `CopilotKitProvider`:

```vue
<script setup lang="ts">
import { useHumanInTheLoop } from "@copilotkit/vue/v2";
import { z } from "zod";
import ConfirmDeletion from "./ConfirmDeletion.vue";

useHumanInTheLoop({
  name: "confirmDeletion",
  description: "Ask the user to confirm before deleting items",
  parameters: z.object({
    itemName: z.string().describe("Name of the item to delete"),
    itemCount: z.number().describe("Number of items to delete"),
  }),
  render: ConfirmDeletion,
});
</script>

<template>
  <!-- nothing to render here; the tool UI is shown in the chat -->
</template>
```

### Form Input Collection [#form-input-collection]

Collect structured input from the user before the agent proceeds. Local form state lives in the render component using `ref`.

`ShippingAddressForm.vue`:

```vue
<script setup lang="ts">
import { ref } from "vue";
import { ToolCallStatus } from "@copilotkit/vue/v2";

defineProps<{
  status: ToolCallStatus;
  args: { orderSummary?: string };
  name: string;
  description: string;
  result?: string;
  respond?: (result: unknown) => Promise<void>;
}>();

const address = ref({ street: "", city: "", zip: "" });
</script>

<template>
  <div
    v-if="status === ToolCallStatus.Executing && respond"
    class="p-4 border rounded space-y-3"
  >
    <p class="font-medium">Order: {{ args.orderSummary }}</p>
    <p>Please enter your shipping address:</p>
    <input
      v-model="address.street"
      placeholder="Street address"
      class="w-full border p-2 rounded"
    />
    <input
      v-model="address.city"
      placeholder="City"
      class="w-full border p-2 rounded"
    />
    <input
      v-model="address.zip"
      placeholder="ZIP code"
      class="w-full border p-2 rounded"
    />
    <button
      class="bg-blue-500 text-white px-4 py-2 rounded"
      @click="respond({ ...address })"
    >
      Submit Address
    </button>
  </div>

  <div v-else-if="status === ToolCallStatus.Complete" class="p-2 text-green-600">
    Shipping address submitted.
  </div>
</template>
```

Registration:

```vue
<script setup lang="ts">
import { useHumanInTheLoop } from "@copilotkit/vue/v2";
import { z } from "zod";
import ShippingAddressForm from "./ShippingAddressForm.vue";

useHumanInTheLoop({
  name: "collectShippingAddress",
  description: "Collect shipping address from the user before placing an order",
  parameters: z.object({
    orderSummary: z.string().describe("A summary of the order being placed"),
  }),
  render: ShippingAddressForm,
});
</script>

<template>
  <!-- tool UI renders inside the chat -->
</template>
```

### Approval Workflow with Context [#approval-workflow-with-context]

`ExpenseApproval.vue`:

```vue
<script setup lang="ts">
import { ToolCallStatus } from "@copilotkit/vue/v2";

defineProps<{
  status: ToolCallStatus;
  args: {
    employeeName?: string;
    amount?: number;
    category?: string;
    description?: string;
  };
  name: string;
  description: string;
  result?: string;
  respond?: (result: unknown) => Promise<void>;
}>();
</script>

<template>
  <div
    v-if="status === ToolCallStatus.Executing && respond"
    class="p-4 border rounded"
  >
    <h3 class="font-bold">Expense Approval Required</h3>
    <div class="mt-2 space-y-1 text-sm">
      <p>Employee: {{ args.employeeName }}</p>
      <p>Amount: ${{ args.amount?.toFixed(2) }}</p>
      <p>Category: {{ args.category }}</p>
      <p>Description: {{ args.description }}</p>
    </div>
    <div class="flex gap-2 mt-4">
      <button
        class="bg-green-500 text-white px-4 py-2 rounded"
        @click="respond({ approved: true })"
      >
        Approve
      </button>
      <button
        class="bg-red-500 text-white px-4 py-2 rounded"
        @click="respond({ approved: false, reason: 'Needs more detail' })"
      >
        Reject
      </button>
    </div>
  </div>

  <div
    v-else-if="status === ToolCallStatus.Complete && result"
    class="p-2 text-sm"
    :class="JSON.parse(result).approved ? 'text-green-600' : 'text-red-600'"
  >
    {{
      JSON.parse(result).approved
        ? "Expense approved."
        : `Expense rejected: ${JSON.parse(result).reason}`
    }}
  </div>
</template>
```

Registration:

```vue
<script setup lang="ts">
import { useHumanInTheLoop } from "@copilotkit/vue/v2";
import { z } from "zod";
import ExpenseApproval from "./ExpenseApproval.vue";

useHumanInTheLoop({
  name: "approveExpense",
  description: "Request manager approval for an expense report",
  parameters: z.object({
    employeeName: z.string().describe("Name of the employee"),
    amount: z.number().describe("Expense amount in dollars"),
    category: z.string().describe("Expense category"),
    description: z.string().describe("Description of the expense"),
  }),
  render: ExpenseApproval,
});
</script>

<template>
  <!-- tool UI renders inside the chat -->
</template>
```

## Behavior [#behavior]

- **Blocks agent execution**: The internally generated handler returns a promise that does not resolve until `respond` is called, so the agent pauses on this tool call and waits for the user.
- **Internal status machine**: The composable drives three phases - `inProgress` (arguments streaming in), `executing` (waiting for the user, `respond` available), and `complete` (user has responded, `result` available). Your render component receives the appropriate props for each phase.
- **`respond` is only passed during `executing`**: In the `inProgress` and `complete` phases, `respond` is `undefined`. Guard on `status === ToolCallStatus.Executing && respond` before calling it.
- **Single response**: Calling `respond` resolves the pending promise once and clears the stored resolver, so subsequent calls are no-ops for that tool call.
- **Stop while waiting**: If the user stops the agent while the tool waits, the pending call rejects with `Human-in-the-loop interaction aborted`. A later `respond` call does nothing.
- **Built on `useFrontendTool`**: The composable forwards a `VueFrontendTool` (your tool plus the generated `handler` and a wrapping render component) to `useFrontendTool`, so the same registration lifecycle applies.
- **Scope lifecycle**: The tool and its render component are registered while the composable's reactive scope is active and removed automatically on scope cleanup: the render component via `onScopeDispose`, and the tool via the underlying `useFrontendTool` watch's cleanup.
- **Calls after cleanup**: If the agent calls the tool after it was removed (for example, the owning scope was disposed while the run was in flight), CopilotKit answers the call with a `Tool not found` error result and reports a `TOOL_NOT_FOUND` error, so the conversation can continue. This applies only to tools that were sent to the agent for that run, and only when the run finishes normally; an interrupted, stopped or failed run leaves the call open. A call to a name that was not sent to the agent for that run stays unanswered; register a wildcard tool (`name: "*"`) to handle those.
- **No return value**: The composable returns `void`.

## ToolCallStatus [#toolcallstatus]

The `ToolCallStatus` enum is exported from `@copilotkit/vue/v2` and defines the three phases of tool execution. Its string values are what appear in the render component's `status` prop.

| Value                       | String value   | Description                                                                              |
| --------------------------- | -------------- | ---------------------------------------------------------------------------------------- |
| `ToolCallStatus.InProgress` | `"inProgress"` | Arguments are being streamed from the agent. The tool has not started executing yet.     |
| `ToolCallStatus.Executing`  | `"executing"`  | Arguments are fully resolved. For `useHumanInTheLoop`, the `respond` callback is passed.  |
| `ToolCallStatus.Complete`   | `"complete"`   | Execution is finished. The `result` string is available.                                 |
