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}!`);
    },
  }
);

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.

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

action
Action
required

The function made available to the Copilot. See Action.

dependencies
any[]

An optional array of dependencies.

Action

name
string
required

The name of the action.

description
string

A description of the action. This is used to instruct the Copilot on how to use the action.

parameters
Parameter[]

The parameters of the action. See Parameter.

handler
(args) => Promise<any>
required

The handler of the action.

render
string | (props: ActionRenderProps<T>) => string

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:

status
'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.
args
T

The arguments passed to the action in real time. When the status is "inProgress", they are possibly incomplete.

result
any

The result returned by the action. It is only available when the status is "complete".

Parameter

name
string
required

The name of the parameter.

type
'string' | 'number' | 'boolean' | 'object' | 'string[]' | 'number[]' | 'boolean[]' | 'object[]'
required

The type of the argument.

description
string

A description of the argument. This is used to instruct the Copilot on what this argument is used for.

required
boolean

Wether or not the argument is required. Defaults to true.

attributes

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