# 获取智能体状态 (/zh-CN/ai/build/handle-runtime-events/get-agent-state) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 如果你的 App 希望感知智能体状态变化,可以选择通过 RTM Message 或 RTM Presence 获取状态。本文介绍如何通过 RTM Message 获取智能体状态,并说明该方案与 RTM Presence 方案的差异。 :::info[信息] - 本文重点介绍如何通过 RTM Message 获取智能体状态。 - 如果你希望使用客户端组件监听状态变化,可以参考[监听智能体事件](/zh-CN/ai/build/handle-runtime-events/event-notifications)。 - 如果你希望通过 RTM Presence 获取状态,可以继续沿用现有 Presence 方案。 ::: ## 实现原理 [#实现原理] ConvoAI 支持通过 RTM Message 向客户端推送智能体状态变化事件。与 RTM Presence 的键值同步方式不同,RTM Message 会将每一次状态变化包装成一条独立的事件消息,便于你记录状态变更时间、进行顺序处理或与其他 RTM Message 事件统一消费。 ConvoAI 推送的状态消息通过 RTM 的消息回调(`onMessageEvent`)下发。消息的内层 `message` 字段是一个 JSON 字符串,需要再次解析才能得到具体的状态事件。对于状态消息,建议你直接根据内层 `message` 中的 `event_type` 字段识别消息类型。 当前通过 RTM Message 推送的智能体状态包括: - `state.listening` - `state.thinking` - `state.speaking` 其工作方式如下: ```text ConvoAI 状态变化 ├─ listening -> true / false ├─ thinking -> true / false └─ speaking -> true / false ↓ RTM Message ↓ 客户端解析内层 payload 并根据 event_type 识别状态事件 ``` ### 状态消息类型 [#状态消息类型] ConvoAI 会在智能体状态变化时发送 RTM Message。每一条消息只对应一个状态变化事件。 当前支持以下事件类型: | `event_type` | 说明 | | ----------------- | ------------------------------ | | `state.listening` | 智能体开始或结束聆听用户输入。 | | `state.thinking` | 智能体开始或结束处理用户输入。 | | `state.speaking` | 智能体开始或结束播报语音。 | ### 消息结构 [#消息结构] 智能体状态消息的内层 `message` 为 JSON 字符串,反序列化后的结构如下: ```json { "event_id": "xxxx", "event_type": "state.listening", "event_ms": 1611566412672, "payload": { "value": true, "timestamp": 1611566412600 } } ``` 字段说明如下: | 字段 | 类型 | 说明 | | ------------------- | ------- | ------------------------------------------------------------------------------ | | `event_id` | string | 事件唯一 ID。 | | `event_type` | string | 状态事件类型,取值为 `state.listening`、`state.thinking` 或 `state.speaking`。 | | `event_ms` | integer | 事件发送时间戳,单位为毫秒。 | | `payload.value` | boolean | 当前状态值。`true` 表示进入该状态,`false` 表示退出该状态。 | | `payload.timestamp` | integer | 状态实际发生时间戳,单位为毫秒。 | ### 示例 [#示例] 智能体进入聆听状态时,内层 `message` 反序列化后的示例如下: ```json { "event_id": "a1b2c3d4", "event_type": "state.listening", "event_ms": 1611566412672, "payload": { "value": true, "timestamp": 1611566412600 } } ``` 智能体退出说话状态时,内层 `message` 反序列化后的示例如下: ```json { "event_id": "e5f6g7h8", "event_type": "state.speaking", "event_ms": 1611566420000, "payload": { "value": false, "timestamp": 1611566419900 } } ``` ## 前提条件 [#前提条件] 开始前,请确保你已经: - 参考[实现对话式智能体](/zh-CN/ai/get-started/quick-start)完成与智能体交互的基本流程。 - 完成 RTM SDK 的基础集成,并参考[实现收发消息](/zh-CN/realtime-media/rtm/get-started/quick-start)实现消息监听逻辑。 - 在创建智能体时启用 RTM 服务,并将 `data_channel` 设置为 `rtm`。 在开始监听智能体状态消息前,你需要先在创建智能体时启用 RTM 服务,并将数据通道设置为 RTM。 调用 [POST 创建对话式智能体](/zh-CN/api-reference/api-ref/conversational-ai/join)接口时,至少需要包含以下配置: ```json { "properties": { "advanced_features": { "enable_rtm": true }, "parameters": { "data_channel": "rtm" } } } ``` ## 实现通过 RTM Message 获取智能体状态 [#实现通过-rtm-message-获取智能体状态] 完成 RTM 登录并订阅与智能体同名的频道后,你可以在 RTM 消息回调中解析状态消息。处理逻辑分为三步: 1. 将收到的 RTM `message` 字段反序列化为状态事件对象。 2. 检查反序列化结果中是否包含 `event_type` 和 `payload` 等字段。 3. 根据 `event_type` 分发处理,并使用 `payload.value` 更新业务状态。 ### 监听并解析状态消息 [#监听并解析状态消息] Android iOS Web ```kotlin val rtmConfig = RtmConfig() rtmConfig.eventListener = object : RtmEventListener { override fun onMessageEvent(event: MessageEvent) { // 1. 反序列化内层 message(JSON 字符串) val payload = JSONObject(event.message.data) if (!payload.has("event_type") || !payload.has("payload")) { return } val eventType = payload.getString("event_type") val statePayload = payload.getJSONObject("payload") val value = statePayload.getBoolean("value") val timestamp = statePayload.getLong("timestamp") // 2. 根据 event_type 分发处理 when (eventType) { "state.listening" -> handleListeningChanged(value, timestamp) "state.thinking" -> handleThinkingChanged(value, timestamp) "state.speaking" -> handleSpeakingChanged(value, timestamp) } } } mRtmClient = RtmClient.create(rtmConfig) ```` ```swift func rtmKit(_ rtmKit: AgoraRtmClientKit, didReceiveMessageEvent event: AgoraRtmMessageEvent) { // 1. 反序列化内层 message(JSON 字符串) guard let jsonString = event.message.stringData, let data = jsonString.data(using: .utf8), let payload = try? JSONSerialization.jsonObject(with: data) as? [String: Any], let eventType = payload["event_type"] as? String, let statePayload = payload["payload"] as? [String: Any] else { return } let value = statePayload["value"] as? Bool ?? false let timestamp = statePayload["timestamp"] as? Int ?? 0 // 2. 根据 event_type 分发处理 switch eventType { case "state.listening": handleListeningChanged(value, timestamp) case "state.thinking": handleThinkingChanged(value, timestamp) case "state.speaking": handleSpeakingChanged(value, timestamp) default: break } } ```` ```typescript rtm.addEventListener("message", (event) => { // 1. 反序列化内层 message(JSON 字符串) const payload = JSON.parse(event.message as string); if (!payload.event_type || !payload.payload) { return; } const { event_type, payload: statePayload } = payload; // 2. 根据 event_type 分发处理 switch (event_type) { case "state.listening": handleListeningChanged(statePayload.value, statePayload.timestamp); break; case "state.thinking": handleThinkingChanged(statePayload.value, statePayload.timestamp); break; case "state.speaking": handleSpeakingChanged(statePayload.value, statePayload.timestamp); break; default: break; } }); ``` 在上述示例中: - 内层 `message` 是 JSON 字符串,需要再次反序列化才能得到 `event_type` 和 `payload`。 - `event_type` 用于判断具体的状态类型。 - `payload.value` 表示进入(`true`)或退出(`false`)该状态。 - `payload.timestamp` 可用于精确排序或日志记录。 ### 更新业务状态 [#更新业务状态] 你可以根据接收到的事件更新 UI 或内部状态机,例如: - 收到 `state.listening` 且 `payload.value = true` 时,展示“正在听”。 - 收到 `state.thinking` 且 `payload.value = true` 时,展示“思考中”。 - 收到 `state.speaking` 且 `payload.value = true` 时,展示“说话中”。 ## RTM Message 与 RTM Presence 方案差异 [#rtm-message-与-rtm-presence-方案差异] ConvoAI 同时支持通过 RTM Message 和 RTM Presence 获取智能体状态。两种方案的核心差异如下: | 对比项 | RTM Presence | RTM Message | | -------- | ---------------------- | ------------------------------------------ | | 返回形式 | 状态键值对 | 状态事件消息 | | 粒度 | 更适合读取当前状态 | 更适合处理每次状态变化 | | 时间信息 | 一般只依赖消息到达时间 | 显式包含 `event_ms` 和 `payload.timestamp` | | 适用场景 | 简单 UI 状态展示 | 事件驱动、日志记录、统一消息消费 | 可以按以下方式选择: - 如果你只需要根据智能体当前是否处于 `listening`、`thinking` 或 `speaking` 状态来更新界面,优先使用 RTM Presence,接入更直接。 - 如果你希望将状态变化与字幕、打断、性能指标等其他 RTM Message 一起统一处理,适合使用 RTM Message。 - 如果你需要记录每次状态变化的事件时间,或要对状态切换进行顺序分析,适合使用 RTM Message。 ## 开发注意事项 [#开发注意事项] - RTM 状态消息的内层 `message` 字段是 JSON 字符串,需要再次反序列化后才能读取 `event_type` 和 `payload`。 - 如果你已经通过 RTM Presence 驱动界面状态,切换到 RTM Message 时需要避免两套链路同时更新同一份 UI 状态,以免产生重复更新或状态抖动。 - `state.speaking` 为 `false` 并不一定等于端侧已经停止说话。当前 `speaking` 状态的结束时间由服务端根据 TTS 音频长度估算得出,因此在端侧实际播放结束时间与服务端估算时间存在偏差时,可能出现状态已经切换为 `false`,但端侧仍在播放剩余音频的情况。 - 旧版状态链路中,智能体状态可能通过 RTC Datastream 或 RTM Presence 的聚合态对外暴露。当前文档中的 RTM Message 状态事件,针对的是新状态链路中的 `listening`、`thinking` 和 `speaking` 三类细粒度状态。 :::warning[注意] 本文中的状态消息仅覆盖智能体状态事件,不包含手动 `sos/eos` 指令或相关回调。 ::: ## 相关文档 [#相关文档] - [实现对话式智能体](/zh-CN/ai/get-started/quick-start) - [监听智能体事件](/zh-CN/ai/build/handle-runtime-events/event-notifications) - [实时字幕](/zh-CN/ai/build/transcripts) - [RTM 实现收发消息](/zh-CN/realtime-media/rtm/get-started/quick-start) - [RTM 添加事件监听](/zh-CN/realtime-media/rtm/build/messaging/add-event-listener)