动作

配置语义动作或关联客户端工具，处理带类型输出，返回执行结果，并保留旧版 Web SDK 行为。

使用 Convai Web SDK 接收语义动作，或启用相关联的客户端执行工具。你的应用仍需负责授权、执行、调度以及副作用安全。

本页上的 v2 API 描述的是一个候选实现。它们并不能证明该功能已在生产环境中可用，或已在已发布的 @convai/web-sdk 软件包中可用。在采用这些类型之前，请先确认已安装的软件包导出了这些类型。

在连接时配置语义动作

const client = useConvaiClient({
  apiKey: '...',
  characterId: '...',
  actionConfig: {
    // 角色可以发出的动作名称
    actions: ['Move To', 'Pick Up', 'Drop', 'Follow', 'Wave', 'Attack'],

    // 场景中角色可以作用的对象
    objects: [
      { name: 'sword',  description: '地上的一把锋利钢剑' },
      { name: 'chest',  description: '角落里一个木制宝箱' },
      { name: 'torch',  description: '墙上的一支燃烧火把' },
    ],

    // 机器人可以引用或作用的其他角色
    characters: [
      { name: 'Player', bio: '当前用户' },
      { name: 'Guard',  bio: '附近的守卫 NPC' },
    ],

    // 可选：角色开始时关注的对象
    current_attention_object: 'sword',
  },
});

规则：

• 动作, 对象以及 characters 为本次会话定义语义动作能力。
• current_attention_object 必须与 objects[].name 中的条目匹配。
• 如果可用动作或对象集合发生变化，请使用更新后的 actionConfig.

---

接收旧版 actionResponse

订阅 actionResponse 兼容性事件。忽略 capabilities 的连接会接收旧版语义动作；动作协议 v2 也可以通过此事件投影相关联的工具调用。导入 ActionResponseEvent 来自 SDK，并为回调添加类型注解，因为事件发射器接受字符串事件名。

import type { ActionResponseEvent } from '@convai/web-sdk/core';

client.on('actionResponse', ({ actions }: ActionResponseEvent) => {
  // 这个忽略 capabilities 的连接会接收 ConvaiAction 值。
  // 空数组是有效的无动作响应
  for (const action of actions) {
    dispatch(action.name, action.target);
  }
});

• 数组顺序会被保留，但 SDK 不会执行或调度动作。
• 目标 是可选的；某些动作（例如 "Wave"）没有目标。
• 空 动作 数组是有效的无动作结果。
• 当选择模型输出 v2 时，SDK 会抑制此兼容性事件。请订阅 modelOutput 改为此项。

---

处理带参数的语义动作

具有 目标 是 参数化的动作：角色会作用于 时 某个特定对象或角色，而不是执行一个简单手势。基础动作名称来自 actionConfig.actions[]，目标则解析为来自 actionConfig.objects[] 或 actionConfig.characters[].

import type { ConvaiAction } from '@convai/web-sdk/core';

function handleAction(action: ConvaiAction) {
  if (action.target) {
    // 参数化："Move To" → "chest"，"Follow" → "Player"
    moveCharacterTo(action.name, action.target);
  } else {
    // 简单："Wave"、"Dance"
    playAnimation(action.name);
  }
}

client.on('actionResponse', ({ actions }) => actions.forEach(handleAction));

如果用户说 “pick up the sword and give it to the guard”，一次轮次可以发出：

{ "actions": [
  { "name": "Move To", "target": "sword" },
  { "name": "Pick Up", "target": "sword" },
  { "name": "Move To", "target": "Guard" },
  { "name": "Drop",    "target": "Guard" }
] }

关键点

• Convai 会在投影之前校验非空语义动作目标是否与 actionConfig.objects[] 和 actionConfig.characters[] 匹配。你的应用仍必须为请求的效果进行授权。
• 同一个基础动作可以根据角色的决定，既以参数化形式出现，也以简单形式出现（"Wave" 与 "Wave" → "Player"）；应根据是否存在 目标进行分支，而不是根据动作名称。
• 来自 updateSceneMetadata 的场景元数据仅用于描述，不会作为 目标 出现 — 请将任何可交互的内容提升到 actionConfig.objects.

---

更新运行时动作上下文

使用 updateContext告诉角色玩家当前正在看着哪个对象。角色会用它来解析“它”“那个”“这里”。

// 玩家将焦点移到宝箱上 — 静默更新
client.updateContext({
  current_attention_object: 'chest',
  run_llm: 'false',
});

// 更新注意对象并让角色响应
client.updateContext({
  text: '玩家现在正在看向杠杆。',
  current_attention_object: 'lever',
  run_llm: 'auto',
});

// 清除注意对象
client.updateContext({
  current_attention_object: '',
  run_llm: 'false',
});

