On this page

Interrupt Agent

2026-10-27

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 MethodDescription
Voice InterruptionWhen 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 InterruptionThrough API, you can directly interrupt the AI agent's current content
Custom InterruptionImplemented 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 ModeInterruption CombinationCommon 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.

ParameterTypeRequiredDescription
InterruptModeNumberNoMode for voice interruption during agent's response:
  • 0: Voice interruption enabled
  • 1: Voice interruption disabled (normal voice interruption is turned off, speech recognition continues, and can be combined with InterruptKeywords to implement custom interruption)
Default is 0 if not set.

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.

ParameterTypeRequiredDescription
InterruptModeNumberNoMode 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.
InterruptKeywordsString[]NoA 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.
  • Up to 10 keywords
  • Each keyword is 1–32 characters long

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

1

Configure Callback Address

Contact ZEGOCLOUD technical support to configure the address for receiving AI Agent backend callbacks.

2

Enable Callback Reception

When creating an agent instance, set the request parameter CallbackConfig.Interrupted to 1.

3

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:

ParameterTypeDescription
ReasonNumberInterruption reason:

Previous

Get AI Agent Status

Next

Speech Segmentation Control

On this page

Back to top