响应契约与解析

了解旧版和规范模型输出、原始文本投影、动作解析、客户端执行反馈和保留的响应模式。

Convai 角色可以生成对话文本、语义动作、客户端工具调用和情绪。你的客户端接收到的契约取决于在……时选择的能力 /connect.

Actions 协议 v2、规范模型输出 v2，以及原始 bot-llm-text 是可选启用的候选表面。本文档不确认生产可用性或已发布的 SDK 版本。请验证 capabilities 由你的目标环境返回。

---

选择一个输出契约

选择	传递的行为
省略 capabilities	Action 协议 v1、模型输出 v1，以及旧版过滤 bot-llm-text。该 /connect 响应省略 capabilities.
action_protocol_version: 2	关联的客户端 工具调用 项目和 action-result 反馈。
model_output_version: 2	类型化 model-output 封装成为规范输出的权威来源。
bot_llm_text_mode: "raw"	现有的 bot-llm-text 事件在结构化输出解析和对话过滤之前携带提供方可见文本。

这些选择彼此独立，但每个非旧版选择都需要一个单一的已创建会话。见 Agentic Actions v2 预览 关于拓扑和工具声明限制。

此候选表面未定义内置显示、链接、卡片、表格、CSV 或快速响应模式。不要将原始文本视为显示协议。如果你的应用使用一个 扩展 项目，只接受你的客户端明确识别的模式和版本，并始终提供安全回退。

---

动作如何分离

语义动作和客户端工具调用使用不同路径：

1. 你在……中声明语义动作能力和可选客户端工具 action_config 于 /connect.
2. 当 启用 Agentic 操作 对角色开启时，Convai 会把适用的契约添加到提示中。当它被明确关闭时，语义动作和客户端工具模式不会暴露给模型。如果该设置缺失，已保存的旧版 Character Actions 会继承一个启用状态，适用于模型输出 v1 和 v2；没有已保存旧版动作的角色在模型输出 v2 中默认为关闭。
3. 语义动作可以使用提供方原生调用或 Convai 解析的受支持结构化响应。客户端工具需要提供方原生函数调用。
4. Convai 通过规范的……发出语义动作或关联的客户端工具调用 model-output 在被选中时。它也可以发出 action-response 作为兼容性投影。

已解析的模型必须支持用于客户端工具的提供方原生函数调用。仅凭能力协商并不授权某项操作，也不能保证模型能够调用已声明的工具。

角色被赋予的动作规则

当语义动作能力处于活动状态时，Convai 会添加这些约束：

• 会返回一个完整、按顺序的动作序列 仅 当用户请求一个物理任务时。
• 仅可使用你 动作 列表中的精确动作名称。模型被指示绝不发明或重命名动作。
• 仅可针对你 对象 和 characters 列表中的对象和角色。 scene_description 仅是描述性上下文—— 它不会扩展能力列表.
• “我”, “我的”以及 “这里” 解析为当前说话者。
• “this”, “that”, “it”以及 “那里” 解析为 current_attention_object 当已设置时。
• 如果任务不可能、未受支持、非物理、不安全，或被口头拒绝，动作列表为空。
• 如果角色在口头回复中拒绝该任务，动作列表也为空。
• 动作载荷不应写入对话文本。

提示指令可以减少无效的模型输出，但它们不是客户端授权。Convai 在投影前会验证语义动作名称和目标。对于客户端工具，它会验证声明的名称和 JSON Schema 参数，而你的应用仍需负责权限、确认、执行以及副作用安全。

---

规范化模型输出

当 model_output_version 是 2，每个完成的封装都包含一个唯一的 output_id，一个可选的 logical_turn_id，原始的 raw 字符串，以及类型化的 items 中列表中的索引。使用 items 作为唯一可信的可渲染或可执行投影。绝不要解析或执行 raw.

