> 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/convai-playground/character-customization/agentic-actions.md).

# 智能体动作

配置动作合约，选择入门模板，检查解析输出，并将每个生成的动作连接到客户端处理程序。

Agentic Actions 可让你定义用于结构化输出的提示指令，并测试角色在聊天中如何发出动作。使用此选项卡准备契约、为新连接启用契约，并检查结果；请勿将解析后的输出视为已执行的证明。

### 开始之前

* 创建要配置的角色。
* 确定客户端可以执行哪些动作或工具。
* 测试执行之前，先在客户端中使用稳定的名称注册这些功能。

{% hint style="warning" %}
Actions Contract 是提示文本，而不是可执行的客户端代码。 `Parsed action` 行确认 Convai 识别到了发出的动作，但不能确认客户端已执行该动作。
{% endhint %}

### 准备 Actions Contract

{% stepper %}
{% step %}

#### 打开 Agentic Actions

打开一个角色，然后在角色编辑器中选择 **Agentic Actions** 。

**启用 Agentic Actions** 对于没有已保存旧版 Character Actions 的角色，默认处于关闭状态。你可以在开关关闭时准备并保存契约。只有启用 Agentic Actions 并建立新的聊天连接后，契约才会加入模型提示。

对于已保存一个或多个 Character Actions、且从未保存过此开关设置的现有角色，系统会显示为 **已启用（继承）**。这样可以保留现有动作行为，而不会悄然写入新设置。此后，将开关设为开或关并保存，即表示明确选择了生效设置。

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2Fgit-blob-58e7764171366c85cf0a8c51ec6b1943ac596807%2Fplayground-agentic-actions-disabled-panel.png?alt=media" alt="Agentic Actions editor with Enable Agentic Actions switched off, the template selector available, and a saved Actions Contract retained"><figcaption><p>在 Agentic Actions 关闭时准备并保存 Actions Contract。在为新连接启用此功能之前，已保存的文本不会加入模型提示。</p></figcaption></figure>
{% endstep %}

{% step %}

#### 预览模板

从 **Action contract template**中选择一个示例。所选示例会显示在 **Template preview**.

选择模板不会更改当前契约、启用 Agentic Actions，也不会保存角色。

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2Fgit-blob-7d4e0631262519b083a00054d483de96e4542704%2Fplayground-agentic-actions-template-menu.png?alt=media" alt="Agentic Actions template menu showing three embodied templates and three browser-agent templates"><figcaption><p>选择器中包含三个具身示例和三个浏览器智能体示例。</p></figcaption></figure>
{% endstep %}

{% step %}

#### 添加并调整示例

选择 **Add template to contract** 即可将预览内容追加到现有文本下方。编辑器会保留当前契约，而不是将其替换。

将建议的动作和工具名称替换为客户端注册的准确名称。Actions Contract 最多可包含 `20,000` 个字符。如果添加内容会超出限制，请先缩短当前契约，再添加模板。

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2Fgit-blob-b4d67dc73ee98f5b67d0a52b508a4d99064209c1%2Fplayground-agentic-actions-template-appended.png?alt=media" alt="A gestures template preview above an existing Actions Contract after the example was appended"><figcaption><p>添加模板会保留现有契约，并在其后追加完整示例。此操作不会启用 Agentic Actions，也不会自动保存。</p></figcaption></figure>
{% endstep %}
{% endstepper %}

### 选择一个起始模板

模板列表中包含三个具身示例和三个浏览器示例：

| 模板                  | 起始点                                    |
| ------------------- | -------------------------------------- |
| **具身 · 手势与反应**      | 辅助口头回应的克制手势。                           |
| **具身 · 移动与跟随**      | 按顺序移动，目的地明确，目标角色清晰。                    |
| **具身 · 物体交互**       | 基于客户端上下文的拾取、递交和放置流程。                   |
| **浏览器智能体 · 导航与检查**  | 导航并重新检查可见的页面状态。                        |
| **浏览器智能体 · 安全填写表单** | 可撤销的表单填写，并在执行重要提交前进行确认。                |
| **浏览器智能体 · 研究与总结**  | 检查来源，并生成简洁的口头回答；如果客户端支持，还可显示包含丰富链接的内容。 |

浏览器模板不会为 Playground 添加浏览器控件或工具处理程序。它们是供客户端使用的起点，客户端需注册并执行相应的浏览器工具。

### 为新聊天启用操作

开启 **启用智能体操作**，然后选择 **更新角色**。保存后会重新连接聊天，使已接受的设置和契约应用于下一次交互。

关闭智能体操作不会删除已保存的契约。保存禁用状态后会重新连接，且不会将操作契约或已配置的角色操作添加到模型提示中。

对于标记为 **已启用（继承）**&#x7684;旧版角色，只有在想要用显式设置替换继承状态时，才保持开关开启并保存。关闭开关并保存，会有意禁用其已保存的旧版角色操作以及新连接所用的操作契约。

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2Fgit-blob-b919ff89e5e2d1a9e3cfe7baf9460b88930d90c9%2Fplayground-agentic-actions-enabled-saved.png?alt=media" alt="Agentic Actions enabled with the saved contract retained and a Parsed action Wave status visible in chat"><figcaption><p>启用开关会为新连接激活已保存的操作指令。已解析操作行确认的是识别和传递，而非客户端执行。</p></figcaption></figure>

