> 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/cha-jian-yu-ji-cheng/convai-unity-sdk/scripting-reference/convaimanager-api.md).

# ConvaiManager API

场景管理器组件所有公共成员的参考文档，涵盖连接控制、门面访问、玩家正在与谁交谈以及服务发现。

`ConvaiManager` 是 Convai Unity SDK 的主要脚本入口。它负责初始化运行时、管理房间连接、提供 `Events`, `Audio`和 `Transcripts` 门面，并通过类型化访问器提供对底层服务的访问。所有脚本交互都从这里开始。

**访问方式：** `ConvaiManager.ActiveManager` （单例）

```csharp
var manager = ConvaiManager.ActiveManager;
if (manager == null)
{
    Debug.LogError("ConvaiManager not found in scene. Add it via GameObject > Convai > Setup Required Components.");
    return;
}
```

{% hint style="warning" %}
`ActiveManager` 如果场景中不存在 `null` 则返回 `ConvaiManager` ，或者它尚未完成启动。在使用前务必进行 null 检查，尤其是在可能于管理器初始化之前调用 `OnEnable` 的组件中。
{% endhint %}

***

### 状态属性

| 属性               | 类型     | 说明                                 |
| ---------------- | ------ | ---------------------------------- |
| `IsBootstrapped` | `bool` | 静态属性。运行时完成初始启动后为 True，此时可以安全访问各门面。 |
| `IsInitialized`  | `bool` | 启动完成且事件中心可用时为 True。                |
| `IsConnected`    | `bool` | 房间会话处于 `Connected` 状态时为 True。      |

***

### 门面访问器

| 属性            | 类型                  | 引用                                                                                                                                                                                                                                                 |
| ------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Events`      | `ConvaiEvents`      | [会话事件](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/scripting-reference/session-events.md), [角色事件](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/scripting-reference/character-events.md) |
| `Audio`       | `ConvaiAudio`       | [音频 API](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/scripting-reference/audio-api.md)                                                                                                                               |
| `Transcripts` | `ConvaiTranscripts` | [转录 API](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/scripting-reference/transcript-api.md)                                                                                                                          |

***

### 所有权属性

| 属性                            | 类型                               | 说明                               |
| ----------------------------- | -------------------------------- | -------------------------------- |
| `Characters`                  | `IReadOnlyList<ConvaiCharacter>` | 此管理器当前拥有的所有 `ConvaiCharacter` 实例 |
| `Player`                      | `ConvaiPlayer`                   | 此管理器拥有的 `ConvaiPlayer` 实例        |
| `ActiveConversationCharacter` | `ConvaiCharacter`                | 当前设为对话目标的角色；可能为 `null`           |
| `ConversationMode`            | `ConvaiManagerConversationMode`  | 为此管理器配置的对话模式                     |
| `ActiveConversationInputMode` | `ConversationInputMode`          | 当前生效的运行时对话输入模式                   |
| `PushToTalkKey`               | `KeyCode`                        | 当模式为以下值时，用于按键通话的键码： `PushToTalk` |

### `ConvaiManagerConversationMode` 枚举

| 值                     | 说明                                    |
| --------------------- | ------------------------------------- |
| `UseRoomDefaults` (0) | 使用管理器的 `TurnTakingOptions` 中配置的对话输入模式 |
| `HandsFree` (1)       | 设置免按键通话（LocalAudio）模式，覆盖房间默认设置        |
| `PushToTalk` (2)      | 设置按键通话模式，覆盖房间默认设置                     |

***

### 房间操作

### `ConnectAsync`

```csharp
// 简单连接——使用场景配置
IConvaiOperation<RoomSession> ConnectAsync(CancellationToken ct = default)

