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 lets you integrate actionable functions in the Copilot chat. The Copilot can then call these actions to trigger actions in your application, allowing for interactive and dynamic behavior controlled by the Copilot.

You can define actions with parameters of any complexity. CopilotKit will relay these definitions to the LLM and subsequently invoke your action handler with the parameters you’ve defined.

In addition, the types of all parameters in your action handler are automatically inferred from the action definition. This enables the use of TypeScript for ensuring type safety and enabling autocompletion in your action handlers.

useCopilotAction takes an optional render() function that lets you render a custom component or string instead of the default message component.

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
function | string

Render lets you define a custom component or string to render instead of the default.

In the simplest case, you can provide a string to render a text message.

{
  // ...
  render: "Hello, world!",
}

You can also provide a function to dynamically set the content of the message.

{
  // ...
  render: ({status, args, result}) => status === "complete" ? "Done!" : "Processing...",
}

In this case, status is the execution status of the action, args are the possibly incomplete, streaming arguments, and result is the result of the action.

Finally, you can return a React component to render a custom component.

{
  // ...
  render: ({status, args, result}) => (
    <div>
      {status === "complete" ? "Done!" : "Processing..."}
    </div>
  ),
}

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