智能体动作

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

Agentic Actions 允许你为结构化输出定义提示词指令，并测试角色在聊天中如何发出操作。使用该标签页准备一个契约，为新的连接启用它，并在不将已解析输出视为执行证明的情况下检查结果。

开始前

• 创建你想要配置的角色。
• 决定你的客户端可以执行哪些操作或工具。
• 在测试执行之前，请在客户端中用稳定名称注册这些能力。

操作契约是提示文本，不是可执行的客户端代码。一个 已解析的操作 行确认 Convai 识别到了一个发出的操作；它并不确认你的客户端已执行它。

准备操作契约

1

打开 Agentic Actions

打开一个角色，然后选择 代理行为 在角色编辑器中。

启用 Agentic 操作 对于没有已保存旧版 Character Actions 的角色，此开关默认关闭。你可以在开关关闭时准备并保存契约。只有在启用 Agentic Actions 并启动新的聊天连接后，契约才会进入模型提示词。

对于已经保存了一个或多个 Character Actions 且从未保存过此开关的现有角色，会显示为 已启用（继承）。这会保留其现有的操作行为，而不会在不提示的情况下写入新设置。无论将开关保存为开或关，此后都会让该明确选择成为权威设置。

在 Agentic Actions 关闭时准备并保存操作契约。已保存的文本不会加入模型提示词，直到你为新的连接启用该功能。

2

预览模板

从以下内容中选择一个示例 操作契约模板。所选示例会显示在 模板预览.

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

选择器包含三个具身示例和三个浏览器代理示例。

3

添加并调整示例

选择 将模板添加到契约 以将预览附加到现有文本下方。编辑器会保留当前契约，而不是替换它。

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

添加模板会保留现有契约并附加完整示例。它不会启用 Agentic Actions，也不会自动保存。

选择起始模板

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

模板	起点
具身 · 手势与反应	克制的手势，配合口头回应。
具身 · 移动与跟随	有序移动，带有落地目标和角色目标。
具身 · 物体交互	基于客户端上下文的拾取、交接和放置序列。
浏览器代理 · 导航与检查	对可见页面状态进行导航和重新检查。
浏览器代理 · 安全填写表单	可撤销的表单填写，并在有影响的提交前进行确认。
浏览器代理 · 研究与总结	在客户端支持时，进行来源检查，并以简洁语音和富含链接的显示输出呈现。

浏览器模板不会向 Playground 添加浏览器控制项或工具处理器。它们是供会注册并执行匹配浏览器工具的客户端使用的起点。

为新聊天启用操作

开启 启用 Agentic 操作的密钥，再选择 更新角色。保存后会重新连接聊天，从而使已接受的设置和契约应用于下一次交互。

关闭 Agentic Actions 不会删除已保存的契约。保存禁用设置后重新连接时，不会把操作契约或已配置的角色操作添加到模型提示词中。

对于标记为以下状态的旧版角色 已启用（继承），只有在你想用显式设置替换继承状态时，才保持开关开启并保存。将其关闭并保存会有意禁用其已保存的旧版 Character Actions 和其 Actions Contract，供新连接使用。

启用开关会为新连接激活已保存的操作指令。已解析的操作行确认的是识别和传递，而不是客户端执行。

检查系统生成的操作指令

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

显示出的块是只读的。它们不会被复制到操作契约中，也不会作为用户编写的文本保存。编辑草稿会使显示结果失效；请保存角色并再次检查，以查看新配置的有效指令。

此检查反映的是当前的 Core 提示词组合器。它并不声称与已停用的旧版 Playground 或 Middleman 实现生成的历史提示词逐字节一致。

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

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

在聊天中显示完整未过滤的 LLM 输出 独立控制诊断显示，与 启用 Agentic 操作:

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

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

关闭原始显示时，聊天会显示正常响应和已解析的操作状态，而不会暴露提供方输出。

开启原始显示时，可供提供方查看的 JSON 会显示出来以供检查，而已解析的操作仍保持独立。无论哪一行，都不能证明客户端已执行该操作。

验证客户端执行

在拥有该能力的客户端中确认操作处理。对于具身操作，请观察动画、移动或物体操作。对于浏览器操作，请观察已注册的工具结果以及由此产生的页面状态。

请分别看待以下状态：

1. 模型发出一个操作。
2. Convai 解析并传递该操作。
3. 客户端接受并执行该操作。
4. 客户端观察到结果状态。

Playground 聊天在显示 已解析的操作时，可以证明第二种状态。它本身无法证明后续的客户端侧状态。

故障排查

没有出现已解析的操作

症状： 角色有回应，但聊天中没有显示 已解析的操作 行。

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

解决方法： 启用 Agentic Actions，选择 更新角色，并发送使用准确已注册操作名称的明确请求。

验证： 下一次符合条件的轮次会显示 已解析的操作：<name>.

已解析的操作未运行

症状： 聊天显示 已解析的操作，但预期的客户端行为没有发生。

原因： 客户端没有匹配的处理器、操作名称不同，或者处理器在传递后失败。

解决方法： 为准确的操作名称注册处理器，并检查客户端侧执行结果。

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

无法添加模板

症状： 将模板添加到契约 已禁用，并显示字符限制消息。

原因： 追加模板将超过 20,000 个字符。

解决方法： 请缩短当前契约，然后再次添加模板。

验证： 模板会显示在现有契约下方，而不会替换它。

下一步

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

角色动作角色动作动作

直接实现响应协议时，请使用 Live API 参考：

响应契约与解析