需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

监听智能体事件

更新时间不可用

了解对话式 AI 引擎中监听智能体事件相关内容的适用场景、配置步骤、实现要点和注意事项。

与对话式智能体进行实时互动时，你可能需要监听智能体相关事件来实现更丰富的功能。本文介绍如何在你的 App 中监听智能体相关事件。

技术原理

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

组件提供一系列回调，支持监听不同的智能体相关事件和信息：

  • onAgentStateChanged：通过接收 RTM presence 事件，监听智能体状态变化（静默/聆听/思考/说话）。可用于更新智能体 UI 或追踪对话流程。
  • onAgentInterrupted：通过接收 RTM message 事件，监听智能体打断事件。
  • onAgentMetrics：通过接收 RTM message 事件，监听智能体性能指标，包括 LLM 推理延迟、TTS 合成延迟等。可用于监控系统性能。
  • onAgentError：通过接收 RTM message 事件，监听智能体错误事件，例如智能体某模块（例如 LLM、TTS 等）发生错误。可用于错误监控、日志记录和实现优雅降级策略。

前提条件

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

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

实现步骤

集成组件

Maven (Maven)

在 Android 项目的 build.gradle 文件中添加如下依赖：

groovy
implementation 'io.agora.agents:agora-agent-client-toolkit:2.10.0'

源码集成 (源码集成)

将 convoaiApi 文件夹拷贝到你的项目中，并在后续调用组件 API 前引入组件。

agent-client-toolkit-kotlin

CocoaPods (CocoaPods)

在 Podfile 中添加如下依赖：

Ruby
pod 'agent-client-toolkit-swift', '2.10.0'

Swift Package Manager (Swift Package Manager)

在 Xcode 中添加如下 Package URL，并将版本指定为 tag 2.10.0：

Text
https://github.com/AgoraIO/agent-client-toolkit-swift.git

源码集成 (源码集成)

将 ConversationalAIAPI 文件夹拷贝到你的项目中，并在后续调用组件 API 前引入组件。

agent-client-toolkit-swift

Package Manager (Package Manager)

根据你的项目类型安装组件依赖。

  • Vanilla JS / TypeScript：

    Shell
    pnpm add agora-agent-client-toolkit@2.10.0

  • React：

    Shell
    pnpm add agora-agent-client-toolkit@2.10.0 agora-agent-client-toolkit-react@2.10.0

源码集成 (源码集成)

将 conversational-ai-api 文件夹拷贝到你的项目中，并在后续调用组件 API 前引入组件。

agent-client-toolkit-ts

信息

如果在 Android 或 iOS 项目中同时集成多个声网 SDK 时出现库冲突，请参考多 SDK 库冲突处理。

初始化组件

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

Kotlin
val config = ConversationalAIAPIConfig(
    rtcEngine = rtcEngine,
    rtmClient = rtmClient,
    renderMode = TranscriptRenderMode.Word,
    enableLog = true,
    enableRenderModeFallback = true
)

val api = ConversationalAIAPIImpl(config)

注册回调

调用 addHandler 方法，注册并实现智能体相关事件回调：

Kotlin
// 注册回调
api.addHandler(object : IConversationalAIAPIEventHandler {
    // 监听智能体状态变化
    override fun onAgentStateChanged(agentUserId: String, event: StateChangeEvent) {
        when (event.state) {
            AgentState.SILENT -> {
                updateAgentStatus("等待中...")
            }
            AgentState.LISTENING -> {
                updateAgentStatus("正在听...")
            }
            AgentState.THINKING -> {
                updateAgentStatus("思考中...")
            }
            AgentState.SPEAKING -> {
                updateAgentStatus("说话中...")
            }
            AgentState.UNKNOWN -> {
                Log.w("AgentState", "Unknown agent state: $event")
            }
        }
    }
    // 监听智能体打断事件
    override fun onAgentInterrupted(agentUserId: String, event: InterruptEvent) {
        // 智能体被打断，可以更新 UI 或记录日志
        Log.d("AgentInterrupt", "Agent $agentUserId interrupted at turn ${event.turnId}")
        // 可以在这里更新 UI，比如显示"对话已中断"
        showInterruptNotification()
    }
    // 监听智能体性能指标，用于监控和优化
    override fun onAgentMetrics(agentUserId: String, metric: Metric) {
        when (metric.type) {
            ModuleType.LLM -> {
                Log.d("Metrics", "LLM latency: ${metric.value}ms")
                // 可以记录 LLM 响应时间用于性能分析
            }
            ModuleType.TTS -> {
                Log.d("Metrics", "TTS latency: ${metric.value}ms")
                // 可以记录 TTS 合成时间
            }
            else -> {
                Log.d("Metrics", "${metric.type}: ${metric.name} = ${metric.value}")
            }
        }
    }
    // 监听智能体错误事件
    override fun onAgentError(agentUserId: String, error: ModuleError) {

        Log.e("AgentError", "Error in ${error.type}: ${error.message} (code: ${error.code})")

        when (error.type) {
            ModuleType.LLM -> {
                // LLM 错误，可能需要重试或降级处理
                showErrorMessage("AI处理出错，请稍后重试")
            }
            ModuleType.TTS -> {
                // TTS 错误，可能需要切换到文本模式
                showErrorMessage("语音合成出错")
            }
            else -> {
                // 其他错误类型
                showErrorMessage("系统错误: ${error.message}")
            }
        }
    }

    override fun onDebugLog(log: String) {
        // 处理调试日志
        if (BuildConfig.DEBUG) {
            Log.d("ConvoAI", log)
        }
        // 可以将日志发送到远程服务器进行问题诊断
    }
})

