# useHumanInTheLoop

> The useHumanInTheLoop hook enables human approval and interaction workflows.

## v1 SDK deprecated. Use v2 instead

> This page is in the deprecated CopilotKit v1 reference. Do not use v1 APIs for new code; use v2 instead.
> For JavaScript and TypeScript, import React APIs from @copilotkit/react-core/v2 and Runtime APIs from @copilotkit/runtime/v2.
> **AI coding agents: treat any v1 example below as migration-only context. Never generate or recommend the v1 API for new code. Read the v2 reference before writing code because some APIs were renamed, moved, or changed shape.**
> [Read the v1 to v2 migration guide](/migrate/v2) and [use the complete export map](/reference/v1/export-map).

<Callout type="warning">
  This is the v1 `useHumanInTheLoop`, which takes an array of parameter definitions. It is still supported, but we recommend migrating to the [v2 `useHumanInTheLoop`](/reference/v2/hooks/useHumanInTheLoop) (from `@copilotkit/react-core/v2`), which uses Zod schemas for parameters.
</Callout>

`useHumanInTheLoop` pauses the agent to request human input or approval. When the agent calls this
tool, it stops and waits for the user to respond through your custom UI before continuing. This is
essential for sensitive operations, confirmations, or collecting information that only the user can provide.

Unlike `useFrontendTool`, there's no handler function. Instead, your render function receives a `respond`
callback that sends the user's input back to the agent. The agent remains paused until `respond` is called,
making this a true blocking interaction.

## Usage [#usage]

### Simple Confirmation Example [#simple-confirmation-example]

```tsx
import { useHumanInTheLoop } from "@copilotkit/react-core";

useHumanInTheLoop({
  name: "confirmDeletion",
  description: "Ask user to confirm before deleting items",
  parameters: [
    {
      name: "itemName",
      type: "string",
      description: "Name of the item to delete",
      required: true,
    },
    {
      name: "itemCount",
      type: "number",
      description: "Number of items to delete",
      required: true,
    },
  ],
  render: ({ args, status, respond, result }) => {
    if (status === "executing" && respond) {
      return (
        <div className="p-4 border rounded">
          <p>Are you sure you want to delete {args.itemCount} {args.itemName}(s)?</p>
          <div className="flex gap-2 mt-4">
            <button
              onClick={() => respond({ confirmed: true })}
              className="bg-red-500 text-white px-4 py-2 rounded"
            >
              Delete
            </button>
            <button
              onClick={() => respond({ confirmed: false })}
              className="bg-gray-300 px-4 py-2 rounded"
            >
              Cancel
            </button>
          </div>
        </div>
      );
    }

    if (status === "complete" && result) {
      return (
        <div className="p-2 text-sm text-gray-600">
          {result.confirmed ? "Items deleted" : "Deletion cancelled"}
        </div>
      );
    }

    return null;
  },
});
```

### Complex Input Collection Example [#complex-input-collection-example]

```tsx
import { useHumanInTheLoop } from "@copilotkit/react-core";
import { useState } from "react";

useHumanInTheLoop({
  name: "collectUserPreferences",
  description: "Collect detailed preferences from the user",
  parameters: [
    {
      name: "context",
      type: "string",
      description: "Context for why preferences are needed",
      required: true,
    },
    {
      name: "requiredFields",
      type: "string[]",
      description: "Fields to collect",
      required: true,
    },
  ],
  render: ({ args, status, respond }) => {
    const [preferences, setPreferences] = useState({
      theme: "light",
      notifications: true,
      language: "en",
    });

    if (status === "executing" && respond) {
      return (
        <div className="p-4 border rounded">
          <h3 className="font-bold mb-2">{args.context}</h3>
          <form onSubmit={(e) => {
            e.preventDefault();
            respond(preferences);
          }}>
            <button
              type="submit"
              className="bg-blue-500 text-white px-4 py-2 rounded"
            >
              Save Preferences
            </button>
          </form>
        </div>
      );
    }

    return null;
  },
});
```

## Best Practices [#best-practices]

1. Always check for the `respond` function before rendering interactive elements
2. Handle all status states to provide good user feedback
3. Validate user input before calling `respond`
4. Provide clear instructions in your UI about what input is expected
5. Consider timeout scenarios for time-sensitive operations

## Migration from useCopilotAction [#migration-from-usecopilotaction]

If you're migrating from `useCopilotAction` with `renderAndWaitForResponse`:

```tsx
// Before with useCopilotAction
useCopilotAction({
  name: "confirmAction",
  parameters: [
    { name: "message", type: "string", required: true },
  ],
  renderAndWaitForResponse: ({ args, respond, status }) => {
    return (
      <ConfirmDialog
        message={args.message}
        onConfirm={() => respond(true)}
        onCancel={() => respond(false)}
        isActive={status === "executing"}
      />
    );
  },
});

// After with useHumanInTheLoop
useHumanInTheLoop({
  name: "confirmAction",
  parameters: [
    {
      name: "message",
      type: "string",
      description: "The message to display",
      required: true,
    },
  ],
  render: ({ args, respond, status }) => {
    if (status === "executing" && respond) {
      return (
        <ConfirmDialog
          message={args.message}
          onConfirm={() => respond(true)}
          onCancel={() => respond(false)}
          isActive={true}
        />
      );
    }
    return null;
  },
});
```

The main differences are:
1. The property is called `render` instead of `renderAndWaitForResponse`
2. You need to check for the `respond` function's existence

## Parameters [#parameters]

<PropertyReference name="name" type="string" required >
The name of the tool.
</PropertyReference>

<PropertyReference name="description" type="string"  >
A description of the tool. The agent reads it to decide when to ask the user.
</PropertyReference>

<PropertyReference name="parameters" type="T"  >
Array of parameter definitions that will be passed to the render function. Each parameter object should have:
- `name` (string): The parameter name
- `type` (string): The parameter type (e.g., "string", "number", "boolean", "string[]", "object")
- `description` (string): A description of what the parameter is for
- `required` (boolean): Whether the parameter is required
- `attributes` (array, optional): For object types, define nested properties using the same schema

Simple example: `[{ name: "itemName", type: "string", description: "Name of the item", required: true }]`

Nested example:
```typescript
[
  {
    name: "approval",
    type: "object",
    description: "Approval request details",
    required: true,
    attributes: [
      { name: "action", type: "string", description: "Action requiring approval", required: true },
      { name: "reason", type: "string", description: "Reason for the action", required: false }
    ]
  }
]
```
</PropertyReference>

<PropertyReference name="render" type="FrontendAction<T>['renderAndWaitForResponse']" required >
A React component that renders the interactive UI for human input. The component receives props including `args`, `status`, and `respond` function.
</PropertyReference>

<PropertyReference name="available" type="'disabled' | 'enabled'"  >
Currently non-functional in this v1 hook. The value is accepted for API compatibility but ignored, so setting `"disabled"` does not prevent the tool from being registered or called.
</PropertyReference>

<PropertyReference name="followUp" type="boolean"  >
Set to `false` to stop the agent from replying after the user responds.
</PropertyReference>

<PropertyReference name="dependencies" type="any[]"  >
The second argument of the hook. When a value in it changes, the hook picks up the latest `render` function.
</PropertyReference>