// 使用运行时覆盖设置进行连接
IConvaiOperation<RoomSession> ConnectAsync(RoomSessionConnectOptions options, CancellationToken ct = default)
```

成功时返回一个 `RoomSession` 。有关使用模式，请参阅 [操作与流类型](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/scripting-reference/operation-and-stream-types.md) 和 [异步模式](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/scripting-reference/async-patterns.md) 。

#### `RoomSessionConnectOptions` 字段

将其传递给第二个重载，以在连接时覆盖运行时行为。

| 字段                               | 类型                                    | 说明                                                                                                                                                                                  |
| -------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TurnTaking`                     | `TurnTakingOptions`                   | 覆盖此会话的轮次切换配置。有关完整字段参考，请参阅 [轮次切换模式](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/core-concepts/turn-taking-modes.md) 。                                  |
| `EndUserId`                      | `string`                              | 覆盖此会话的最终用户 ID（供长期记忆使用）                                                                                                                                                              |
| `CharacterSessionId`             | `string`                              | 可选的会话 ID，作用域限于此显式的最终用户连接请求。当存在最终用户 ID 时，优先使用此字段，而不是角色自身的 `ConvaiCharacter.CharacterSessionId` 字段。                                                                                   |
| `EndUserMetadata`                | `IReadOnlyDictionary<string, object>` | 最终用户的附加元数据                                                                                                                                                                          |
| `ActionConfigOverride`           | `ConvaiActionConfig`                  | 覆盖此会话的动作配置                                                                                                                                                                          |
| `ActionDefinitionsOverride`      | `List<ConvaiActionDefinition>`        | 覆盖为此会话注册的动作定义                                                                                                                                                                       |
| `SharedSessionKey`               | `string`                              | 可选的共享会话密钥，用于将多人参与者分组到同一房间。请参阅 [连接 API 参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/multi-character-sessions/connection-api-reference.md). |
| `RoomSessionId`                  | `string`                              | 加入现有房间时使用的持久化多角色房间标识符。通常应通过 `MultiCharacterJoinOptions` 进行设置，而不是直接设置。                                                                                                               |
| `JoinExistingMultiCharacterRoom` | `bool`                                | 选择无拓扑的人类参与者加入方式，而不是构建并发送参与者列表。                                                                                                                                                      |
| `MaxNumParticipants`             | `int`                                 | 共享会话的可选参与者人数上限。                                                                                                                                                                     |

```csharp
var options = new RoomSessionConnectOptions
{
    EndUserId = currentUser.Id,
    EndUserMetadata = new Dictionary<string, object>
    {
        ["department"] = "Engineering",
        ["cohort"]     = "2025-Q2"
    }
};

var result = await manager.ConnectAsync(options, destroyCancellationToken);
if (!result.IsSuccessful)
    Debug.LogError($"Connect failed: {result.Error.Message}");
```

### `DisconnectAsync`

```csharp
IConvaiOperation<Unit> DisconnectAsync(CancellationToken ct = default)
```

正常断开房间会话。会话达到以下状态时操作完成： `Disconnected`.

***

### 对话控制

| 方法                                                                                          | 返回                       | 说明                                                                    |
| ------------------------------------------------------------------------------------------- | ------------------------ | --------------------------------------------------------------------- |
| `SetConversationInputModeAsync(ConversationInputMode mode, CancellationToken ct = default)` | `IConvaiOperation<Unit>` | 在运行时切换房间的对话输入模式                                                       |
| `StartListening()`                                                                          | `void`                   | 开始麦克风采集。此方法是以下方法的快捷方式： `Audio.StartListeningAsync()` 并使用默认设备。         |
| `ToggleMicMute()`                                                                           | `bool`                   | 切换麦克风静音状态。返回新的静音状态。                                                   |
| `EnableAudioAndStartListening()`                                                            | `void`                   | 调用 `Audio.EnableAudioPlayback()` 然后开始聆听。在 WebGL 上进行任何音频交互之前，必须先调用此方法。 |

***

### 直接 C# 事件

`ConvaiManager` 除可通过以下方式访问的强类型事件中心外，还提供三个直接 C# 事件： `Events`。如果只需轻量级的会话状态通知，而不需要完整的事件中心或中继器设置，请订阅这些事件。

| 事件               | 签名                     | 触发时机                |
| ---------------- | ---------------------- | ------------------- |
| `OnConnected`    | `Action`               | 会话达到 `Connected`    |
| `OnDisconnected` | `Action`               | 会话达到 `Disconnected` |
| `OnError`        | `Action<SessionError>` | 会话发生错误              |

如需更丰富的会话状态数据（转换上下文、参与者变更、空闲警告），请使用 `ConvaiSessionEventRelay` 或 `ConvaiManager.ActiveManager.Events`。上述直接事件有意保持精简，仅涵盖连接和错误。

***

### 所有权管理

