用 ElevenAgents 为 Unity NPC 添加语音

玩家现在可以走近 Unity 游戏中的角色，并直接与其交谈。新版 ElevenAgents Unity SDK 可将场景连接到 ElevenLabs 语音智能体。它通过玩家的麦克风收听，通过 AudioSource 播放智能体的语音，并通过 Conversation API 运行会话。

同一套代码可在 Editor、桌面端构建版本和 WebGL 中运行，iOS、Android 和 XR 目前处于 beta 阶段。

开始对话

会话需要你在 ElevenLabs 控制台创建的智能体 ID，其中包含提示词和音色。SDK 随附的 GettingStarted 示例中，角色周围的触发碰撞体会在玩家走入时开启会话，并在玩家离开时关闭会话：

private Conversation activeConversation;

private void OnTriggerEnter(Collider other) => _ = StartTalkingAsync();
private void OnTriggerExit(Collider other) => _ = StopTalkingAsync();

private async Awaitable StartTalkingAsync()
{
    var options = new ConversationOptions { AgentId = agentId };
    activeConversation = await Conversation.StartSessionAsync(options);
}

private async Awaitable StopTalkingAsync()
{
    if (activeConversation == null)
        return;
    await activeConversation.EndSession();
    activeConversation = null;
}

连接已打开且音频设备准备就绪后，StartSessionAsync 会返回，并会为构建目标选择合适的传输方式。如果会话已结束，EndSession 不会执行任何操作。

SDK 包含哪些内容

从角色发出的声音

默认情况下，智能体语音以 2D 方式播放。将自己的 AudioSource 作为 OutputAudioSource 传入，即可让语音从角色处发出。

GetOutputVolume() 会在所有平台返回智能体当前的音量级别，范围为 0 到 1。示例用它让立方体在说话时上下浮动，也可以用同样方式驱动嘴部动画。

一个智能体，多个角色

动态变量会填充智能体提示词和首条消息中的 {{mood}} 等占位符，因此每个角色在会话开始时都能发送自己的值。值可以是字符串、数字或布尔值。示例中，一个黄色快乐立方体和一个红色愤怒立方体共用同一个智能体：

var options = new ConversationOptions
{
    AgentId = agentId,
    OutputAudioSource = audioSource,
    DynamicVariables = new Dictionary<string, object>
    {
        ["color"] = "red",
        ["mood"] = "angry",
    },
};

如需进行更大的调整，可通过 Overrides 替换单次会话中智能体配置的一部分，例如首条消息或音色。每项覆盖设置都必须先在智能体的 安全设置中启用。

了解当前情况的角色

SendContextualUpdate 可在对话过程中告知智能体游戏事件，不会打断它，也不会添加玩家未说出的对话轮次：

activeConversation.SendContextualUpdate("The player picked up the cellar key.");

会在游戏中行动的角色

客户端工具可让智能体触发游戏代码。先在智能体设置中定义工具，再以相同名称注册处理程序：

activeConversation.RegisterTool<OpenDoorParams, string>("open_door", parameters =>
{
    DoorRegistry.Open(parameters.DoorId);
    return $"Door {parameters.DoorId} is open.";
});

SDK 使用 Newtonsoft Json 反序列化工具参数，并将处理程序返回的任何内容发送回智能体。处理程序可针对耗时任务返回 Awaitable，也可以抛出 ClientToolException 来告知智能体失败原因。

事件和控制

UserTranscriptReceived、AgentResponded、ModeChanged 和 Interrupted 等事件会在 Unity 主线程触发，因此可以直接据此更新 UI。相关方法包括通过 SendUserMessage 输入文本、通过 SetMicMuted 静音、SetVolume、获取用于可视化的频率数据，以及在会话中切换输入或输出设备。Unity SDK 文档列出了全部方法。

平台支持

SDK 会为每个目标选择传输方式。

• iOS 和 Android：开始会话前请求麦克风权限。
• WebGL：在 Publishing Settings 中启用 Use WebAssembly.Table。如果未启用，SDK 会使构建失败并提供操作说明。WebGL 为当前构建目标时，Play Mode 无法运行，因此请在桌面端目标上测试。
• WebGL 音频：语音通过 Web Audio API 播放，因此部分 AudioSource 设置（如混音器路由和多普勒效果）不会生效。WebRTC 会话会忽略 OutputAudioSource。

兼容性说明中列出了完整信息。

开始使用

1. 在 ElevenLabs 控制台中创建智能体。首次测试时，请在其 安全设置中关闭 身份验证，让游戏仅使用智能体 ID 即可连接。
2. 在 Unity 中，依次打开 Window > Package Manager > + > Install package from git URL，然后固定发布版本：https://github.com/elevenlabs/unity.git#v0.1.0
3. 导入 GettingStarted 示例，粘贴智能体 ID，然后按下 Play。

警告：发布前，请重新启用 身份验证。随后，自己的服务器会请求短期有效的 签名 URL，游戏会将其作为 SignedUrl 传入，而非 AgentId。切勿将 ElevenLabs API 密钥放入游戏构建版本中。

入门指南大约需要 10 分钟，最终可实现当你走近时由立方体向你问候。其他内容请查看 Unity SDK 文档，并通过 GitHub issues 提交 bug 和功能请求。