# 结构体 (/zh-CN/api-reference/conversational-ai/android/struct) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). ## MessageReceipt [#messagereceipt] ```kotlin data class MessageReceipt( val type: ModuleType, val chatMessageType: ChatMessageType, val turnId: Long, val message: String ) ``` [`MessageReceipt`](/zh-CN/api-reference/conversational-ai/android/struct#messagereceipt) 表示消息回执信息,支持通过 `MediaInfo` 处理多种媒体类型。 #### 成员参数 [#成员参数] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `type` | `ModuleType` | 模块类型,详见 [`ModuleType`](/zh-CN/api-reference/conversational-ai/android/enum#moduletype),例如 `llm`、`mllm`、`tts`、`context`。 | | `chatMessageType` | `ChatMessageType` | 消息错误类型。详见 [`ChatMessageType`](/zh-CN/api-reference/conversational-ai/android/struct#chatmessagetype)。 | | `turnId` | `Long` | 消息的轮次 ID。 | | `message` | `String` | [struct-android-html-0-4-2 details](#table-slot-struct-android-html-0-4-2) | **struct-android-html-0-4-2 details** 消息内容信息。需要根据 `type` 字段进行解析: - `Context` 类型:通常为包含资源信息的 JSON 字符串。 ## ChatMessageType [#chatmessagetype] ```kotlin enum class ChatMessageType(val value: String) { Text("text"), Image("picture"), UNKNOWN("unknown"); companion object { fun fromValue(value: String): ChatMessageType { return ChatMessageType.entries.find { it.value == value } ?: UNKNOWN } } } ``` 用于区分会话系统中不同类型的消息。 #### 成员参数 [#成员参数-1] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `value` | `String` | 用于匹配的字符串值。 | ## MessageError [#messageerror] ```kotlin data class MessageError( val chatMessageType: ChatMessageType, val code: Int, val message: String, val timestamp: Long ) ``` 用于处理和上报消息错误信息。 #### 成员参数 [#成员参数-2] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `chatMessageType` | `ChatMessageType` | 消息错误类型。详见 [`ChatMessageType`](/zh-CN/api-reference/conversational-ai/android/struct#chatmessagetype)。 | | `code` | `Int` | 用于识别特定错误情况的错误码。 | | `message` | `String` | 错误描述信息,提供详细错误解释,通常为包含资源信息的 JSON 字符串。 | | `timestamp` | `Long` | 事件发生的时间戳(自 1970 年 1 月 1 日 UTC 起的毫秒数)。 | ## UserManualEventPayload [#usermanualeventpayload] ```kotlin data class UserManualEventPayload( val success: Boolean, val requestId: String, val turnId: Long?, val errorMessage: String? ) ``` 手动 SoS/EoS 通用载荷。 #### 成员参数 [#成员参数-3] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `success` | `Boolean` | 服务端是否成功处理本次手动信令。 | | `requestId` | `String` | 请求 ID,与调用 `manualSOS` 或 `manualEOS` 后在 `completion` 中返回的 `requestId` 对应。 | | `turnId` | `Long?` | 关联的对话轮次 ID。若服务端失败回调未携带 `turn_id`,则该字段为 null。 | | `errorMessage` | `String?` | 服务端返回的原始错误信息。成功时通常为 null。 | ## UserManualSosEvent [#usermanualsosevent] ```kotlin data class UserManualSosEvent( val eventId: String, val timestamp: Long, val payload: UserManualEventPayload ) ``` 手动 SoS 事件对象。 #### 成员参数 [#成员参数-4] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `eventId` | `String` | 事件唯一 ID。 | | `timestamp` | `Long` | 事件时间戳,单位为毫秒。 | | `payload` | `UserManualEventPayload` | 事件载荷。详见 [`UserManualEventPayload`](/zh-CN/api-reference/conversational-ai/android/struct#usermanualeventpayload)。 | ## UserManualEosEvent [#usermanualeosevent] ```kotlin data class UserManualEosEvent( val eventId: String, val timestamp: Long, val payload: UserManualEventPayload ) ``` 手动 EoS 事件对象。 #### 成员参数 [#成员参数-5] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `eventId` | `String` | 事件唯一 ID。 | | `timestamp` | `Long` | 事件时间戳,单位为毫秒。 | | `payload` | `UserManualEventPayload` | 事件载荷。详见 [`UserManualEventPayload`](/zh-CN/api-reference/conversational-ai/android/struct#usermanualeventpayload)。 | ## AgentManualEosPayload [#agentmanualeospayload] ```kotlin data class AgentManualEosPayload( val reason: String, val maxDurationMs: Long, val turnId: Long ) ``` 服务端超限自动 EoS 载荷。 #### 成员参数 [#成员参数-6] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `reason` | `String` | 服务端自动结束当前用户发言的原因。 | | `maxDurationMs` | `Long` | 当前配置的单轮最大音频时长,单位为毫秒。 | | `turnId` | `Long` | 关联的对话轮次 ID。 | ## AgentManualEosEvent [#agentmanualeosevent] ```kotlin data class AgentManualEosEvent( val eventId: String, val timestamp: Long, val payload: AgentManualEosPayload ) ``` 服务端超限自动 EoS 事件对象。 #### 成员参数 [#成员参数-7] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `eventId` | `String` | 事件唯一 ID。 | | `timestamp` | `Long` | 事件时间戳,单位为毫秒。 | | `payload` | `AgentManualEosPayload` | 事件载荷。详见 [`AgentManualEosPayload`](/zh-CN/api-reference/conversational-ai/android/struct#agentmanualeospayload)。 | ## ChatMessage [#chatmessage] ```kotlin sealed class ChatMessage ``` 用于发送给智能体的所有消息类型的密封基类。 该密封类层级结构为不同内容类型的消息提供类型安全的处理方式。 ## SpeakMessage [#speakmessage] ```kotlin data class SpeakMessage( val text: String, val priority: Priority = Priority.INTERRUPT, val interruptable: Boolean = true, ) ``` 用于绕过大模型,直接通过智能体的 TTS 流程播报文本。 #### 成员参数 [#成员参数-8] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `text` | `String` | 要播报的文本。 | | `priority` | `Priority` | 播报请求的处理优先级,默认值为 `INTERRUPT`。详见 [`Priority`](/zh-CN/api-reference/conversational-ai/android/enum#priority)。 | | `interruptable` | `Boolean` | 是否允许用户说话打断本次播报,默认值为 `true`。 | ## ThinkMessage [#thinkmessage] ```kotlin data class ThinkMessage( val text: String, val onListeningAction: ThinkListeningAction = ThinkListeningAction.INTERRUPT, val onThinkingAction: ThinkThinkingAction = ThinkThinkingAction.IGNORE, val onSpeakingAction: ThinkSpeakingAction = ThinkSpeakingAction.IGNORE, val interruptable: Boolean = true, val metadata: Map? = null, ) ``` 用于将文本作为用户输入注入对话,并交由大模型处理。 #### 成员参数 [#成员参数-9] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `text` | `String` | 要注入大模型的指令文本。 | | `onListeningAction` | `ThinkListeningAction` | 智能体处于倾听状态时的处理动作,默认值为 `INTERRUPT`。详见 [`ThinkListeningAction`](/zh-CN/api-reference/conversational-ai/android/enum#thinklisteningaction)。 | | `onThinkingAction` | `ThinkThinkingAction` | 智能体处于思考状态时的处理动作,默认值为 `IGNORE`。详见 [`ThinkThinkingAction`](/zh-CN/api-reference/conversational-ai/android/enum#thinkthinkingaction)。 | | `onSpeakingAction` | `ThinkSpeakingAction` | 智能体处于说话状态时的处理动作,默认值为 `IGNORE`。详见 [`ThinkSpeakingAction`](/zh-CN/api-reference/conversational-ai/android/enum#thinkspeakingaction)。 | | `interruptable` | `Boolean` | 是否允许用户说话打断本次指令生成的响应,默认值为 `true`。 | | `metadata` | `Map?` | 可选的业务自定义键值对。为 null 时不会写入 RTM 消息。 | ## Transcript [#transcript] ```kotlin data class Transcript constructor( val turnId: Long, val userId: String = "", val text: String, var status: TranscriptStatus, var type: TranscriptType ) ``` [`Transcript`](/zh-CN/api-reference/conversational-ai/android/struct#transcript) 用于渲染 UI 的完整转录消息。 #### 成员参数 [#成员参数-10] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `turnId` | `Long` | 会话轮次的唯一标识符。 | | `userId` | `String` | 与该转录关联的用户标识符。 | | `text` | `String` | 转录的实际文本内容。 | | `status` | `TranscriptStatus` | 转录的当前状态。详见 [`TranscriptStatus`](/zh-CN/api-reference/conversational-ai/android/enum#transcriptstatus)。 | | `type` | `TranscriptType` | 转录类型,例如 AGENT 或 USER。详见 [`TranscriptType`](/zh-CN/api-reference/conversational-ai/android/enum#transcripttype)。 | ## ModuleError [#moduleerror] ```kotlin data class ModuleError( val type: ModuleType, val code: Int, val message: String, val timestamp: Long, val turnId: Long? = null ) ``` 用于处理和上报 [`ModuleError`](/zh-CN/api-reference/conversational-ai/android/struct#moduleerror) 类型的智能体相关错误信息。 包含错误类型、错误码、错误描述和时间戳,便于实现错误监控、日志记录以及故障排查。 #### 成员参数 [#成员参数-11] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `type` | `ModuleType` | 错误类型,例如:LLM 调用失败、TTS 异常等。详见 [`ModuleType`](/zh-CN/api-reference/conversational-ai/android/enum#moduletype)。 | | `code` | `Int` | 用于标识特定错误条件的错误码。 | | `message` | `String` | 提供详细错误说明的错误描述信息。 | | `timestamp` | `Long` | 错误发生的时间戳(从 1970 年 1 月 1 日 UTC 起的毫秒数)。 | | `turnId` | `Long?` | (可选)图片对应的 `turnId`,用于图像上传错误。 | ## ImageMessage [#imagemessage] ```kotlin data class ImageMessage( val uuid: String, val imageUrl: String, ) : ChatMessage() ``` 用于向智能体发送图像内容。 支持通过 HTTP/HTTPS 链接指定图像文件。 #### 成员参数 [#成员参数-12] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `uuid` | `String` | 图像消息的唯一标识符。 | | `imageUrl` | `String?` | HTTP/HTTPS 图像文件链接。 | ## StateChangeEvent [#statechangeevent] ```kotlin data class StateChangeEvent( val state: AgentState, val turnId: Long, val timestamp: Long, ) ``` 表示智能体状态变更事件。 用于跟踪会话流程和更新用户界面中的状态指示,包含事件发生的时间戳。 #### 成员参数 [#成员参数-13] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `state` | `AgentState` | 当前智能体状态。包括:`silent`、`listening`、`thinking`、`speaking`。详见 [`AgentState`](/zh-CN/api-reference/conversational-ai/android/enum#agentstate)。 | | `turnId` | `Long` | 会话轮次 ID,用于标识特定的对话轮次。 | | `timestamp` | `Long` | 事件发生的时间戳(自 1970 年 1 月 1 日 UTC 起的毫秒数)。 | ## InterruptEvent [#interruptevent] ```kotlin data class InterruptEvent( val turnId: Long, val timestamp: Long ) ``` [`InterruptEvent`](/zh-CN/api-reference/conversational-ai/android/struct#interruptevent) 表示中断事件。 通常在用户主动打断 AI 说话或系统检测到高优先级消息时触发,用于记录中断行为并进行相应处理。 #### 成员参数 [#成员参数-14] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `turnId` | `Long` | 被中断的对话轮次 ID。 | | `timestamp` | `Long` | 中断事件发生的时间戳(自 1970 年 1 月 1 日 UTC 起的毫秒数)。 | ## Metric [#metric] ```kotlin data class Metric( val type: ModuleType, val name: String, val value: Double, val timestamp: Long ) ``` 用于定义系统性能指标数据。 用于记录和传输系统性能数据。该数据可用于性能监控、系统优化和用户体验改进。 #### 成员参数 [#成员参数-15] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `type` | `ModuleType` | 指标类型。详见 [`ModuleType`](/zh-CN/api-reference/conversational-ai/android/enum#moduletype)。 | | `name` | `String` | 指标名称,用于描述具体的性能项。 | | `value` | `Double` | 指标值,通常为延迟时间(毫秒)或其他量化指标。 | | `timestamp` | `Long` | 指标记录的时间戳(自 1970 年 1 月 1 日 UTC 起经过的毫秒数)。 | ## ConversationalAIAPIConfig [#conversationalaiapiconfig] ```kotlin data class ConversationalAIAPIConfig( val rtcEngine: RtcEngine, val rtmClient: RtmClient, val renderMode: TranscriptRenderMode = TranscriptRenderMode.Word, val enableLog: Boolean = false ) ``` 用于配置对话式 AI 引擎 API 所需的参数。 该类包含初始化对话式 AI 引擎 API 所需的参数配置,包括用于音频通信的 `rtcEngine`、用于实时消息传递的 `rtmClient`,以及转写渲染模式设置。 #### 成员参数 [#成员参数-16] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `rtcEngine` | `RtcEngine` | 用于音视频通信的引擎实例。详见 `RtcEngine`。 | | `rtmClient` | `RtmClient` | 用于实时消息通信的客户端实例。详见 `RtmClient`。 | | `renderMode` | `TranscriptRenderMode` | 转写渲染模式,默认为按词渲染。详见 [`TranscriptRenderMode`](/zh-CN/api-reference/conversational-ai/android/enum#transcriptrendermode)。 | | `enableLog` | `Boolean` | [struct-android-html-14-4-2 details](#table-slot-struct-android-html-14-4-2) | **struct-android-html-14-4-2 details** 是否启用日志记录: - `true`:启用日志记录。 - `false`:不启用日志记录(默认)。 ## ConversationalAIAPIError [#conversationalaiapierror] ```kotlin sealed class ConversationalAIAPIError : Exception() { data class RtmError(val code: Int, val msg: String) : ConversationalAIAPIError() data class RtcError(val code: Int, val msg: String) : ConversationalAIAPIError() data class UnknownError(val msg: String) : ConversationalAIAPIError() val errorCode: Int get() = when (this) { is RtmError -> this.code is RtcError -> this.code is UnknownError -> -100 } val errorMessage: String get() = when (this) { is RtmError -> this.msg is RtcError -> this.msg is UnknownError -> this.msg } } ``` 表示对话式 AI 引擎 API 中的错误类型。 #### 成员参数 [#成员参数-17] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `errorCode` | `Int` | [struct-android-html-15-1-2 details](#table-slot-struct-android-html-15-1-2) | | `errorMessage` | `String` | 错误信息,返回具体的错误描述内容。 | **struct-android-html-15-1-2 details** 错误码: - `RtmError` 或 `RtcError` 返回具体错误码。 - `UnknownError` 返回 -100。