打断智能体
2026-10-27
在不同场景下，需要支持不同的方式来打断智能体说话。目前支持三种打断形式，且多种打断形式组合使用。
| 打断方式 | 打断说明 |
|---|---|
| 语音打断 | 若开启语音打断，则智能体正在说话时，持续监听用户说话状态及识别说话内容，若用户开始说话，则会打断停止智能体说话（停止本轮LLM请求、TTS请求），并开始下一轮回答。若关闭语音打断，则直到智能体说话结束，才开始下一轮。 |
| 手动打断 | 通过 API ，即可直接打断智能体本轮内容 |
| 自定义打断 | 通过打断关键词实现：配置后，仅当用户本轮说话内容中包含任一打断关键词时，才会打断智能体说话；打断后语音识别继续进行。 |
常见场景
| 语音通话模式 | 打断组合 | 常见场景 |
|---|---|---|
| 自然语音聊天 | ✅开启语音打断 ❌不用手动打断 ❌不支持自定义打断 | AI虚拟陪聊 AI智能对话语音助手 AI客服 |
| Push-to-talk的对讲机模式 | ❌关闭语音打断 ✅使用手动打断 ⭕自定义打断（可选） | 异常嘈杂的展会环境 研讨会中短暂发言 狼人杀等有规定时间的发言 |
使用步骤
开启或关闭语音打断
在创建智能体实例时可通过设置 AdvancedConfig.InterruptMode 参数控制语音打断开或者关。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| InterruptMode | Number | 否 | 智能体回复时被用户语音打断的模式：
|
手动打断
调用打断智能体实例状态接口（InterruptAgentInstance）时传入创建智能体实例接口返回的 AgentInstanceId，即可立即打断智能体讲话。
除了通过服务端 API 打断智能体外，您也可以通过客户端 ZEGO Express SDK 发送房间信令实现打断，详情请查看客户端文档智能体自定义控制。
自定义打断
在创建智能体实例时，将 AdvancedConfig.InterruptMode 设置为 1（语音不打断），并通过 AdvancedConfig.InterruptKeywords 参数配置打断关键词列表，即可实现自定义打断。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| InterruptMode | Number | 否 | 智能体回复时被用户语音打断的模式。使用自定义打断需设置为 1：关闭普通语音打断，智能体说话期间持续进行语音识别，命中打断关键词时触发打断，不设置默认为 0。 |
| InterruptKeywords | String[] | 否 | 打断关键词列表。用户本轮的识别内容中包含任一关键词时，智能体将被打断；打断后语音识别继续进行。InterruptMode 为 0 时该参数不生效。
|
开启自定义打断后，智能体说话过程中，用户的普通语音不会打断智能体，仅当用户本轮的识别内容中包含任一打断关键词时，才会打断智能体本轮说话，打断后语音识别继续进行。
触发打断的这一轮用户识别文本会记录到对话上下文，但不会自动触发智能体的新一轮回答。
获取智能体被打断的事件通知
1
配置回调地址
请联系 ZEGO 技术支持配置用于接收 AI Agent 后台回调的地址。
2
启用回调接收
创建智能体实例 时，请求参数 CallbackConfig.Interrupted 设置为 1。
3
接收回调
当智能体被打断时，AI Agent 后台会向上述配置的地址发送打断事件通知（Event为Interrupted），内容示例如下：
{
"AppId": 123456789,
"Nonce": "abcdd22113",
"Timestamp": 1747033950524，
"Sequence": 1921825797275873300,
"Signature": "XXXXXXX",
// !mark
"Event": "Interrupted",
"RoomId": "90000001237",
"AgentInstanceId": "1921825671047294976",
"AgentUserId": "apitest689_agent",
"Data": {
"Round": 1481651956,
"Reason": 1
}
}Reason（被打断的原因）解释如下：
| 参数 | 类型 | 说明 |
|---|---|---|
| Reason | Number | 被打断的原因： |