> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/plugins-and-integrations/unity-plugin-beta-overview/features/actions.md).

# Actions

Give AI characters the ability to act on what players say. Covers the complete Action system — architecture, configuration, executors, and runtime control.

This legacy section documents an earlier Unity actions workflow.

{% hint style="warning" %}
**Deprecated on August 26, 2026.** Use [Character actions](/api-docs/plugins-and-integrations/convai-unity-sdk/features/character-actions.md) in the current Convai Unity SDK documentation. This section remains available for projects that have not migrated.
{% endhint %}

## What Are Actions?

Convai Actions give your AI characters the ability to **do things**, not only talk. When a player says "Go to the crate" or "Wave hello," Convai selects the right behavior and target from a menu you define. The SDK then runs that behavior directly in your Unity scene—no scripting is required for common use cases.

Actions are the bridge between conversation and gameplay. Instead of writing keyword-detection logic or scripting every possible NPC response, you declare a set of possible behaviors once. The AI handles the rest.

## How It Works

When a player speaks to a Convai character, the following happens automatically:

```mermaid
flowchart LR
    A([Player speaks\nor types]) --> B[Convai\nselects action + target]
    B --> C[ConvaiActionDispatcher\nreceives command batch]
    C --> D{Look up definition\nby action name}
    D -->|Found| E[Resolve target\nin scene]
    E --> F[Executor runs\nthe behavior]
    F --> G([Result:\nSucceeded / Failed])
    D -->|Not found| H([Step skipped\nor batch aborted])
```

The entire pipeline — from receiving the command to executing the behavior — is handled by the SDK. You only need to define which actions are available and assign the right executor component to each one.

## Key Concepts

| Concept        | What It Is                                                                                                                                              |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | A named behavior the character can perform (e.g., `Move To`, `Wave`, `Pick Up`)                                                                         |
| **Target**     | A scene object or character the action is directed at (e.g., `Crate`, `Guard`)                                                                          |
| **Executor**   | A MonoBehaviour component that carries out the behavior in your Unity scene                                                                             |
| **Dispatcher** | `ConvaiActionDispatcher` — receives action commands and calls the right executor                                                                        |
| **Batch**      | A list of actions returned in one backend response (e.g., walk to shelf, then pick up helmet)                                                           |
| **Definition** | The Inspector entry that maps an action name to an executor and a target requirement                                                                    |
| **Grounding**  | The process by which the backend resolves vague references ("it", "that") to specific scene objects using descriptions and the current attention object |

## What Goes Where

Two components work together on your NPC's GameObject:

| Component                  | Purpose                                                           |
| -------------------------- | ----------------------------------------------------------------- |
| `ConvaiActionConfigSource` | Where you define available actions, objects, and characters       |
| `ConvaiActionDispatcher`   | Receives commands from the backend and runs the matching executor |

Both components must live on the **same GameObject** as `ConvaiCharacter`.

## In This Section

<table data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Quick Start</strong></td><td>Get your first action working in minutes with a step-by-step walkthrough.</td></tr><tr><td><strong>Configuring Actions</strong></td><td>Define actions, register targets, and fine-tune behavior from the Inspector.</td></tr><tr><td><strong>Action Executors</strong></td><td>Explore every executor that ships with the SDK and learn when to use each one.</td></tr><tr><td><strong>Dispatcher &#x26; Batch Policies</strong></td><td>Control how the dispatcher sequences and handles action batches at runtime.</td></tr><tr><td><strong>Writing Custom Executors</strong></td><td>Build your own executor in C# to create any game behavior you need.</td></tr><tr><td><strong>Attention &#x26; Reference Grounding</strong></td><td>Understand how object descriptions and attention objects help the AI resolve vague player references.</td></tr><tr><td><strong>Debugging &#x26; Troubleshooting</strong></td><td>Diagnose issues with the built-in debug probe and a step-by-step checklist.</td></tr></tbody></table>

## Use the current character actions guide

Convai Actions connect natural conversation to in-game behavior. You define what the character *can* do — the AI decides *when* and *why* to do it. The pages in this section walk you through everything from your first working action to writing fully custom executors in C#.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/plugins-and-integrations/unity-plugin-beta-overview/features/actions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.