打断智能体

与智能体互动期间，你可能需要打断智能体发言来开启新一轮对话。声网对话式 AI 引擎支持通过以下两种方式打断智能体：

• 语音打断：系统根据用户的语音输入自动判断并打断智能体说话。
• 手动打断：通过调用 RESTful API 或客户端组件 API 主动发起打断请求，实现点击按钮或发送特定命令来打断智能体。

本文介绍打断智能体的实现方式。

语音打断

声网对话式 AI 引擎支持开启优雅打断功能，开启后，用户与智能体互动时，支持根据用户的音频输入自动打断说话中的 AI 智能体并快速响应，实现自然过渡和流畅对话。

信息

优雅打断为增值服务，开启后会收取费用，详见计费说明。

优雅打断功能默认关闭，你需要在调用 POST 创建对话式智能体时，设置 advanced_features.enable_aivad 为 true，开启优雅打断。以 curl 为例：

请求示例

Bash

curl --request post \
  --url https://api.agora.io/cn/api/conversational-ai-agent/v2/projects/:appid/join \
  --header 'Authorization: Basic <credentials>' \
  --data '
{
  "name": "unique_name",
  "properties": {
    "channel": "channel_name",
    "token": "token",
    "agent_rtc_uid": "0",
    "remote_rtc_uids": [
      "*"
    ],
    "enable_string_uid": false,
    "idle_timeout": 120,
    // highlight-start
    "advanced_features": {
      "enable_aivad": true
    },
    // highlight-end
    "llm": {
      "url": "https://api.minimax.chat/v2/text/chatcompletion_v2",
      "api_key": "xxx",
      "system_messages": [
        {
          "role": "system",
          "content": "You are a helpful chatbot."
        }
      ],
      "greeting_message": "您好，有什么可以帮您？",
      "failure_message": "抱歉，我无法回答这个问题。",
      "max_history": 32,
      "params": {
        "model": "abab6.5s-chat",
        "max_token": 1024,
        "userName": "Tomas"
      }
    },
    "asr": {
      "language": "zh-CN"
    },
    "tts": {
      "vendor": "minimax",
      "params": {
        "group_id": "xxxx",
        "key": "xxxx",
        "model": "speech-01-turbo",
        "voice_setting": {
          "voice_id": "female-shaonv",
          "speed": 1,
          "vol": 1,
          "pitch": 0,
          "emotion": "happy"
        },
        "audio_setting": {
          "sample_rate": 16000
        }
      },
      "skipPatterns": [
        1
      ]
    }
  }
}
'

响应示例

请求成功时返回 200 状态码，响应体如下：

JSON

{
  "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
  "create_ts": 1737111452,
  "status": "RUNNING"
}

手动打断

声网对话式 AI 引擎支持通过调用 RESTful API 或客户端组件 API 主动发起打断请求，从而实现点击按钮或发送特定命令来打断智能体。

方案一：调用 RESTful API

你可以调用 POST 打断智能体接口主动发起打断请求。

请求示例

以 curl 为例：

Bash

curl --request post \
  --url https://api.agora.io/cn/api/conversational-ai-agent/v2/projects/:appid/agents/:agentId/interrupt \
  --header 'Authorization: Basic <credentials>' \
  --data '{}'

响应示例

请求成功时返回 200 状态码，响应体如下：

JSON

{
  "agent_id": "1NT29XxxxxxxxxELWEHC8OS",
  "channel": "test_channel",
  "start_ts": 1744877089
}

方案二：调用客户端组件 API

声网提供一套灵活可扩展、标准化的对话式 AI 引擎客户端组件（以下简称组件）。该组件支持 iOS、Android、Web 平台，封装了多个场景化 API，你只需要调用这些 API 即可结合声网实时互动 (RTC) SDK 和实时消息 (RTM) SDK 的能力实现以下功能：

• 打断智能体
• 实时字幕
• 监听智能体相关事件
• 设置最佳音频参数 （仅支持 Android 和 iOS）

前提条件

开始前，请确保完成以下准备工作：

• 已集成 RTC v4.5.1 及以上版本 SDK，且在 App 中实现了基本的实时音视频功能、获取了相关设备的使用权限。请参考实现音视频互动。
• 已在控制台为项目启用 RTM 服务，并在 App 中实现了基本的实时消息功能。请参考实现收发消息。
• 已参考实现对话式智能体实现与智能体对话的基本逻辑。
• 确保 RTC 可用、RTM 已登录，且 RTC 和 RTM 实例的生命周期大于组件的生命周期。组件内部不负责维护 RTC，RTM 的初始化、生命周期以及鉴权/登录状态的逻辑。