使用这些方法和属性来控制管理器拥有哪些角色和玩家、哪些角色会加入下一次房间连接，以及房间初始打开时使用哪个角色。

| 成员                                                                | 说明                                                                                                                                                                                             |
| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SetInitialCharacter(ConvaiCharacter character)`                  | 选择房间连接时首先发言的角色。这是初始化设置，而非对话引导：它决定对话从何处开始；如果在房间已连接时更改此设置，则会排队等待重新连接，而不会改变当前对话。通常可以不设置：场景顺序中的第一个角色会先发言。要在正在运行的房间中改变对话对象，请使用 `TalkTo`.                                                            |
| `InitialCharacter`                                                | `ConvaiCharacter`的读取端。 `SetInitialCharacter`. `null` （未明确选择任何对象时）。                                                                                                                             |
| `TalkTo(ConvaiCharacter character)`                               | 在包含多个角色的实时房间中，将对话目标设为一个角色。可随时安全调用；如果房间不包含多个角色，或指定角色不在房间中，则不会执行任何操作。请参阅 [对话目标设定](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/conversation-targeting.md). |
| `AddressedCharacter`                                              | `ConvaiCharacter`。当前玩家正在交谈的角色；在房间创建前后均可解析。聊天字段标签应绑定到此角色，切勿绑定到玩家当前视线所及的对象。                                                                                                                      |
| `ConversationAvailability`                                        | `ConvaiConversationAvailability`。玩家当前是否可以与 `AddressedCharacter` 交谈。可用值： `NoCharacter`, `Offline`, `Connecting`, `Preparing`, `Ready`, `Answering`, `Unavailable`.                              |
| `ConversationAvailability.CanAcceptPlayerInput()`                 | 在 `ConvaiConversationAvailability`上的扩展方法。返回 `true` 表示值为 `Ready` 或 `Answering` ——这两种状态是仅有的可接受消息的状态。应依据此方法启用或禁用聊天输入框和麦克风按钮，而不是依据 `IsConnected`.                                                  |
| `ConversationTargeting`                                           | `ConversationTargetingOptions`。用于调整自动对话目标设定（模式、范围、视角角度、切换边距、切换延迟）。绝不能为 `null`.                                                                                                                 |
| `SetCharactersToConnect(IEnumerable<ConvaiCharacter> characters)` | 选择下一次房间连接中包含的、由当前对象拥有的确切角色集合，并替换之前的选择。传入空集合会有意使下一次连接不包含有效角色列表。更改仅对下一次连接生效，不影响当前连接。                                                                                                             |
| `CharactersToConnect`                                             | `IReadOnlyList<ConvaiCharacter>`。由 `SetCharactersToConnect`设置的显式房间角色集合；当包含所有活动角色时则为空。此选择是一个确切集合，而不是待追加的列表——如果你想表达“还要加上这个角色”，请先阅读 `SetCharactersToConnect` 。                                    |
| `UseAllCharactersForConnection()`                                 | 恢复默认行为：下一次房间连接将包含所有由当前对象拥有且处于活动状态的场景角色。                                                                                                                                                        |
| `SetExplicitPlayer(ConvaiPlayer player)`                          | 将指定的 `ConvaiPlayer` 实例指定为受管理的玩家                                                                                                                                                                |
| `SetExplicitCharacters(IEnumerable<ConvaiCharacter> characters)`  | 用提供的集合替换受管理的角色列表                                                                                                                                                                               |
| `RefreshReferences()`                                             | 重新扫描场景中的 `ConvaiCharacter` 和 `ConvaiPlayer` 实例，以重建受管理的集合                                                                                                                                       |

#### 运行时生成的角色

场景加载后实例化的角色并不会在 `Instantiate` 返回的那一刻就能使用。管理器必须先接管该角色并注入服务，而这会在后续帧中完成。 `ConvaiCharacter.IsInjected` 会指示注入是否已完成；在此之前，该角色的对话和音频调用都不会生效。

生成角色后，调用 `RefreshReferences()` ；或者在管理器未自动扫描场景时调用 `SetExplicitCharacters` ，然后等待 `IsInjected` 变为 true 后再与其交互。

```csharp
using System;
using System.Threading.Tasks;
using Convai.Runtime.Components;
using UnityEngine;

