useCopilotAction

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.

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

​

Action

​

Parameter

{
  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.",
    },
    // ...
  ],
}