# IConversationalAIAPIEventHandler 类 (/zh-CN/api-reference/conversational-ai/android/iconversationalaiapieventhandler)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

<a id="onmessageerror"></a>
## onMessageError [#onmessageerror]

```kotlin
fun onMessageError(agentUserId: String, error: MessageError)
```

消息处理出错回调。

该回调在消息处理过程中发生错误时触发。

#### 参数 [#参数]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体用户 ID。 |
| `error` | `MessageError` | 消息错误信息，包含错误类型和错误内容。详见 [`MessageError`](/zh-CN/api-reference/conversational-ai/android/struct#messageerror)。 |

<a id="onmessagereceiptupdated"></a>
## onMessageReceiptUpdated [#onmessagereceiptupdated]

```kotlin
fun onMessageReceiptUpdated(agentUserId: String, receipt: MessageReceipt)
```

消息回执更新回调。

#### 参数 [#参数-1]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体用户 ID。 |
| `receipt` | `MessageReceipt` | 消息回执信息。详见 [`MessageReceipt`](/zh-CN/api-reference/conversational-ai/android/struct#messagereceipt)。 |

<a id="onusermanualsosevent"></a>
## onUserManualSosEvent [#onusermanualsosevent]

```kotlin
fun onUserManualSosEvent(agentUserId: String, event: UserManualSosEvent)
```

手动 SoS 结果回调。

该回调用于接收服务端返回的手动 SoS 处理结果。服务端成功和失败都会通过该回调返回，业务侧可根据 `event.payload.success` 判断结果。

该回调有默认空实现，已有接入方无需强制实现。

#### 参数 [#参数-2]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体用户 ID。 |
| `event` | `UserManualSosEvent` | 手动 SoS 事件对象。详见 [`UserManualSosEvent`](/zh-CN/api-reference/conversational-ai/android/struct#usermanualsosevent)。 |

<a id="onusermanualeosevent"></a>
## onUserManualEosEvent [#onusermanualeosevent]

```kotlin
fun onUserManualEosEvent(agentUserId: String, event: UserManualEosEvent)
```

手动 EoS 结果回调。

该回调用于接收服务端返回的手动 EoS 处理结果。服务端成功和失败都会通过该回调返回，业务侧可根据 `event.payload.success` 判断结果。

该回调有默认空实现，已有接入方无需强制实现。

#### 参数 [#参数-3]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体用户 ID。 |
| `event` | `UserManualEosEvent` | 手动 EoS 事件对象。详见 [`UserManualEosEvent`](/zh-CN/api-reference/conversational-ai/android/struct#usermanualeosevent)。 |

<a id="onagentmanualeosevent"></a>
## onAgentManualEosEvent [#onagentmanualeosevent]

```kotlin
fun onAgentManualEosEvent(agentUserId: String, event: AgentManualEosEvent)
```

服务端超限自动 EoS 通知回调。

当用户单轮音频持续时间超过服务端阈值时，服务端会主动结束当前用户发言，并通过该回调通知客户端。该事件不是 `manualEOS()` 的调用结果。

该回调有默认空实现，已有接入方无需强制实现。

#### 参数 [#参数-4]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体用户 ID。 |
| `event` | `AgentManualEosEvent` | 服务端超限自动 EoS 事件对象。详见 [`AgentManualEosEvent`](/zh-CN/api-reference/conversational-ai/android/struct#agentmanualeosevent)。 |

<a id="onagentstatechanged"></a>
## onAgentStateChanged [#onagentstatechanged]

```kotlin
fun onAgentStateChanged(agentUserId: String, event: StateChangeEvent)
```

智能体状态变化回调。

#### 参数 [#参数-5]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体用户 ID。 |
| `event` | `StateChangeEvent` | 状态变化事件，详见 [`StateChangeEvent`](/zh-CN/api-reference/conversational-ai/android/struct#statechangeevent)。 |

<a id="onagentlisteningchanged"></a>
## onAgentListeningChanged [#onagentlisteningchanged]

```kotlin
fun onAgentListeningChanged(agentUserId: String, isListening: Boolean)
```

智能体倾听状态变化回调。

该回调是对 `onAgentStateChanged` 的细粒度补充，用于监听智能体是否正在倾听用户输入。

#### 参数 [#参数-6]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体用户 ID。 |
| `isListening` | `Boolean` | 智能体当前是否处于倾听状态。 |

<a id="onagentthinkingchanged"></a>
## onAgentThinkingChanged [#onagentthinkingchanged]

```kotlin
fun onAgentThinkingChanged(agentUserId: String, isThinking: Boolean)
```

智能体思考状态变化回调。

该回调是对 `onAgentStateChanged` 的细粒度补充，用于监听智能体是否正在思考或处理请求。

#### 参数 [#参数-7]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体用户 ID。 |
| `isThinking` | `Boolean` | 智能体当前是否处于思考状态。 |

<a id="onagentspeakingchanged"></a>
## onAgentSpeakingChanged [#onagentspeakingchanged]

```kotlin
fun onAgentSpeakingChanged(agentUserId: String, isSpeaking: Boolean)
```

智能体说话状态变化回调。

该回调是对 `onAgentStateChanged` 的细粒度补充，用于监听智能体是否正在播报语音。

#### 参数 [#参数-8]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体用户 ID。 |
| `isSpeaking` | `Boolean` | 智能体当前是否处于说话状态。 |

<a id="onagentinterrupted"></a>
## onAgentInterrupted [#onagentinterrupted]

```kotlin
fun onAgentInterrupted(agentUserId: String, event: InterruptEvent)
```

中断事件回调。

#### 参数 [#参数-9]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体用户 ID。 |
| `event` | `InterruptEvent` | 中断事件，详见 [`InterruptEvent`](/zh-CN/api-reference/conversational-ai/android/struct#interruptevent)。 |

<a id="onagentmetrics"></a>
## onAgentMetrics [#onagentmetrics]

```kotlin
fun onAgentMetrics(agentUserId: String, metric: Metric)
```

性能指标回调。

#### 参数 [#参数-10]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体用户 ID。 |
| `metric` | `Metric` | 性能指标。详见 [`Metric`](/zh-CN/api-reference/conversational-ai/android/struct#metric)。 |

<a id="onagenterror"></a>
## onAgentError [#onagenterror]

```kotlin
fun onAgentError(agentUserId: String, error: ModuleError)
```

智能体错误回调。

#### 参数 [#参数-11]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体用户 ID。 |
| `error` | `ModuleError` | 错误信息。详见 [`ModuleError`](/zh-CN/api-reference/conversational-ai/android/struct#moduleerror)。 |

<a id="ontranscriptupdated"></a>
## onTranscriptUpdated [#ontranscriptupdated]

```kotlin
fun onTranscriptUpdated(agentUserId: String, transcript: Transcript)
```

转写内容更新回调。

:::warning[注意]
该回调可能会高频触发。如需去重，请在业务层处理。
:::

#### 参数 [#参数-12]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `agentUserId` | `String` | 智能体用户 ID。 |
| `transcript` | `Transcript` | 转写数据。详见 [`Transcript`](/zh-CN/api-reference/conversational-ai/android/struct#transcript)。 |

<a id="ondebuglog"></a>
## onDebugLog [#ondebuglog]

```kotlin
fun onDebugLog(log: String)
```

内部调试日志回调。

#### 参数 [#参数-13]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `log` | `String` | 调试日志信息。 |