> 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 Actions

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

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

| 阶段                | 目标                                | 你将学到什么                                                                                                    |
| ----------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------- |
| **阶段 1 — 默认动作**   | 无需编写脚本，让机器人在关卡中动起来。               | 在聊天机器人上启用动作，注册对象，设置移动，基于 NavMesh 运行。                                                                      |
| **阶段 2 — 自定义动作**  | 添加一个不带参数的新动作，并将其连接到 Blueprint 事件。 | 该 `FConvaiAction` 模板， `OnActionReceived` 事件， `HandleActionCompletion`.                                    |
| **阶段 3 — 带参数的动作** | 添加带类型的参数、连接器、选项，并使用实时编辑器预览。       | 参数类型（`Auto` / `Reference` / `String` / `Number` / `Bool` / `Enum`), `Get Param As X` 访问器、渲染后的字符串预览、中止与完成。 |

### 心智模型

动作系统有三个组成部分，你会在本指南中反复看到：

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

### V2 有什么新变化

如果你在这次重构之前用过 Convai 动作，以下是概览中的变化：

* 动作模板从原始 `FString` (`“Wait For <time in seconds>”`）迁移到了结构化的 `FConvaiAction` ，带类型的 `Parameters`、可选的 `连接词`、可选的 `Choices` / `EnumType`.
* 一个实时的双向 **渲染预览** 在 Details 面板中会精确显示 LLM 将收到的内容——而且你可以编辑任一侧。
* 动作结果将一切统一为 `Parameters: TMap<Name, FConvaiResultParam>` 并始终尽力进行字符串 / 数字 / 布尔值 / actor 引用强制转换。旧版 `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, and the optional `goal` 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>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.