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 lets you define executable actions that the agent can call with a handler function.
This is the primary way to give your agent the ability to perform actions in your application, whether
that's updating state, making API calls, or triggering side effects.
The hook takes three main pieces. Only the name is required:
- A name and description so the agent knows when to call it
- A parameters definition describing what inputs the tool accepts
- A handler function that executes when the agent 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 lets you 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 are migrating from useCopilotAction with a handler, change the hook name. The options and the render props stay the same.
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
How is this guide?