useCopilotAction
A hook for providing actions the Copilot can call.
![](https://mintlify.s3-us-west-1.amazonaws.com/tawkitai/images/useCopilotAction/use-copilot-action.gif)
![](https://static.scarf.sh/a.png?x-pxid=a9b290bb-38f9-4518-ac3b-8f54fdbf43be)
useCopilotAction
is a React hook that you can use in your application to provide
custom actions that can be called by the AI. Essentially, it allows the Copilot to
execute these actions contextually during a chat, based on the user’s interactions
and needs.
Here’s how it works:
Use useCopilotAction
to set up actions that the Copilot can call. To provide
more context to the Copilot, you can provide it with a description
(for example to explain
what the action does, under which conditions it can be called, etc.).
Then you define the parameters of the action, which can be simple, e.g. primitives like strings or numbers, or complex, e.g. objects or arrays.
Finally, you provide a handler
function that receives the parameters and returns a result.
CopilotKit takes care of automatically inferring the parameter types, so you get type safety
and autocompletion for free.
To render a custom UI for the action, you can provide a render()
function. This function
lets you render a custom component or return a string to display.
Generative UI
By implementing render
and returning a React component, you can provide custom
UI elements that update in real-time as args
are dynamically streamed to the action.
![](https://mintlify.s3-us-west-1.amazonaws.com/tawkitai/images/useCopilotAction/render-generative-spreadsheet.gif)
![](https://mintlify.s3-us-west-1.amazonaws.com/tawkitai/images/useCopilotAction/render-generative-presentation.gif)
For example this shows “Processing…” while the action is executing and “Done!” when it is complete:
{
// ...
render: ({status, args, result}) => (
<div>
{status === "complete" ? "Done!" : "Processing..."}
</div>
),
}
For in-depth examples of custom rendering, see the Spreadsheet and Presentation demos.
Rendering a Dynamic Message
You can also return a string from render
to display a message that updates in real-time as the action is executed.
{
// ...
render: ({ status, args, result }) =>
(status === "complete" ? "☑️ Done!" : "Processing..."),
}
If you want the message to disappear when the action is complete, return a falsy value. Otherwise, return a string to display.
![](https://mintlify.s3-us-west-1.amazonaws.com/tawkitai/images/useCopilotAction/render-dynamic.gif)
Rendering a Waiting Message
Sometimes, you might want to display a simple message to let the user know that the action is
in progress. To do this, provide a string to render
:
{
// ...
render: "Processing...",
}
This will display a spinner and your message while the action is running that disappears when the action is complete.
![](https://mintlify.s3-us-west-1.amazonaws.com/tawkitai/images/useCopilotAction/render-string.gif)
Parameters
The function made available to the Copilot. See Action.
An optional array of dependencies.
Action
The name of the action.
A description of the action. This is used to instruct the Copilot on how to use the action.
The parameters of the action. See Parameter.
The handler of the action.
Render lets you define a custom component or string to render instead of the default. You can either pass in a string or a function that takes the following props:
"inProgress"
: arguments are dynamically streamed to the function, allowing you to adjust your UI in real-time."executing"
: The action handler is executing."complete"
: The action handler has completed execution.
The arguments passed to the action in real time. When the status is "inProgress"
, they are
possibly incomplete.
The result returned by the action. It is only available when the status is "complete"
.
Parameter
The name of the parameter.
The type of the argument.
A description of the argument. This is used to instruct the Copilot on what this argument is used for.
Whether or not the argument is required. Defaults to true.
If the argument is of a complex type, i.e. object
or object[]
, this field
lets you define the attributes of the object. For example:
{
name: "addresses",
description: "The addresses extracted from the text.",
type: "object[]",
attributes: [
{
name: "street",
type: "string",
description: "The street of the address.",
},
{
name: "city",
type: "string",
description: "The city of the address.",
},
// ...
],
}