useFrontendTool

This is the v1 useFrontendTool, which takes an array of parameter definitions. It is still supported, but we recommend migrating to the v2 useFrontendTool (from @copilotkit/react-core/v2), which uses Zod schemas for parameters.

useFrontendTool allows you to define executable actions that the AI can call with a handler function. This is the primary way to give your AI agent the ability to perform actions in your application, whether that's updating state, making API calls, or triggering side effects.

The hook requires three main pieces:

A name and description so the AI knows when to call it
A parameters definition describing what inputs the tool accepts
A handler function that executes when the AI calls the tool

Optionally, you can provide a render function to display custom UI showing the tool's execution status and results in the chat interface.

Usage

Simple Usage

import { useFrontendTool } from "@copilotkit/react-core";

useFrontendTool({
  name: "sayHello",
  description: "Say hello to someone.",
  parameters: [
    {
      name: "name",
      type: "string",
      description: "name of the person to greet",
      required: true,
    },
  ],
  handler: async ({ name }) => {
    alert(`Hello, ${name}!`);
  },
});

With Custom UI Rendering

import { useFrontendTool } from "@copilotkit/react-core";

useFrontendTool({
  name: "showWeatherCard",
  description: "Display weather information for a location",
  parameters: [
    {
      name: "location",
      type: "string",
      description: "The location to show weather for",
      required: true,
    },
    {
      name: "temperature",
      type: "number",
      description: "Temperature in celsius",
      required: true,
    },
  ],
  handler: async ({ location, temperature }) => {
    // Fetch and return weather data
    return { location, temperature, conditions: "Sunny" };
  },
  render: ({ args, status, result }) => {
    if (status === "inProgress") {
      return <div>Loading weather for {args.location}...</div>;
    }
    if (status === "complete" && result) {
      return (
        <WeatherCard
          location={result.location}
          temperature={result.temperature}
          conditions={result.conditions}
        />
      );
    }
    return null;
  },
});

Generative UI

This hook enables you to dynamically generate UI elements and render them in the copilot chat. For more information, check out the Generative UI page.

Migration from useCopilotAction

If you're migrating from useCopilotAction, here are the key differences:

The render component props include name and description

Migration Example

// Before with useCopilotAction
useCopilotAction({
  name: "addTodo",
  parameters: [
    {
      name: "text",
      type: "string",
      description: "The todo text",
      required: true,
    },
  ],
  handler: ({ text }) => {
    addTodo(text);
  },
});

// After with useFrontendTool
useFrontendTool({
  name: "addTodo",
  parameters: [
    {
      name: "text",
      type: "string",
      description: "The todo text",
      required: true,
    },
  ],
  handler: ({ text }) => {
    addTodo(text);
  },
});

Parameters

Prop

Type

Prop

Type

Prop

Type

Prop

Type

Prop

Type

Prop

Type

Prop

Type