AI主动说话：主动调用 LLM 或 TTS

大语言模型 ( LLM ) 本身并不支持主动输出，需要通过开发者基于一定规则主动触发智能体说话，从而提升实时互动中的沉浸感。例如当用户5s中没有说话，则让智能体主动通过文本转语音 ( TTS ) 说一句话等。

AI Agent 主动说话的方式：

主动调用 LLM。本质上是模拟用户发起一条消息，从而实现基于上下文的智能体主动文字和语音输出。
主动调用 TTS。直接让智能体用语音说一段文本内容，通常是固定模式话术，例如“你好呀，欢迎使用 ZEGO AI Agent 服务”。

AI智能体说话时，可以设置优先级，从而实现不同的效果，通过设置两个参数（非必填）

Priority（High、Medium、Low）。
SamePriorityOption（ClearAndInterupt、Enqueue）。

前提条件

已参考快速开始完成基本流程。

使用方式

主动调用 LLM和主动调用 TTS章节的说明包含所有相关参数，但是示例代码仅演示必选参数使用方式。

主动调用 LLM

您可以调用 SendAgentInstanceLLM 接口，主动让 LLM 输出文本和语音。

调用 SendAgentInstanceLLM 时 AI Agent 服务端会拼接一个上下文，这个上下文由 3 部分组成：

放在最前面的是 SystemPrompt ，本次对话的临时智能体系统提示词。
放在中间的是之前的对话记录，使用的对话记录数量由 WindowSize 决定。
放在最后的部分是本接口中设置的 Text。

调用本接口传入的文本信息不会记录在会话历史消息中，也不会通过 RTC 房间消息下发。但 LLM 生成的回复会被记录在会话历史消息中并且会通过 RTC 房间消息下发。

接口参数如下：

参数	类型	是否必选	描述
AgentInstanceId	String	是	智能体实例的唯一标识，通过创建智能体实例接口的响应参数获取。
Text	String	是	发送给 LLM 服务的文本内容。
SystemPrompt	String	否	本次对话的临时智能体系统提示词。如果不填则使用注册智能体或者创建智能体实例时的 LLM 参数中的 `SystemPrompt`。
AddQuestionToHistory	Boolean	否	是否把问题加入到上下文。默认值为 `false`。
AddAnswerToHistory	Boolean	否	是否把答案加入到上下文。默认值为 `false`。
Priority	String	否	任务优先级，默认为 `Medium`。可选值： 1. `Low`：低优先级 2. `Medium`：中等优先级 3. `High`：高优先级
SamePriorityOption	String	否	相同优先级时的打断策略，默认为 `ClearAndInterrupt`。可选值： - `ClearAndInterrupt`：清空并打断 - `Enqueue`：排队等待，队列最大数量为 5

请求示例如下：

{
    "AgentInstanceId": "1907755175297171456",
    "Text": "今天天气怎么样？"
}

{
    "AgentInstanceId": "1907755175297171456",
    "Text": "今天天气怎么样？"
}

主动调用 TTS

您可以通过调用 SendAgentInstanceTTS 接口，主动让智能体用语音说一段文本内容。

调用本接口传入的文本消息，会根据 AddHistory 参数决定是否被记录在会话消息历史之中，作为上下文输入给 LLM，同时该消息还会通过 RTC 房间消息下发。

接口参数如下：

参数	类型	是否必选	描述
AgentInstanceId	String	是	智能体实例的唯一标识，通过创建智能体实例接口的响应参数获取。
Text	String	是	用于 TTS 的文本内容，最大不超过 300 个字符。
AddHistory	Boolean	否	是否将文本消息记录在会话消息历史之中，作为上下文输入给 LLM。默认值为 `true`。
Priority	String	否	任务优先级，默认为 `Medium`。可选值： 1. `Low`：低优先级 2. `Medium`：中等优先级 3. `High`：高优先级
SamePriorityOption	String	否	相同优先级时的打断策略，默认为 `ClearAndInterrupt`。可选值： - `ClearAndInterrupt`：清空并打断 - `Enqueue`：排队等待，队列最大数量为 5

请求示例如下：

{
    "AgentInstanceId": "1907780504753553408",
    "Text": "你好呀，欢迎使用 ZEGO AI Agent 服务。"
}

{
    "AgentInstanceId": "1907780504753553408",
    "Text": "你好呀，欢迎使用 ZEGO AI Agent 服务。"
}

场景调用示例

场景1：AI 播放欢迎语

希望在用户每次与 AI 开始语音或数字人对话时，AI 主动播报一句欢迎语。

确保用户已经拉到 Agent 实例的 RTC 流

监听拉流成功事件示例代码

(Android)监听拉流成功事件示例

// 创建引擎后设置事件处理器
engine.setEventHandler(new IZegoEventHandler() {
    @Override
    public void onPlayerStateUpdate(String streamID, ZegoPlayerState state,
                                  int errorCode, JSONObject extendedData) {
        super.onPlayerStateUpdate(streamID, state, errorCode, extendedData);
        if (errorCode != 0) {
            Log.d("Zego", "拉流状态出错: " + streamID);
            return;
        }
        // 监听拉流状态变化
        switch (state) {
            // !mark
            case PLAYING:
                Log.d("Zego", "拉流成功，可以调用接口播放欢迎语");
                break;
            case PLAY_REQUESTING:
                Log.d("Zego", "正在拉流: " + streamID);
                break;
            case NO_PLAY:
                Log.d("Zego", "拉流停止: " + streamID);
                break;
        }
    }
});