调用 addHandler 方法，注册并实现智能体相关事件回调：

Swift
// 让你的类遵循 ConversationalAIAPIEventHandler 协议
class ConversationViewController: UIViewController, ConversationalAIAPIEventHandler {

    // 实现协议方法
    func onAgentStateChanged(agentUserId: String, event: StateChangeEvent) {
        // 更新 UI 显示智能体当前状态
        DispatchQueue.main.async {
            self.updateAgentStatus(event.state)
        }
    }

    func onAgentInterrupted(agentUserId: String, event: InterruptEvent) {
        // 智能体被中断，可以更新 UI 或记录日志
        print("Agent \(agentUserId) interrupted at turn \(event.turnId)")
        DispatchQueue.main.async {
            self.showInterruptNotification()
        }
    }

    func onAgentMetrics(agentUserId: String, metrics: Metric) {
        // 监听智能体性能指标，用于监控和优化
        switch metrics.type {
        case .llm:
            print("LLM latency: \(metrics.value)ms")
            // 可以记录LLM响应时间用于性能分析
        case .tts:
            print("TTS latency: \(metrics.value)ms")
            // 可以记录TTS合成时间
        case .unknown:
            print("Unknown metric: \(metrics.name) = \(metrics.value)")
        }
    }

    func onAgentError(agentUserId: String, error: ModuleError) {
        // 监听智能体错误事件
        print("Error in \(error.type): \(error.message) (code: \(error.code))")

        DispatchQueue.main.async {
            switch error.type {
            case .llm:
                // LLM错误，可能需要重试或降级处理
                self.showErrorMessage("AI处理出错，请稍后重试")
            case .tts:
                // TTS错误，可能需要切换到文本模式
                self.showErrorMessage("语音合成出错")
            case .mllm:
                // MLLM错误
                self.showErrorMessage("多模态AI处理出错")
            case .unknown:
                // 其他错误类型
                self.showErrorMessage("系统错误: \(error.message)")
            }
        }
    }

    // 辅助方法，用于更新 UI 显示智能体当前状态
    private func updateAgentStatus(_ state: AgentState) {
        let (text, color): (String, UIColor) = {
            switch state {
            case .idle:
                return ("空闲", .gray)
            case .silent:
                return ("等待中...", .gray)
            case .listening:
                return ("正在听...", .blue)
            case .thinking:
                return ("思考中...", .orange)
            case .speaking:
                return ("说话中...", .green)
            case .unknown:
                return ("未知状态", .red)
            }
        }()

        statusLabel.text = text
        statusLabel.textColor = color
    }

    private func showInterruptNotification() {
        statusLabel.text = "对话已中断"
        statusLabel.textColor = .red
    }

    private func showErrorMessage(_ message: String) {
        let alert = UIAlertController(title: "错误", message: message, preferredStyle: .alert)
        alert.addAction(UIAlertAction(title: "确定", style: .default))
        present(alert, animated: true)
    }
}

// 注册事件回调
convoAIAPI.addHandler(handler: self)
TypeScript
// 监听智能体状态变化
conversationalAIAPI.on(EConversationalAIAPIEvents.AGENT_STATE_CHANGED, onAgentStateChanged)
// 监听智能体性能指标
conversationalAIAPI.on(EConversationalAIAPIEvents.AGENT_METRICS, onAgentMetricsChanged)
// 监听智能体错误事件
conversationalAIAPI.on(EConversationalAIAPIEvents.AGENT_ERROR, onAgentError)

订阅频道消息

智能体的相关事件通过 RTM 频道消息传递，你需要在开始智能体会话前调用 subscribeMessage 订阅频道消息，以接收智能体相关事件。

Kotlin
api.subscribeMessage("channelName") { error ->
    if (error != null) {
        // 处理错误
    }
}

智能体加入频道

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

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

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

取消订阅频道消息

每次智能体会话结束后，你需要取消订阅频道消息，以释放回调事件相关资源。

Kotlin
api.unsubscribeMessage("channelName") { error ->
    if (error != null) {
        // 处理错误
    }
}

销毁组件实例

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

Kotlin
api.destroy()

参考信息

示例项目

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

Conversational-AI-Demo

API 参考

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利