集成组件

Android

将 convoaiApi 文件夹拷贝到你的项目中，并在后续调用组件 API 前引入组件。你可以前往组件结构了解各个文件作用。

convoaiApi

iOS

将 ConversationalAIAPI 文件夹拷贝到你的项目中，并在后续调用组件 API 前引入组件。你可以前往组件结构了解各个文件作用。

ConversationalAIAPI

Web

将 conversational-ai-api 文件拷贝到你自己的项目中，并在后续调用组件 API 前引入组件。你可以前往组件结构了解各个文件作用。

conversational-ai-api

初始化组件

为 RTC 和 RTM 实例创建配置对象，之后创建组件实例：

Android

Java

// 为 RTC 和 RTM 实例创建配置对象
val config = ConversationalAIAPIConfig(
    rtcEngine = rtcEngineInstance,
    rtmClient = rtmClientInstance,
    enableLog = true
)
// 创建组件实例
val api = ConversationalAIAPIImpl(config)

iOS

Swift

// 为 RTC 和 RTM 实例创建配置对象
let config = ConversationalAIAPIConfig(
    rtcEngine: rtcEngine, 
    rtmEngine: rtmEngine,
    enableLog: true
)
/// 创建组件实例
convoAIAPI = ConversationalAIAPIImpl(config: config)

Web

TypeScript

// 为 RTC 和 RTM 实例创建配置对象
ConversationalAIAPI.init({
    rtcEngine,
    rtmEngine,
    })

// 获取 API 实例（单例）
const conversationalAIAPI = ConversationalAIAPI.getInstance()

智能体加入频道

调用 POST 创建对话式智能体接口，并完成以下参数设置：

• advanced_features.enable_rtm: true —— （必选）启动 RTM 服务
• parameters.data_channel: "rtm" —— （必选）开启 RTM 数据传输通道
• parameters.enable_metrics: true —— （按需开启）接收智能体性能数据
• parameters.enable_error_message: true —— （按需开启）接收智能体错误事件

调用成功后，智能体会加入指定 RTC 频道，用户可以开始与智能体互动。

打断智能体

调用 interrupt 方法，打断智能体。

Android

Kotlin

api.interrupt("agentId") { error -> /* ... */ }

iOS

Swift

convoAIAPI.interrupt(agentUserId: "\(agentUid)") { error in
    if let error = error {
        print("打断失败: \(error.message)")
    } else {
        print("打断成功")
    }
}

Web

TypeScript

await conversationalAIAPI.interrupt(`${agent_rtc_uid}`)

销毁组件实例

结束 AI 对话场景后或关闭 App 前，你需要销毁组件实例，以释放组件的所有资源。

Android

Kotlin

api.destroy()

iOS

Swift

convoAIAPI.destroy()

Web

TypeScript

conversationalAIAPI.destroy()

参考信息

示例项目

声网提供了开源的示例项目供你参考，你可以前往下载或查看其中的源代码。

Conversational-AI-Demo

组件结构

客户端组件文件夹的结构和各文件作用如下：

信息

以下文件和文件夹即为集成客户端组件所需全部内容，无需拷贝其他文件。

Android

• IConversationalAIAPI.kt — API 接口及相关数据结构和枚举
• ConversationalAIAPIImpl.kt — ConversationalAI API 主要实现逻辑
• ConversationalAIUtils.kt — 工具函数与事件回调管理
• subRender/
  • v3/ — 字幕部分模块
    • TranscriptionController.kt — 字幕控制器
    • MessageParser.kt — 消息解析器

iOS

• ConversationalAIAPI.swift — API 接口及相关数据结构和枚举
• ConversationalAIAPIImpl.swift — ConversationalAI API 主要实现逻辑
• Transcription/
  • TranscriptionController.swift — 字幕控制器

Web

• index.ts — API 类
• type.ts — API 接口及相关数据结构和枚举
• utils/index.ts — API 工具函数
• utils/events.ts — 事件管理类，可以拓展该类以轻松实现事件监听和播报
• utils/sub-render.ts — 字幕部分模块

API 参考

RESTful API

• POST 创建对话式智能体
• POST 打断智能体

客户端组件 API

Android

• interrupt
• destroy

iOS

• interrupt
• destroy

Web

• interrupt
• destroy