### 检查系统生成的操作指令

在 **显示系统生成的操作指令** 中选择 **操作契约 / 操作定义** ，以检查当前 Core 提示组装器会针对已保存的角色配置添加的确切操作指令块和结构化输出指令块。

显示的指令块为只读内容。它们不会复制到操作契约中，也不会作为用户编写的文本保存。编辑草稿会使显示的结果失效；保存角色后重新检查，即可查看新配置生效的指令。

{% hint style="info" %}
此检查反映的是当前 Core 提示组装器的行为，并不声称与已停用的旧版 Playground 或 Middleman 实现所生成的历史提示逐字节完全一致。
{% endhint %}

### 检查已解析输出和原始输出

发送一条明确请求执行某个已注册操作的聊天消息。Convai 识别到结构化操作输出时，聊天中会显示 `Parsed action: <name>` 状态。如果操作包含目标，则箭头后会显示该目标。

**在聊天中显示未经筛选的完整 LLM 输出** 独立控制诊断信息的显示，不受 **启用智能体操作**:

| 设置 | 聊天显示                          |
| -- | ----------------------------- |
| 关闭 | 显示常规文本流以及任何已解析的操作状态。          |
| 开启 | 还会显示提供方可见的预解析输出，同时保留已解析的操作状态。 |

启用原始输出显示不会让结构化标记成为语音合成的一部分。不要解析原始文本来驱动操作。请使用传递到客户端的结构化操作事件。

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2Fgit-blob-91e94568764f71757a8aeef480cc03821e7e08bf%2Fplayground-agentic-actions-chat-raw-off.png?alt=media" alt="Filtered chat showing a spoken response and Parsed action Wave without provider JSON"><figcaption><p>关闭原始输出显示时，聊天会显示常规响应和已解析的操作状态，不会暴露提供方输出。</p></figcaption></figure>

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2Fgit-blob-3e739ae2371e064eb6f9c2f948f205c385d680a0%2Fplayground-agentic-actions-chat-raw-on.png?alt=media" alt="Unfiltered chat showing provider JSON and a separate Parsed action Wave status"><figcaption><p>开启原始输出显示时，会显示提供方可见的 JSON 供检查，已解析的操作则单独显示。无论哪一行，都不能证明客户端已执行该操作。</p></figcaption></figure>

### 验证客户端执行情况

在拥有相应功能的客户端中确认操作处理情况。对于具身操作，请观察动画、移动或对象操作。对于浏览器操作，请观察已注册工具的结果及随后出现的页面状态。

请分别看待以下状态：

1. 模型发出操作。
2. Convai 解析并传递操作。
3. 客户端接受并执行操作。
4. 客户端观察到由此产生的状态。

当 Playground 聊天显示 `Parsed action`时，可证明第二种状态。仅凭这一点无法证明后续的客户端状态。

### 故障排查

#### 未显示已解析的操作

**症状：** 角色会回应，但聊天中没有显示 `Parsed action` 行。

**原因：** Agentic Actions 已关闭、该设置未保存到新连接、请求未要求执行操作，或契约与已注册的能力不匹配。

**修复：** 启用 Agentic Actions，选择 **更新角色**，并发送明确无歧义、使用准确已注册操作名称的请求。

**验证：** 下一个适用轮次会显示 `Parsed action: <name>`.

#### 已解析的操作未执行

**症状：** 聊天中显示 `Parsed action`，但预期的客户端行为没有发生。

**原因：** 客户端没有匹配的处理程序、操作名称不一致，或处理程序在交付后执行失败。

**修复：** 为准确的操作名称注册处理程序，并检查客户端执行结果。

**验证：** 客户端执行相应行为并报告结果状态。

#### 无法添加模板

**症状：** **Add template to contract** 呈禁用状态，并显示字符数限制提示。

**原因：** 追加模板会超出 `20,000` 个字符的限制。

**修复：** 缩短当前契约，然后再次添加模板。

**验证：** 模板显示在现有契约下方，且不会替换现有内容。

### 后续步骤

使用客户端所用的 SDK 注册并执行具身操作：

{% content-ref url="/pages/48542e3f43c9fa4320574cae5c541c172f781a1d" %}
[角色动作](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions.md)
{% endcontent-ref %}

{% content-ref url="/pages/46d3b8351132c46e6470ee20811d82cf5cae7051" %}
[角色动作](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions.md)
{% endcontent-ref %}

{% content-ref url="/pages/503cd2436973022c29d385f47025d13de33f428c" %}
[处理角色动作](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/actions.md)
{% endcontent-ref %}

直接实现响应协议时，请参阅 Live API 参考文档：

{% content-ref url="/pages/1cd881956cb1a85bfe10e533ddd9bd813eeb716d" %}
[响应契约与解析](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/response-contract-and-parsing.md)
{% endcontent-ref %}


---

# 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/zh/convai-playground/character-customization/agentic-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.
