> 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/zh/cha-jian-yu-ji-cheng/unreal-engine-plugin-beta-overview/convai-actions.md).

# Convai 动作

Convai 角色不仅能对话：它们还能 **执行物理动作** 在你的场景中执行。动作系统让驱动 Convai 角色的 LLM 能发出结构化命令（移动到目标、拾取物体、等待、运行自定义动画等），然后由你的游戏代码执行这些命令。

本指南分为 **三个阶段**，每个阶段都会引入下一层能力：

| 阶段                  | 目标                                | 你将学习的内容                                                                                               |
| ------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------- |
| **第 1 阶段 — 默认动作**   | 无需任何脚本即可让机器人在关卡中移动。               | 为聊天机器人启用动作，注册对象，设置移动能力，在 NavMesh 上运行。                                                                 |
| **第 2 阶段 — 自定义动作**  | 添加一个不带参数的新动作，并将其连接到 Blueprint 事件。 | 该 `FConvaiAction` 模板， `OnActionReceived` 事件， `HandleActionCompletion`.                                |
| **第 3 阶段 — 带参数的动作** | 添加类型化参数、连接器、选项，并使用实时编辑器预览。        | 参数类型（`Auto` / `Reference` / `字符串` / `Number` / `布尔` / `枚举`), `Get Param As X` 访问器、渲染后的字符串预览、中止与完成的区别。 |

### 心智模型

动作系统有三个组成部分，你将在本指南中多次看到：

1. **聊天机器人的 `环境`** —— 聊天机器人组件上的一个结构体，用于声明机器人可以作用的世界：
   * `动作` —— `FConvaiAction` 机器人允许使用的模板列表。
   * `Objects` —— 场景中机器人可作为目标的道具（立方体、拉杆、门等）。
   * `Characters` —— NPC / 玩家。这些会在 `/connect` 时作为机器人的“动作契约”发送到服务器。
2. **`bEnableActions`** —— 一个针对每个聊天机器人的开关，用来决定 `环境` 是否发送该内容。关闭 = 仅进行对话。开启 = 机器人可以发出动作序列。
3. **动作-响应流程** —— 当机器人决定执行动作时，服务器会返回一个 `FConvaiResultAction`列表。插件将每一项与你声明的模板进行匹配，解析出参数值，并根据以下内容解析任何角色引用： `Environment.Objects` / `.Characters`，并触发 `OnActionReceivedEvent_V2` ，并传入解析后的序列。你的处理程序执行该动作，然后回调到 `HandleActionCompletion` 或 `AbortActionSequence` 以继续 / 重试 / 中止。

### V2 中的新内容

如果你在此次重构之前使用过 Convai 动作，下面是变化概览：

* 动作模板已从原始 `FString` (`“Wait For <time in seconds>”`）迁移到结构化的 `FConvaiAction` ，带有类型化的 `Parameters`、可选的 `连接器`、可选的 `Choices` / `枚举类型`.
* 一个实时的双向 **渲染预览** 在 Details 面板中会准确显示 LLM 将收到的内容——而且你可以编辑任一侧。
* 动作结果将所有内容统一为 `参数：TMap<Name, FConvaiResultParam>` 并始终尽最大努力进行字符串 / 数字 / 布尔 / 角色引用的转换。旧版 `RelatedObjectOrCharacter` 是位于 `ConvaiExtraParams` 仍会作为已弃用的镜像填充，因此现有处理程序可以继续工作。

如果你有旧版图，请遵循第 3 阶段中的迁移说明。


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/unreal-engine-plugin-beta-overview/convai-actions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.