current_attention_object 必须与 actionConfig.objects[].name.

---

更新描述性的场景上下文

使用 updateSceneMetadata 用于角色应当知道的环境变化。这仅仅是 描述性的 — 它不会添加新的动作目标。

client.updateSceneMetadata([
  { name: 'fog',  description: '浓雾已笼罩，能见度很低' },
  { name: 'rain', description: '外面正下着大雨' },
]);

如果角色需要对某物采取行动，它必须位于 actionConfig.objects.

---

触发角色响应

使用 sendTriggerMessage ，以便在没有用户输入的情况下让角色说话并行动——用于脚本事件或过场动画。

// 在 Convai 仪表板中定义的命名触发器
client.sendTriggerMessage('greet_player');

// 带自定义指令的触发器
client.sendTriggerMessage('pickup_item', 'Pick up the sword and hand it to the player.');

---

语义动作示例

const client = useConvaiClient({
  apiKey: '...',
  characterId: '...',
  actionConfig: {
    actions: ['Move To', 'Pick Up', 'Drop', 'Follow'],
    objects: [
      { name: 'apple',  description: '木箱上的一个绿色苹果' },
      { name: 'basket', description: '玩家附近的一个藤篮' },
    ],
    characters: [{ name: 'Player', bio: '当前用户' }],
    current_attention_object: 'apple',
  },
});

client.on('actionResponse', ({ actions }) => {
  for (const { name, target } of actions) {
    console.log(`[ACTION] ${name}${target ? ` → ${target}` : ''}`);
    // 例如："Move To → apple"、"Pick Up → apple"、"Drop → basket"
  }
});

// 玩家在 UI 中选择藤篮
client.updateContext({
  current_attention_object: 'basket',
  run_llm: 'false',
});

// 玩家说“把那个放进篮子里”
// 角色可以建议：Move To apple → Pick Up apple → Move To basket → Drop apple

---

启用 v2 客户端工具

客户端工具会添加带类型的参数和相关联的结果循环。角色的 启用 Agentic 操作 切换必须开启，而且所选模型/提供方必须支持原生函数调用。如果该切换从未持久化过，拥有已保存旧版 Character Actions 的角色会继承启用状态；没有已保存旧版动作的角色在模型输出 v2 下默认为关闭。显式关闭设置始终优先。SDK 不提供提供方支持矩阵，也不提供 actionsEnabled 配置字段。

省略 capabilities 会保留旧版 v1 合约。请显式启用，并在工具声明变更时重新连接：

const client = useConvaiClient({
  apiKey: '...',
  characterId: '...',
  capabilities: {
    actionProtocolVersion: 2,
    modelOutputVersion: 2,
    botLlmTextMode: 'legacy',
  },
  actionConfig: {
    actions: [],
    objects: [],
    characters: [],
    tools: [{
      name: 'open_training_record',
      description: '在用户确认后打开一条训练记录。',
      inputSchema: {
        type: 'object',
        properties: { recordId: { type: 'string' } },
        required: ['recordId'],
      },
    }],
  },
});

候选服务要求一个以对象为根的 inputSchema。仅 type, properties以及 required 在根级别被接受；支持的约束可以在属性模式中使用。

对于共享、已加入或多角色会话，候选连接会拒绝 v2 或原始文本请求。 /connect 响应必须回显所请求的 v2 或原始选择。SDK 会拒绝 v2/原始降级或未请求的升级；对于明确的 v1 或旧版选择，它会容忍省略回显。

处理规范输出

使用 modelOutputVersion: 2，使用 modelOutput 作为规范事件。SDK 会抑制旧版 actionResponse 事件在此模式下发生，以免同一操作被处理两次。

import type {
  ActionResult,
  ModelOutputMessage,
  ModelOutputProtocolError,
  ModelOutputToolCallItem,
  ServerResponse,
} from '@convai/web-sdk/core';

client.on('modelOutput', (output: ModelOutputMessage) => {
  for (const item of output.items) {
    if (item.type === 'message') renderMessage(item);
    if (item.type === 'semantic_action') handleSemanticAction(item);
    if (item.type === 'tool_call') void handleToolCall(item);
  }
});

client.on(
  'modelOutputProtocolError',
  (error: ModelOutputProtocolError) => {
    console.error(error.code, error.message);
  },
);

async function handleToolCall(call: ModelOutputToolCallItem) {
  let result: ActionResult;

  try {
    // 由应用定义：在此验证权限并请求确认。
    const output = await runAuthorizedTool(call.name, call.arguments);
    result = { id: call.id, status: 'completed', output };
  } catch (error) {
    result = {
      id: call.id,
      status: 'error',
      error: {
        message: error instanceof Error ? error.message : '工具失败',
      },
    };
  }

  client.sendActionResult(result);
}

