useFrontendTool
The useFrontendTool hook allows the Copilot to execute tools in the frontend.
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
The name of the tool.
A description of the tool. This is used to instruct the Copilot on how to use the tool.
Array of parameter definitions for the tool. Each parameter object should have:
name(string): The parameter nametype(string): The parameter type (e.g., "string", "number", "boolean", "string[]", "object")description(string): A description of what the parameter is forrequired(boolean): Whether the parameter is requiredproperties(array, optional): For object types, define nested properties using the same schema
Simple example: [{ name: "query", type: "string", description: "The search query", required: true }]
Nested example:
[
{
name: "user",
type: "object",
description: "User information",
required: true,
properties: [
{ name: "name", type: "string", description: "User's name", required: true },
{ name: "age", type: "number", description: "User's age", required: false }
]
}
]The handler function that executes the tool logic.
Whether to report the result of the tool call to the LLM which will then provide a follow-up response. Pass false to disable.
A React component that renders custom UI for the tool.
Whether the tool is available. Set to "disabled" to prevent the tool from being called.
