# 监听智能体事件 (/zh-CN/ai/build/handle-runtime-events/event-notifications)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
与对话式智能体进行实时互动时,你可能需要监听智能体相关事件来实现更丰富的功能。本文介绍如何在你的 App 中监听智能体相关事件。
## 技术原理 [#技术原理]
声网提供一套灵活可扩展、标准化的对话式 AI 引擎客户端组件(以下简称组件)。该组件支持 iOS、Android、Web 平台,封装了多个场景化 API,你只需要调用这些 API 即可结合声网[实时互动 (RTC) SDK](/zh-CN/realtime-media/rtc) 和[实时消息 (RTM) SDK](/zh-CN/realtime-media/rtm) 的能力实现以下功能:
- [打断智能体](/zh-CN/ai/build/shape-the-conversation/interrupt-agent)
- [实时字幕](/zh-CN/ai/build/transcripts)
- [监听智能体相关事件](/zh-CN/ai/build/handle-runtime-events/event-notifications)
- [设置最佳音频参数](/zh-CN/ai/build/harden-and-optimize/audio-setup) (仅支持 Android 和 iOS)
- [发送图片消息](/zh-CN/ai/build/send-multimodal-messages)
组件提供一系列回调,支持监听不同的智能体相关事件和信息:
- `onAgentStateChanged`:通过接收 RTM `presence` 事件,监听智能体状态变化(静默/聆听/思考/说话)。可用于更新智能体 UI 或追踪对话流程。
- `onAgentInterrupted`:通过接收 RTM `message` 事件,监听智能体打断事件。
- `onAgentMetrics`:通过接收 RTM `message` 事件,监听智能体性能指标,包括 LLM 推理延迟、TTS 合成延迟等。可用于监控系统性能。
- `onAgentError`:通过接收 RTM `message` 事件,监听智能体错误事件,例如智能体某模块(例如 LLM、TTS 等)发生错误。可用于错误监控、日志记录和实现优雅降级策略。
## 前提条件 [#前提条件]
开始前,请确保完成以下准备工作:
- 已集成 RTC SDK v4.5.1 及以上版本,且已在 App 中实现基本的实时音视频功能并获取相关设备权限。请参考[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。
- 已在[控制台](https://console.shengwang.cn/)为项目启用 RTM 服务,并在 App 中实现基本的实时消息功能。请参考[实现收发消息](/zh-CN/realtime-media/rtm/get-started/quick-start)。
- 已参考[实现对话式智能体](/zh-CN/ai/get-started/quick-start)实现与智能体对话的基本逻辑。
- 确保 RTC 可用、RTM 已登录,且 RTC 和 RTM 实例的生命周期大于组件的生命周期。组件内部不负责维护 RTC,RTM 的初始化、生命周期以及鉴权/登录状态的逻辑。
## 实现步骤 [#实现步骤]
### 集成组件 [#集成组件]
Android
iOS
Web
Maven
源码集成
#### Maven [#maven]
在 Android 项目的 `build.gradle` 文件中添加如下依赖:
```groovy
implementation 'io.agora.agents:agora-agent-client-toolkit:2.10.0'
```
#### 源码集成 [#源码集成]
将 `convoaiApi` 文件夹拷贝到你的项目中,并在后续调用组件 API 前引入组件。
CocoaPods
Swift Package Manager
源码集成
#### 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
```
#### 源码集成 [#源码集成-1]
将 `ConversationalAIAPI` 文件夹拷贝到你的项目中,并在后续调用组件 API 前引入组件。
Package Manager
源码集成
#### 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
```
#### 源码集成 [#源码集成-2]
将 `conversational-ai-api` 文件夹拷贝到你的项目中,并在后续调用组件 API 前引入组件。
:::info[信息]
如果在 Android 或 iOS 项目中同时集成多个声网 SDK 时出现库冲突,请参考[多 SDK 库冲突处理](/zh-CN/reference/faq/integration/rtm2_rtc_integration_issue)。
:::
### 初始化组件 [#初始化组件]
为 RTC 和 RTM 实例创建配置对象,之后创建组件实例:
```kotlin tab="Android" tabGroup="language"
val config = ConversationalAIAPIConfig(
rtcEngine = rtcEngine,
rtmClient = rtmClient,
renderMode = TranscriptRenderMode.Word,
enableLog = true,
enableRenderModeFallback = true
)
val api = ConversationalAIAPIImpl(config)
```
```swift tab="iOS" tabGroup="language"
let config = ConversationalAIAPIConfig(
rtcEngine: rtcEngine,
rtmEngine: rtmEngine,
renderMode: .words,
enableLog: true,
enableRenderModeFallback: true
)
convoAIAPI = ConversationalAIAPIImpl(config: config)
```
```typescript tab="Web" tabGroup="language"
const config: IConversationalAIAPIConfig = {
rtcEngine: rtcEngine,
rtmEngine: rtmEngine,
renderMode: ETranscriptHelperMode.WORD,
enableLog: true,
enableRenderModeFallback: true,
};
const conversationalAIAPI = await ConversationalAIAPI.init(config);
```
### 注册回调 [#注册回调]
Android
iOS
Web
调用 `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 tab="Android" tabGroup="language"
api.subscribeMessage("channelName") { error ->
if (error != null) {
// 处理错误
}
}
```
```swift tab="iOS" tabGroup="language"
convoAIAPI.subscribeMessage(channelName: channelName) { error in
if let error = error {
print("订阅失败: \(error.message)")
} else {
print("订阅成功")
}
}
```
```typescript tab="Web" tabGroup="language"
conversationalAIAPI.subscribeMessage(channel_name)
```
### 智能体加入频道 [#智能体加入频道]
调用 [POST 创建对话式智能体](/zh-CN/api-reference/api-ref/conversational-ai/join)接口,并完成以下参数设置:
- `advanced_features.enable_rtm: true` —— (必选)启动 RTM 服务
- `parameters.data_channel: "rtm"` —— (必选)开启 RTM 数据传输通道
- `parameters.enable_metrics: true` —— (按需开启)接收智能体性能数据
- `parameters.enable_error_message: true` —— (按需开启)接收智能体错误事件
调用成功后,智能体会加入指定 RTC 频道,用户可以开始与智能体互动。
### 取消订阅频道消息 [#取消订阅频道消息]
每次智能体会话结束后,你需要取消订阅频道消息,以释放回调事件相关资源。
```kotlin tab="Android" tabGroup="language"
api.unsubscribeMessage("channelName") { error ->
if (error != null) {
// 处理错误
}
}
```
```swift tab="iOS" tabGroup="language"
/// 取消订阅频道消息
convoAIAPI.unsubscribeMessage(channelName: channelName) { error in
if let error = error {
print("取消订阅失败: \(error.message)")
} else {
print("取消订阅成功")
}
}
```
```typescript tab="Web" tabGroup="language"
conversationalAIAPI.unsubscribeMessage(channel_name)
```
### 销毁组件实例 [#销毁组件实例]
结束 AI 对话场景后或关闭 App 前,你需要销毁组件实例,以释放组件的所有资源。
```kotlin tab="Android" tabGroup="language"
api.destroy()
```
```swift tab="iOS" tabGroup="language"
convoAIAPI.destroy()
```
```typescript tab="Web" tabGroup="language"
conversationalAIAPI.destroy()
```
## 参考信息 [#参考信息]
### 示例项目 [#示例项目]
声网提供了开源的示例项目供你参考,你可以前往下载或查看其中的源代码。
### API 参考 [#api-参考]
Android
iOS
Web
- [`addHandler`](/zh-CN/api-reference/conversational-ai/android/iconversationalaiapi#addhandler)
- [`subscribeMessage`](/zh-CN/api-reference/conversational-ai/android/iconversationalaiapi#subscribemessage)
- [`unsubscribeMessage`](/zh-CN/api-reference/conversational-ai/android/iconversationalaiapi#unsubscribemessage)
- [`destroy`](/zh-CN/api-reference/conversational-ai/android/iconversationalaiapi#destroy)
- [`onAgentStateChanged`](/zh-CN/api-reference/conversational-ai/android/iconversationalaiapieventhandler#onagentstatechanged)
- [`onAgentInterrupted`](/zh-CN/api-reference/conversational-ai/android/iconversationalaiapieventhandler#onagentinterrupted)
- [`onAgentMetrics`](/zh-CN/api-reference/conversational-ai/android/iconversationalaiapieventhandler#onagentmetrics)
- [`onAgentError`](/zh-CN/api-reference/conversational-ai/android/iconversationalaiapieventhandler#onagenterror)
- [`addHandler`](/zh-CN/api-reference/conversational-ai/ios/conversationalaiapi#addhandler)
- [`subscribeMessage`](/zh-CN/api-reference/conversational-ai/ios/conversationalaiapi#subscribemessage)
- [`unsubscribeMessage`](/zh-CN/api-reference/conversational-ai/ios/conversationalaiapi#unsubscribemessage)
- [`destroy`](/zh-CN/api-reference/conversational-ai/ios/conversationalaiapi#destroy)
- [`onAgentStateChanged`](/zh-CN/api-reference/conversational-ai/ios/conversationalaiapieventhandler#onagentstatechanged)
- [`onAgentInterrupted`](/zh-CN/api-reference/conversational-ai/ios/conversationalaiapieventhandler#onagentinterrupted)
- [`onAgentMetrics`](/zh-CN/api-reference/conversational-ai/ios/conversationalaiapieventhandler#onagentmetrics)
- [`onAgentError`](/zh-CN/api-reference/conversational-ai/ios/conversationalaiapieventhandler#onagenterror)
- [`IConversationalAIAPIEventHandler`](/zh-CN/api-reference/conversational-ai/web/struct#iconversationalaiapieventhandlers)
- [`EConversationalAIAPIEvents`](/zh-CN/api-reference/conversational-ai/web/enum#econversationalaiapievents)
- [`subscribeMessage`](/zh-CN/api-reference/conversational-ai/web/conversationalaiapi#subscribemessage)
- [`unsubscribeMessage`](/zh-CN/api-reference/conversational-ai/web/conversationalaiapi#unsubscribe)
- [`destroy`](/zh-CN/api-reference/conversational-ai/web/conversationalaiapi#destroy)