一个逻辑轮次可以产生多个封装，例如一个用于文本，另一个用于语义动作或客户端工具调用。按 output_id进行分组。 logical_turn_id 当它存在时。 最终：true 完成的是一个封装，而非整个逻辑轮次。

支持的项目类型有：

条目	用途
message	助手 content 在 "final" 或 "commentary" 通道。
semantic_action	已验证的语义动作，带有 ID, 名称，以及可选的 目标.
工具调用	关联的客户端工具请求，带有 ID, 名称，可选的 目标，以及已验证的 arguments.
情绪	情绪 名称 和强度 强度.
扩展	用于客户端可识别扩展的按模式版本定义的载荷。此预览未定义显示或快速响应模式。

当前生产者会发出最终通道消息、语义动作、客户端工具调用和情绪。评论通道消息和 扩展 项目是有效的类型化投影，候选客户端可以解析，但当前运行时不会生成它们。

Convai 会继续发出旧版投影以保持兼容性。如果你的客户端选择模型输出 v2，请消费 model-output.items 并忽略重复的 action-response 消息。

客户端工具执行反馈

一个 工具调用 是供客户端考虑的请求。Convai 不会执行它。客户端根据本地策略验证该请求，执行或拒绝该操作，并发送一个终态 action-result 与 "completed", "error"，或 "已取消".

Convai 使用 服务器响应确认结果。对已接受调用 ID 重试相同的终态载荷是幂等的。冲突的重试会被拒绝。在已接受结果之后，Convai 会把它提供给相同的模型上下文，以便生成可以继续。不要把该确认用作顺序屏障；后续输出可能先到。

调用可以并行挂起。候选实现每个用户轮次最多允许 8 个未完成调用，以及最多 8 轮续传。它默认等待 60 秒，然后向模型返回超时错误。这些限制并不意味着你的应用会顺序执行或恰好一次副作用。

bot-llm-text 模式

bot-llm-text 在两种模式下都保持为流式文本投影：

模式	内容	安全用法
"legacy" 或省略	经过旧版解析和过滤路径后的对话文本。	聊天记录以及既定的口语回复路径。
"raw"	在 Convai 的结构化输出解析和对话过滤之前，提供方可见的文本块。	诊断信息或明确标注的开发者视图。

原始模式可以包含结构化 JSON、控制语法、拒绝文本、音频转录文本或其他提供方可见文本字段。不能保证它包含非文本原生工具调用增量。它不能替代 model-output.items，并且不能驱动动作。即使原始文本投影给客户端，已解析的对话和语音路径仍然是权威的。

如果原始传递失败，Convai 会继续解析后的输出路径，并可以发出一个非致命的 raw_bot_llm_text_delivery_failed 错误。失败的原始片段不会重放。

---

旧版文本过滤

在旧版模式下，Convai 会在对话文本投影或到达语音合成之前应用固定的过滤序列。原始 bot-llm-text 会绕过此客户端投影过滤器，但不会改变已解析的语音路径。

#	已移除	匹配的	范围
1	弃权控制标记	[ABSTAIN], [ABSTAINED] （不区分大小写）	文本中的任何位置
2	内部工具调用语法	参见 保留模式 下方	仅前导
3	Markdown 格式	标准 Markdown 强调、标题、列表标记、代码围栏	任何位置
4	视觉模态标签	[vision], [camera], camera: 及类似形式——见下方	仅前导，当视觉输入处于活动状态时
5	叙事设计索引前缀	<index>||| 在回复的最开头	仅前导，当叙事设计处于活动状态时
6	表情符号	Unicode 表情符号和短代码	任何位置，在语音合成阶段

过滤器 1–5 影响旧版 bot-llm-text 以及口语路径。过滤器 6 仅在语音阶段生效，因此表情符号可能保留在旧版文本中，但会从语音中省略。

流式行为

过滤器作用于流式 token 流，而不是完整响应。一个跨越两个块的模式—— [ABS 然后调用 TAIN] ——仍会被正确移除：服务器会缓冲任何可能是保留模式开头的尾部片段，并在证明它不匹配后再释放它。值得注意的一个后果是： 响应末尾的最后几个字符可能会被短暂保留 然后才被发出。

