Interrupt agent

When interacting with an agent, you may need to interrupt the agent to begin a new round of conversation. The Agora Conversational AI Engine supports agent interruption in the following ways:

• Voice interruption: The engine detects user voice input and automatically stops the agent’s response.
• Manual interruption: Your app can explicitly stop the agent by calling a REST API or client SDK method—typically triggered by a button tap or custom command.

This page describes how to implement agent interruption in your app.

Conversational AI Engine supports a graceful interruption feature that allows a user’s voice input to automatically interrupt the speaking agent. This enables quicker response times and more natural, fluid interactions.

info

Graceful interruption is a value-added service. A separate fees is charged after the service is enabled. For details, see Pricing.

By default, this feature is disabled. To enable it, set advanced_features.enable_aivad to true when calling Start a conversational AI agent. The following example shows how to do this:

_46

curl --request post \

_46

--url https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/join \

_46

--header 'Authorization: Basic <your_base64_encoded_credentials>' \

_46

--data '

_46

{

_46

"name": "unique_name",

_46

"properties": {

_46

"channel": "channel_name",

_46

"token": "token",

_46

"agent_rtc_uid": "1001",

_46

"remote_rtc_uids": [

_46

"1002"

_46

],

_46

"idle_timeout": 120,

_46

"advanced_features": {

_46

"enable_aivad": true

_46

},

_46

"llm": {

_46

"url": "https://api.openai.com/v1/chat/completions",

_46

"api_key": "<your_llm_key>",

_46

"system_messages": [

_46

{

_46

"role": "system",

_46

"content": "You are a helpful chatbot."

_46

}

_46

],

_46

"max_history": 32,

_46

"greeting_message": "Hello, how can I assist you today?",

_46

"failure_message": "Please hold on a second.",

_46

"params": {

_46

"model": "gpt-4o-mini"

_46

}

_46

},

_46

"tts": {

_46

"vendor": "microsoft",

_46

"params": {

_46

"key": "<your_tts_api_key>",

_46

"region": "eastus",

_46

"voice_name": "en-US-AndrewMultilingualNeural"

_46

}

_46

},

_46

"asr": {

_46

"language": "en-US"

_46

}

_46

}

_46

}'

If the request succeeds, the API returns a 200 status code and a response body like the following:

_5

{

_5

"agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",

_5

"create_ts": 1737111452,

_5

"status": "RUNNING"

_5

}

Conversational AI Engine supports actively triggering an interruption by calling RESTful APIs or client component APIs. This allows users to interrupt the agent through a button click or a specific command.

Use the Interrupt agent API to manually initiate an interruption request.

_4

curl --request post \

_4

--url https://api.agora.io/cn/api/conversational-ai-agent/v2/projects/:appid/agents/:agentId/interrupt \

_4

--header 'Authorization: Basic <credentials>' \

_4

--data '{}'

If the request is successful, the API returns a 200 status code and the following response body:

_5

{

_5

"agent_id": "1NT29XxxxxxxxxELWEHC8OS",

_5

"channel": "test_channel",

_5

"start_ts": 1744877089

_5

}

Agora provides a set of flexible, scalable and standardized client components for its conversational AI engine. These components support iOS, Android, and Web platforms and encapsulate scenario-based APIs. You can use them to integrate Agora Real-Time Communication (RTC) and Real-Time Messaging Signaling capabilities, enabling the following features:

• Interrupt the agent
• Display real-time subtitles
• Receive event notifications
• Optimize audio (Android and iOS only)

Before you begin, make sure you:

• Integrate Video SDK v4.5.1 or later and follow the Quickstart guide to implement basic real-time audio and video features.
• Enable the Signaling service for your project in the Agora Console and follow the Signaling Quickstart to implement real-time messaging.
• Implement the basic logic to communicate with a Conversational AI agent.
• Ensure that the RTC engine instance is initialized and Signaling is logged in. The toolkit does not handle initialization, lifecycle management, authentication, or login for Video SDK or Signaling.

Android

Copy the convoaiApi folder to your project and import it before calling API methods. Refer to the component structure to understand the role of each file.

iOS

Copy the ConversationalAIAPI folder to your project and import it before calling API methods. Refer to the component structure to understand the role of each file.

Web

Copy the conversational-ai-api file to your project and import it before calling API methods.. Refer to the component structure to understand the role of each file.

Create a configuration object for the RTC engine and Signaling client instances, then use it to initialize the component instance.

Android

// Create a configuration object for the RTC and RTM instances
val config = ConversationalAIAPIConfig(
    rtcEngine = rtcEngineInstance,
    rtmClient = rtmClientInstance,
    enableLog = true
)

// Create the component instance
val api = ConversationalAIAPIImpl(config)

iOS

// Create a configuration object for the RTC and RTM instances
let config = ConversationalAIAPIConfig(
    rtcEngine: rtcEngine, 
    rtmEngine: rtmEngine,
    enableLog: true
)

// Create the component instance
convoAIAPI = ConversationalAIAPIImpl(config: config)

Web

// Create a configuration object for the RTC and RTM instances
ConversationalAIAPI.init({
    rtcEngine,
    rtmEngine,
})

// Get the API instance (singleton)
const conversationalAIAPI = ConversationalAIAPI.getInstance()

Call Start a conversational AI agent using the following parameter settings:

• advanced_features.enable_rtm: true: Start the Signaling service (Required)
• parameters.data_channel: "rtm": Enable the RTM data transmission channel (Required)
• parameters.enable_metrics: true: Receive agent performance data (Enabled on demand)
• parameters.enable_error_message: true: Receive agent error events (Enable on demand)

After the call is successful, the agent joins the specified RTC channel and the user can start interacting with the agent.

Call the interrupt method to interrupt the agent.

Android

api.interrupt("agentId") { error -> /* ... */ }

iOS

convoAIAPI.interrupt(agentUserId: "(agentUid)") { error in
    if let error = error {
        print("Interruption failed: (error.message)")
    } else {
        print("Interruption succeeded")
    }
}

Web

await conversationalAIAPI.interrupt(`${agent_rtc_uid}`)

When the agent interaction ends, destroy the component instance to release all resources.

Android

api.destroy()

iOS

convoAIAPI.destroy()

Web

conversationalAIAPI.destroy()

Agora provides a sample project for your reference. Download or view the source code for a complete example.

The structure of the client component folder and the functions of each file are as follows:

info

Copy only the following files and folders to integrate the client component. You do not need to copy other files.

Android

• IConversationalAIAPI.kt: API interface and related data structures and enumerations
• ConversationalAIAPIImpl.kt: ConversationalAI API main implementation logic
• ConversationalAIUtils.kt: Tool functions and event callback management subRender/
  • v3/: Subtitle module
    • TranscriptionController.kt: Subtitle controller
    • MessageParser.kt: Message parser

iOS

• ConversationalAIAPI.swift: API interface and related data structures and enumerations
• ConversationalAIAPIImpl.swift: ConversationalAI API main implementation logic
• Transcription/
  • TranscriptionController.swift: Subtitle controller

Web

• index.ts: API Class
• type.ts: API interface and related data structures and enumerations
• utils/index.ts: API utility functions
• utils/events.ts: Event management class, which can be extended to easily implement event monitoring and broadcasting
• utils/sub-render.ts: Subtitle module

• Start a conversational AI Agent
• Interrupt the Agent

Android

• interrupt
• destroy

iOS

• interrupt
• destroy

Web

• interrupt
• destroy