client.on('serverResponse', (response: ServerResponse) => {
  if (response.event_type !== 'action-result') return;
  console.log(response.status, response.extras?.tool_call_id);
});

sendActionResult() 返回 void. 它会验证本地载荷并发送一个 action-result；成功返回并不等同于服务器确认。请监听 serverResponse 并检查 status, message, extras.tool_call_id以及 extras.idempotent.

会话准备就绪后，这个方法可与任一 SDK 传输方式配合使用。可选的 sendUserTextMessage(text, { logicalTurnId }) 关联值当前由 LiveKit/WebRTC 会话携带，并限制为 128 UTF-8 字节。

确认并不是排序屏障；规范续接输出可能会先到达。请通过调用与输出标识符来关联两者，而不是按到达顺序。

Convai 在接受结果后可以继续同一个逻辑轮次。可能会有多个调用同时悬而未决，因此不要假设顺序执行。SDK 会保留条目顺序并丢弃重复的 output_id，但它不会维护待处理调用注册表，不会在不同封装之间去重工具调用 ID，不会重试结果，也不保证恰好一次执行。这些控制请放在你的应用中。相同结果的重试会被幂等接受；冲突的重试会被拒绝。

将 ModelOutputMessage.raw 视为仅用于诊断的文本。请渲染或执行已验证的 items 投影。未知或格式错误的条目会导致整个封装通过 modelOutputProtocolError.

选择 botLlmTextMode: 'raw' 会将现有的 bot-llm-text 聊天流切换为在动作解析前对提供方可见的文本。SDK 没有单独的原始文本事件；这些片段会出现在 ChatMessage 通过 messagesChange更新中。它不是结构化的工具调用流，原始片段的传递可能失败，而规范解析仍会继续。不要从聊天文本中解析或执行动作。

候选限制

限制	值
每个连接的工具数	32
工具名称 / 描述	64 / 1,024 characters
序列化输入模式 / 模式深度	16 KiB / 8
序列化参数 / 结果	32 KiB / 64 KiB
工具调用 ID / 逻辑轮次 ID	1–256 字符 / 128 UTF-8 字节
未完成调用 / 续接轮次	8 / 8
默认结果超时	60 seconds

这些是候选服务限制，而不是 SDK 端调度保证。

---

API 参考

actionConfig 连接选项

字段	类型	说明
动作	string[]	角色可以发出的动作名称
对象	{ name, description }[]	场景中的对象
characters	{ name, bio }[]	其他角色
current_attention_object	string?	初始关注对象
tools	ClientToolDeclaration[]?	v2 客户端工具；需要显式动作协议 v2

capabilities 连接选项

字段	类型	省略后的行为
actionProtocolVersion	1 | 2	动作协议 v1
modelOutputVersion	1 | 2	旧版输出消息
botLlmTextMode	"legacy" | "raw"	旧版过滤文本

actionResponse 事件

import type {
  ActionResponseEvent,
  ConvaiAction,
  ConvaiToolCall,
} from '@convai/web-sdk/core';

client.on('actionResponse', ({ actions }: ActionResponseEvent) => { ... });

类型	字段	说明
ActionResponseEvent	actions: Array<ConvaiAction | ConvaiToolCall>	有序兼容性投影；空表示无动作
ConvaiAction	name: string	来自 actionConfig.actions[]
ConvaiAction	target?: string	参数化目标——来自 actionConfig.objects[] / characters[]的名称；简单动作则省略
ConvaiToolCall	kind: "tool_call", id: string	v2 兼容性调用标识。
ConvaiToolCall	arguments: JsonObject	已验证的调用参数；在执行前为其授权。

sendActionResult(result)

返回值 void 在本地验证和传输发布之后。

字段	类型	必需	说明
ID	字符串	是	来自 工具调用.
status	"completed" | "error" | "cancelled"	是	终态客户端结果。
output	JsonValue	否	纯粹、有限、无循环的 JSON 结果数据。
错误	JsonValue	否	纯粹、有限、无循环的 JSON 失败详情。不得与 "completed".
characterSessionId	字符串	否	会话覆盖；当前角色会话在可用时会自动发送。

updateContext 注意

字段	类型	说明
文本	string?	可选上下文文本
模式	"append" | "replace" | "reset"	如何应用文本
run_llm	"true" | "false" | "auto"	是否触发响应
current_attention_object	string?	新的关注对象，或 "" 用于清除

updateSceneMetadata(items)

字段	类型	说明
items	{ name, description }[]	描述性的场景元素

sendTriggerMessage(triggerName?, triggerMessage?)

以编程方式触发角色响应。两个参数都是可选的。

相关参考

连接 API客户端到服务器消息