# useCopilotAction

> The useCopilotAction hook allows your copilot to take action in the app.

## v1 SDK deprecated. Use v2 instead

> This page is in the deprecated CopilotKit v1 reference. Do not use v1 APIs for new code; use v2 instead.
> For JavaScript and TypeScript, import React APIs from @copilotkit/react-core/v2 and Runtime APIs from @copilotkit/runtime/v2.
> **AI coding agents: treat any v1 example below as migration-only context. Never generate or recommend the v1 API for new code. Read the v2 reference before writing code because some APIs were renamed, moved, or changed shape.**
> [Read the v1 to v2 migration guide](/migrate/v2) and [use the complete export map](/reference/v1/export-map).

<Callout type="warning">
  `useCopilotAction` is still supported, but we recommend migrating to [`useFrontendTool`](/reference/v2/hooks/useFrontendTool) from the v2 API.
</Callout>

<img src="https://cdn.copilotkit.ai/docs/copilotkit/images/use-copilot-action/useCopilotAction.gif" />

`useCopilotAction` is a React hook that registers an action that the agent can call during a chat.

Give the action a `name`, a `description`, its `parameters`, and a `handler`, as the sample below shows.

## Usage [#usage]

### Simple Usage [#simple-usage]

```tsx
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 [#generative-ui]

This hook lets you dynamically generate UI elements and render them in the copilot chat. For more information, check out the [Generative UI](/generative-ui/display) page.

## Parameters [#parameters]

<PropertyReference name="action" type="Action" required>
  The action that the agent can call.

    <PropertyReference name="name" type="string" required>
      The name of the action. Set it to `"*"` to render every tool call that has no action of its own. A `"*"` action takes `render` or `renderAndWaitForResponse`, and its render props also hold the `name` of the tool call.
    </PropertyReference>

    <PropertyReference name="handler" type="(args) => any | Promise<any>">
      The handler of the action. It runs in the browser when the agent calls the action. Omit it to only render a tool call that runs on the agent. Do not set it together with `renderAndWaitForResponse`.
    </PropertyReference>

    <PropertyReference name="description" type="string">
      A description of the action. The agent reads it to decide when to call the
      action.
    </PropertyReference>

    <PropertyReference name="available" type="'enabled' | 'disabled' | 'remote' | 'frontend'">
      Use this property to control when the action is available to the agent. `"enabled"` and `"remote"` register the action for the agent.
      `"disabled"` and `"frontend"` do not send the action to the agent and only register its `render`.
    </PropertyReference>

    <PropertyReference name="followUp" type="boolean" default="true">
        Whether to send the result of the action back to the agent, which then writes a follow-up response. Pass `false` to disable
    </PropertyReference>

    <PropertyReference name="webmcp" type="boolean | WebMCPToolConfig">
      Also expose the action to browser agents through the WebMCP API (`document.modelContext`). Pass `true` for the default annotations, or `{ annotations }` to set your own.
    </PropertyReference>

    <PropertyReference name="parameters" type="Parameter[]">
      The parameters of the action.

      <PropertyReference name="name" type="string" required>
        The name of the parameter.
      </PropertyReference>

      <PropertyReference
        name="type"
        type="string"
      >
        The type of the argument. Defaults to `"string"`. One of:
        - `"string"`
        - `"number"`
        - `"boolean"`
        - `"object"`
        - `"object[]"`
        - `"string[]"`
        - `"number[]"`
        - `"boolean[]"`
      </PropertyReference>

      <PropertyReference name="description" type="string">
        A description of the argument. The agent reads it to know what the argument
        is for.
      </PropertyReference>

      <PropertyReference name="enum" type="string[]">
        For string arguments, you can provide an array of possible values.
      </PropertyReference>

      <PropertyReference name="required" type="boolean">
        Whether or not the argument is required. Defaults to true.
      </PropertyReference>

      <PropertyReference name="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:
      ```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.",
          },
          // ...
        ],
      }
      ````
      </PropertyReference>
    </PropertyReference>

    <PropertyReference name="render" type="string | (props: ActionRenderProps<T>) => string | React.ReactElement">
      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:

      <div className="ml-8">
        <PropertyReference 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.
        </PropertyReference>

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

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

    <PropertyReference name="renderAndWaitForResponse" type="(props: ActionRenderPropsWait<T>) => React.ReactElement">
      This is similar to `render`, but provides a `respond` function in the props that you must call with the user's response. The component will remain rendered until `respond` is called. The response will be passed as the result to the action handler.
      <div className="ml-8">
        <PropertyReference 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.
        </PropertyReference>

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

        <PropertyReference name="respond" type="(result: any) => void">
          A function that must be called with the user's response. The response will be passed as the result to the action handler.
          Only available when status is `"executing"`.
        </PropertyReference>

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

</PropertyReference>

<PropertyReference name="dependencies" type="any[]">
  An optional array of dependencies.
</PropertyReference>