---

保留模式

这些模式在它们出现在 开头 时会被移除。不要指示角色以其中任何一个开始回复，也不要设计使用它们的响应格式。

内部工具调用语法。 一个标签后跟一个调用表达式：

tool_code: <name>(...)
tool_call: <name>(...)
function_call: <name>(...)

其中 <name> 是以下之一 look, get_image, abstain，或 emit_actions。匹配不区分大小写。裸调用语法—— get_image(...), abstain(...), emit_actions(...) ——也会被移除。解析器会匹配平衡的括号并尊重引号，因此调用中的嵌套括号和带引号的字符串都能正确处理。最多会从一条回复中剥离四个连续这样的前缀。

视觉模态标签。 带括号或以冒号结尾的形式： vision, 视觉, camera, webcam, canvas, screen:

[vision] ...        [vision]: ...        vision: ...
[camera] ...        [camera]: ...        camera: ...

弃权标记。 [ABSTAIN] 和 [ABSTAINED]，在文本中的任何位置。

叙事设计前缀。 一个前导整数后跟三个竖线—— 1|||, -1||| ——当角色启用叙事设计时。

这些前导模式过滤器会保留句中提及。只有旧版对话输出开头的出现才被视为工具调用或视觉控制语法。

---

编写自定义提示和响应格式

如果你编写自己的核心描述、角色提示或输出格式，这些规则会帮你避免麻烦：

• 不要以任何保留模式开头生成回复。 以 function_call: emit_actions(...) 开头的回复会被静默移除该前缀，而你的客户端永远不会看到它。
• 不要依赖 Markdown 在旧版路径中被保留。 强调、标题和代码围栏会从对话输出中移除。请使用规范的 model-output.items 或已声明的客户端工具，而不是解析格式化文本。
• 不要把动作载荷放进对话文本中。 使用 action_config 并处理已验证的语义项目。通过旧版路径保留的 JSON 可以被朗读出来。
• 将原始文本与语音分开。 原始 bot-llm-text 是开发者投影，可能与通过口语路径发送的已解析文本不同。
• 让模板和场景文本不包含保留前缀。 通过……注入的值 narrative_template_keys, update-scene-metadata，或 context-update 会成为提示的一部分，并可能影响回复的开头方式。

---

故障排查

角色把脚手架、JSON 或选项列表朗读出来。 已解析的对话输出包含能通过过滤器保留下来的结构。把可执行数据移到已声明的工具或语义动作中，并让对话回复保持自然。

一个动作从未触发。 确认 启用 Agentic 操作 对角色是开启的，并且目标模型支持所需的输出模式。对于语义动作，确认其名称和目标已声明。对于客户端工具，确认已选择 action protocol v2 且声明通过了模式验证。

一个工具调用出现了，但模型从未继续。 返回一个 action-result 其 ID 与该调用匹配。检查 服务器响应 确认中的 status: "success"。未知、过时、跨会话、冲突或过大的结果都会被拒绝。

角色的回复缺少最初几个词。 那些词很可能匹配了一个保留的前导模式。检查 保留模式 列表——尤其是视觉标签，它们是后跟冒号的常见英文单词。

动作和语音不同步。 语义项目可以共享一个 logical_turn_id，但它们不携带词级偏移。见 顺序保证.

一个前导 ||| 序列从回复中消失了。 叙事设计处于活动状态，且正在消耗前导索引前缀。避免以一个整数后跟三个竖线开始回复。

---

相关页面

• 轮次生命周期和消息排序 ——输出如何传递，以及你可以依赖的顺序
• model-output ——规范 v2 封装和项目字段
• action-response ——旧版和兼容性投影
• 连接 API ——能力、工具、限制和拓扑约束
• action-result ——返回关联的客户端执行反馈