useCopilotAction.mdx

title	useCopilotAction
description	A hook for providing actions the Copilot can call.

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.

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

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.

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.

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.

Parameters

The function made available to the Copilot. See [Action](#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](#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:

<ResponseField name="status" type="'inProgress' | 'executing' | 'complete'">
  - `"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.
</ResponseField>

<ResponseField name="args" type="T">
  The arguments passed to the action in real time. When the status is `"inProgress"`, they are
  possibly incomplete.
</ResponseField>

<ResponseField name="result" type="any">
  The result returned by the action. It is only available when the status is `"complete"`.
</ResponseField>

Parameter

The name of the parameter.

<ResponseField name="type" type="'string' | 'number' | 'boolean' | 'object' | 'string[]' | 'number[]' | 'boolean[]' | 'object[]'" required

The type of the argument.

A description of the argument. This is used to instruct the Copilot on what this argument is used for. Wether 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: ```js { 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.", }, // ... ], } ````