useFrontendTool
The useFrontendTool hook allows the Copilot to execute tools in the frontend.
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. Open the complete export map.
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
nameanddescription
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