public static class RuntimeCharacterSpawn
{
    public static async Task<ConvaiCharacter> SpawnAsync(GameObject prefab, Vector3 position)
    {
        ConvaiCharacter character = UnityEngine.Object
            .Instantiate(prefab, position, Quaternion.identity)
            .GetComponent<ConvaiCharacter>();

        ConvaiManager.ActiveManager.RefreshReferences();

        for (int frame = 0; frame < 120; frame++)
        {
            if (character != null && character.IsInjected) return character;
            await Task.Yield();
        }

        throw new InvalidOperationException(
            "The runtime character was not injected. Ensure an active ConvaiManager is in the scene.");
    }
}
```

SDK 在共享示例中提供了此模式，名为 `RuntimeCharacterSpawner` 。

***

### 服务访问器模式

对于需要直接访问内部服务的高级场景， `ConvaiManager` 公开了 12 个类型化的 `TryGet*` 访问器。成功时，每个访问器都会返回 `true` 并设置 `out` 参数；如果服务不可用，则返回 `false` 。

{% hint style="info" %}
优先使用 `Events`, `Audio`，以及 `Transcripts` 常见任务的门面属性。 `TryGet*` 访问器面向高级集成和自定义工具。
{% endhint %}

```csharp
if (manager.TryGetMicrophoneDeviceService(out var micService))
{
    var devices = micService.GetAvailableDevices();
    // populate device picker UI
}
```

| 方法                                                                  | 服务类型                             | 常见用例                                                                                                                                                             |
| ------------------------------------------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TryGetEventHub(out IEventHub)`                                     | `IEventHub`                      | 通过以下方式直接访问原始事件总线： `ConvaiEvents.Raw`；高级订阅                                                                                                                        |
| `TryGetRoomConnectionService(out IConvaiRoomConnectionService)`     | `IConvaiRoomConnectionService`   | 底层连接生命周期控制，包括 [多角色会话操作](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/multi-character-sessions/connection-api-reference.md) |
| `TryGetRoomAudioService(out IConvaiRoomAudioService)`               | `IConvaiRoomAudioService`        | 直接访问音频服务（绕过 `ConvaiAudio` 门面）                                                                                                                                    |
| `TryGetAgentRegistry(out IAgentRegistry)`                           | `IAgentRegistry`                 | 查询已注册的角色和玩家                                                                                                                                                      |
| `TryGetSettingsPanelController(out IConvaiSettingsPanelController)` | `IConvaiSettingsPanelController` | 以编程方式打开/关闭设置面板                                                                                                                                                   |
| `TryGetRuntimeSettingsService(out IConvaiRuntimeSettingsService)`   | `IConvaiRuntimeSettingsService`  | 读取和写入运行时设置（音量、麦克风设备等）                                                                                                                                            |
| `TryGetMicrophoneDeviceService(out IMicrophoneDeviceService)`       | `IMicrophoneDeviceService`       | 枚举可用的麦克风设备；构建设备选择器 UI                                                                                                                                            |
| `TryGetPermissionService(out IConvaiPermissionService)`             | `IConvaiPermissionService`       | 请求平台麦克风权限（Android、iOS）                                                                                                                                           |
| `TryGetNotificationService(out IConvaiNotificationService)`         | `IConvaiNotificationService`     | 从自己的脚本触发 SDK 通知                                                                                                                                                  |
| `TryGetPlayerInputService(out IPlayerInputService)`                 | `IPlayerInputService`            | 访问玩家输入状态和文本消息路由                                                                                                                                                  |
| `TryGetVisibleCharacterService(out IVisibleCharacterService)`       | `IVisibleCharacterService`       | 维护由自己的可见性逻辑通过以下方法添加的角色 ID 集合： `AddCharacter`/`RemoveCharacter`；供转录文本 UI 进行筛选和淡出处理                                                                                |
| `TryGetTransportProvider(out ITransportProvider)`                   | `ITransportProvider`             | 访问传输层，用于诊断或自定义传输场景                                                                                                                                               |

***

### SDK 版本

&#x20;`ConvaiSDK`  静态类会公开 SDK 版本，以便进行条件功能检查。

```csharp
using Convai.Application;

Debug.Log($"Convai SDK {ConvaiSDK.Version}");

// 将此值设为集成所支持的最低 SDK 版本。
const string MinimumSupportedVersion = "4.6.0";

if (ConvaiSDK.Version >= System.Version.Parse(MinimumSupportedVersion))
{
    // 可以安全使用该版本提供的 API
}
```

