useCopilotAction.mdx

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

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.

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

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.

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

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