Tool-based

Implement HITL with Mastra using frontend tools that render UI and collect user input.

What is this?#

CopilotKit lets you add custom UI to take user input and then pass it back to the agent upon completion. This approach uses useHumanInTheLoop to register a frontend tool that renders a UI component and waits for the user's response.

Looking for an approach where tools can pause mid-execution and wait for user input? See the interrupt-based approach.

Why should I use this?#

Human-in-the-loop is a powerful way to implement complex workflows that are production ready. By having a human in the loop, you can ensure that the agent is always making the right decisions and ultimately is being steered in the right direction.

Implementation#

Run and connect your agent#

You'll need to run your agent and connect it to CopilotKit before proceeding. If you haven't done so already, you can follow the instructions in the Getting Started guide.

If you don't already have an agent, you can use the coagent starter as a starting point as this guide uses it as a starting point.

Add a human-in-the-loop tool to your Frontend#

First, we'll create a component that offers the user options and waits for their selection.

ui/app/page.tsx

import { useHumanInTheLoop } from "@copilotkit/react-core/v2"

function YourMainContent() {
  // ...

  useHumanInTheLoop({
    name: "offerOptions",
    description: "Give the user a choice between two options and have them select one.",
    parameters: [
      {
        name: "option_1",
        type: "string",
        description: "The first option",
        required: true,
      },
      {
        name: "option_2",
        type: "string",
        description: "The second option",
        required: true,
      },
    ],
    render: ({ args, respond }) => {
      if (!respond) return <></>;
      return (
        <div>
          <button onClick={() => respond(`${args.option_1} was selected`)}>{args.option_1}</button>
          <button onClick={() => respond(`${args.option_2} was selected`)}>{args.option_2}</button>
        </div>
      );
    },
  });

  // ...
}

Setup the Mastra Agent#

On the agent side, we are already done! Mastra natively supports the AG-UI protocol and will automatically pass control back to the frontend when the offerOptions tool is called by the agent.

Give it a try!#

Try asking your agent something that requires a choice.

Can you show me two good options for a restaurant name?"

You'll see that the agent will present two options and wait for you to select one before continuing.