***

### 使用示例

### 示例 1 — 加载场景时连接并支持取消

一个工业安全模拟应用会在场景加载时连接到 Convai，并通过 `destroyCancellationToken` 将连接操作与组件的生命周期关联起来，因此如果场景在连接尝试期间卸载，操作会正常取消。

{% code title="SceneConnector.cs" %}

```csharp
using Convai.Runtime.Core.Async;
using Convai.Runtime.Facades;
using UnityEngine;

public class SceneConnector : MonoBehaviour
{
    private async void Start()
    {
        var manager = ConvaiManager.ActiveManager;
        if (manager == null) return;

        try
        {
            var session = await manager.ConnectAsync(destroyCancellationToken);
            Debug.Log($"Connected. Session: {session.RoomId}");
        }
        catch (ConvaiOperationException ex)
        {
            Debug.LogError($"Connect failed: {ex.Message}");
        }
        catch (System.OperationCanceledException) { /* scene unloaded */ }
    }
}
```

{% endcode %}

### 示例 2 — 进入触发区域时切换对话对象

某企业入职培训模拟应用的房间内有多个 AI 顾问。当学员走进某位顾问的区域时，使用 `TalkTo`.

{% code title="AdvisorZone.cs" %}

```csharp
using Convai.Runtime.Components;
using Convai.Runtime.Facades;
using UnityEngine;

public class AdvisorZone : MonoBehaviour
{
    [SerializeField] private ConvaiCharacter _advisor;

    private void OnTriggerEnter(Collider other)
    {
        if (!other.CompareTag("Player")) return;
        ConvaiManager.ActiveManager?.TalkTo(_advisor);
    }
}
```

{% endcode %}

### 示例 3 — 麦克风设备选择器 UI

某互动体验允许用户在会话开始前选择首选麦克风，并使用 `IMicrophoneDeviceService` 枚举可用设备。

{% code title="MicrophonePicker.cs" %}

```csharp
using Convai.Runtime.Facades;
using System.Linq;
using TMPro;
using UnityEngine;

public class MicrophonePicker : MonoBehaviour
{
    [SerializeField] private TMP_Dropdown _deviceDropdown;

    private void Start()
    {
        var manager = ConvaiManager.ActiveManager;
        if (manager == null || !manager.TryGetMicrophoneDeviceService(out var micService))
            return;

        var devices = micService.GetAvailableDevices();
        _deviceDropdown.ClearOptions();
        _deviceDropdown.AddOptions(devices.Select(d => d.Name).ToList());
    }
}
```

{% endcode %}

***

### 故障排查

| 症状                                  | 可能原因                                   | 解决方法                                                                                                                   |
| ----------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `ActiveManager` 返回 `null` ，可能是因为运行时 | `ConvaiManager` 不在场景中，或在引导程序完成前就访问了它   | 通过以下菜单添加： **GameObject > Convai > Setup Required Components**；使用前检查是否为 null；订阅 `OnConnected` 而不是在 `Awake` 或 `OnEnable` |
| `TryGet*` 返回 `false`                | 服务不可用，或管理器尚未完成引导                       | 调用前检查 `IsBootstrapped` ；在 `OnConnected` 触发后再调用                                                                         |
| `ConnectAsync` 一直处于 `Running` 状态    | API 密钥无效、网络不可达，或 `ConvaiSettings` 资源缺失 | 在 **Convai → 设置**中验证 API 密钥；使用超时 `CancellationToken` 以便显现故障                                                            |
| `RefreshReferences` 无法找到动态生成的角色     | 场景加载后实例化的角色不会被自动发现                     | 在实例化后调用 `RefreshReferences()` ，或使用 `SetExplicitCharacters()` 直接注册它们                                                    |

***

### 后续步骤

有关音频和麦克风脚本编写，请参阅 [音频 API](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/scripting-reference/audio-api.md)。有关 C# 中的连接状态和错误事件，请参阅 [会话事件](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/scripting-reference/session-events.md)。有关异步操作的使用模式，请参阅 [异步模式](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/scripting-reference/async-patterns.md).


---

# 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/cha-jian-yu-ji-cheng/convai-unity-sdk/scripting-reference/convaimanager-api.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.
