useHumanInTheLoop - Copilotkit

<Callout type="warning"> `useHumanInTheLoop` is still supported, but we recommend migrating to [`useHumanInTheLoop`](/reference/v2/hooks/useHumanInTheLoop) from the v2 API. </Callout>

useHumanInTheLoop pauses AI execution to request human input or approval. When the AI 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 AI. The AI execution remains paused until respond is called, making this a true blocking interaction.

Usage

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

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

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

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:

The property is called render instead of renderAndWaitForResponse
You need to check for the respond function's existence

Parameters

<PropertyReference name="name" type="string" required > The name of the tool. </PropertyReference> <PropertyReference name="description" type="string" > A description of the tool. This is used to instruct the Copilot on when to request human input. </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 - `properties` (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,
    properties: [
      { 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'" > Whether the tool is available. Set to "disabled" to prevent the tool from being called. </PropertyReference>