// 创建引擎后设置事件处理器
engine.setEventHandler(new IZegoEventHandler() {
    @Override
    public void onPlayerStateUpdate(String streamID, ZegoPlayerState state,
                                  int errorCode, JSONObject extendedData) {
        super.onPlayerStateUpdate(streamID, state, errorCode, extendedData);
        if (errorCode != 0) {
            Log.d("Zego", "拉流状态出错: " + streamID);
            return;
        }
        // 监听拉流状态变化
        switch (state) {
            // !mark
            case PLAYING:
                Log.d("Zego", "拉流成功，可以调用接口播放欢迎语");
                break;
            case PLAY_REQUESTING:
                Log.d("Zego", "正在拉流: " + streamID);
                break;
            case NO_PLAY:
                Log.d("Zego", "拉流停止: " + streamID);
                break;
        }
    }
});

通过接口调用开始播放欢迎语，有以下两种实现方式：

SendAgentInstanceLLM: 结合上下文，让 LLM 结合上下文播放播放欢迎语。

{
    "AgentInstanceId": "1907755175297171456",
    "Text": "请说一句欢迎语"
}

{
    "AgentInstanceId": "1907755175297171456",
    "Text": "请说一句欢迎语"
}

SendAgentInstanceTTS: 使用固定话术让 AI 播放欢迎语。

{
    "AgentInstanceId": "1907755175297171456",
    "Text": "hello啊"
}

{
    "AgentInstanceId": "1907755175297171456",
    "Text": "hello啊"
}

注意

若播放欢迎语时用户开始说话，则可以直接打断AI，并有概率导致AI无法播出欢迎语。若希望一定能让用户听到欢迎语，则可以设置:

Priority=High

以通过 SendAgentInstanceTTS 发欢迎语为例：

{
    "AgentInstanceId": "1907755175297171456",
    "Text": "hello啊",
    "Priority": "High"
}

{
    "AgentInstanceId": "1907755175297171456",
    "Text": "hello啊",
    "Priority": "High"
}

场景2:冷场时，AI 主动发言可被用户说话打断

用户和 AI 都没有说话时，希望 AI 主动发起话题，同时希望若 AI 发言时用户说话则以用户说话内容为主，即 AI 播报能被用户说话打断。则可直接调用 SendAgentInstanceLLM 或 SendAgentInstanceTTS 实现。

发起话题的内容方式有两种：

结合上下文，让 LLM 结合上下文输出一次主动发言。请求示例: 比如调用 SendAgentInstanceLLM 接口，text 为“现在用户一段时间没有说话了，请主动说一句话”

{
    "AgentInstanceId": "1907755175297171456",
    "Text": "现在用户一段时间没有说话了，请主动说一句话？",
    "Priority": "Medium"
}

{
    "AgentInstanceId": "1907755175297171456",
    "Text": "现在用户一段时间没有说话了，请主动说一句话？",
    "Priority": "Medium"
}

使用固定话术让 AI 说话。请求示例: 比如调用 SendAgentInstanceTTS 接口，text 为“你怎么不说话啦？”

{
    "AgentInstanceId": "1907755175297171456",
    "Text": "你怎么不说话啦？",
    "Priority": "Medium"
}

{
    "AgentInstanceId": "1907755175297171456",
    "Text": "你怎么不说话啦？",
    "Priority": "Medium"
}

场景3:触发关键节点，需要 AI 立刻播报并完成所有内容

例如，当发现已经到了 60s 的时间限制，不管此时用户和 AI 是否在说话，都需要立刻播报提醒用户。

此时除了配置 LLM 的提示词或 TTS 的内容外，需要额外配置：

Priority=High
SamePriorityOption=ClearAndInterrupt

请求示例: 比如调用 SendAgentInstanceTTS 接口，text 为“时间到了，请及时检查。”

{
    "AgentInstanceId": "1907755175297171456",
    "Text": "时间到了，请及时检查。",
    "Priority": "High",
    "SamePriorityOption": "ClearAndInterrupt"
}

{
    "AgentInstanceId": "1907755175297171456",
    "Text": "时间到了，请及时检查。",
    "Priority": "High",
    "SamePriorityOption": "ClearAndInterrupt"
}

场景4: AI 正在播报，需要在播报完当前内容之后，再播报额外内容

例如此时 AI 正在回复用户提问，希望在回答本次提问后，立刻让 AI 补充询问用户是否还有其他想法。

此时除了配置 LLM 的提示词或 TTS 的内容外，需要额外配置：

Priority=Medium
SamePriorityOption=Enqueue

请求示例: 比如调用 SendAgentInstanceTTS 接口，text 为“你有什么其他想法么？”

{
    "AgentInstanceId": "1907755175297171456",
    "Text": "你有什么其他想法么？",
    "Priority": "Medium",
    "SamePriorityOption": "Enqueue"
}

{
    "AgentInstanceId": "1907755175297171456",
    "Text": "你有什么其他想法么？",
    "Priority": "Medium",
    "SamePriorityOption": "Enqueue"
}