Interrupt Agent
Different scenarios require different ways to interrupt the AI agent's speech. Currently, three interruption methods are supported and can be used in combination.
| Interruption Method | Description |
|---|---|
| Voice Interruption | When voice interruption is enabled, the AI agent continuously monitors the user's speech status and recognizes speech content while speaking. If the user starts speaking, the AI agent stops speaking (stopping the current LLM request and TTS request) and starts the next round of response. If voice interruption is disabled, the next round will only begin after the AI agent finishes speaking. |
| Manual Interruption | Through API, you can directly interrupt the AI agent's current content |
| Custom Interruption | Implemented through interruption keywords: after configuration, the AI agent's speech will only be interrupted when the user's speech content in the current round contains any interruption keyword; speech recognition continues after the interruption. |
Common Scenarios
| Voice Call Mode | Interruption Combination | Common Scenarios |
|---|---|---|
| Natural Voice Chat | ✅Enable Voice Interruption ❌No Manual Interruption ❌Custom Interruption not supported | AI Virtual Companion AI Voice Assistant AI Customer Service |
| Push-to-talk Mode | ❌Disable Voice Interruption ✅Use Manual Interruption ⭕Custom Interruption (Optional) | Noisy Exhibition Environment Brief Speeches in Seminars Time-limited Speaking in Social Deduction Games |
Implementation Steps
Enable or Disable Voice Interruption
When creating an agent instance, you can control voice interruption by setting the AdvancedConfig.InterruptMode parameter.
| Parameter | Type | Required | Description |
|---|---|---|---|
| InterruptMode | Number | No | Mode for voice interruption during agent's response:
|
Manual Interruption
Call the InterruptAgentInstance API with the AgentInstanceId returned from the Create Agent Instance API to immediately interrupt the AI agent's speech.
In addition to interrupting the agent via the server API, you can also interrupt the agent through the client-side ZEGO Express SDK by sending room signaling messages. For details, see the client-side document Agent Custom Control.
Custom Interruption
When creating an agent instance, set AdvancedConfig.InterruptMode to 1 (voice interruption disabled) and configure a list of interruption keywords via the AdvancedConfig.InterruptKeywords parameter to implement custom interruption.
| Parameter | Type | Required | Description |
|---|---|---|---|
| InterruptMode | Number | No | Mode for voice interruption during the agent's response. To use custom interruption, set this parameter to 1: normal voice interruption is turned off, speech recognition continues while the agent is speaking, and the interruption is triggered when an interruption keyword is matched. Default is 0 if not set. |
| InterruptKeywords | String[] | No | A list of interruption keywords. The agent will be interrupted if any keyword is included in the user's recognized speech in the current round, and speech recognition continues after the interruption. This parameter does not take effect when InterruptMode is 0.
|
After custom interruption is enabled, the user's normal speech will not interrupt the agent while it is speaking. Only when the user's recognized speech in the current round contains any interruption keyword will the agent's current speech be interrupted, and speech recognition continues after the interruption.
The recognized text of the round that triggers the interruption will be recorded in the conversation context, but it will not automatically trigger a new round of response from the agent.
Receive Agent Interruption Event Notifications
Configure Callback Address
Contact ZEGOCLOUD technical support to configure the address for receiving AI Agent backend callbacks.
Enable Callback Reception
When creating an agent instance, set the request parameter CallbackConfig.Interrupted to 1.
Receive Callbacks
When the agent is interrupted, the AI Agent backend will send an interruption event notification (Event is Interrupted) to the configured address. Here's an example:
{
"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
}
}The Reason parameter is explained below:
| Parameter | Type | Description |
|---|---|---|
| Reason | Number | Interruption reason:
|
