# 打断智能体 (/zh-CN/ai/build/shape-the-conversation/interrupt-agent) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 与智能体互动期间，你可能需要打断智能体发言来开启新一轮对话。声网对话式 AI 引擎支持通过以下两种方式打断智能体： - **语音打断**：系统根据用户的语音输入自动判断并打断智能体说话。 - **手动打断**：通过调用 RESTful API 或客户端组件 API 主动发起打断请求，实现点击按钮或发送特定命令来打断智能体。 本文介绍打断智能体的实现方式。 ## 语音打断 [#语音打断] 声网对话式 AI 引擎支持开启优雅打断功能，开启后，用户与智能体互动时，支持基于语义判定用户当前是否结束发言，实现更自然的对话交互体验。 :::info[信息] - 优雅打断为增值服务，开启后会收取费用，详见[计费说明](/zh-CN/ai/reference/pricing)。 - 当语义判定用户未结束发言时，会等待一段时间才最终判定对话结束，此时响应延时会有所增加。 ::: 优雅打断功能默认关闭，你需要在调用 [POST 创建对话式智能体](/zh-CN/api-reference/api-ref/conversational-ai/join)时，设置 `turn_detection.config.end_of_speech.mode` 为 `semantic` 开启优雅打断。以 curl 为例： #### 请求示例 [#请求示例] ```bash curl --request POST \ --url https://api.agora.io/cn/api/conversational-ai-agent/v2/projects/:appid/join \ --header 'Authorization: agora token="007abcxxxxxxx123"' \ --data ' { "name": "unique_name", "properties": { "channel": "channel_name", "token": "token", "agent_rtc_uid": "0", "remote_rtc_uids": [ "123" ], "enable_string_uid": false, "idle_timeout": 120, // highlight-start "turn_detection": { "mode": "default", "config": { "end_of_speech": { "mode": "semantic" "semantic_config": { "silence_duration_ms": 240, "max_wait_ms": 3000 } } } }, // highlight-end "llm": { "url": "https://api.minimax.chat/v2/text/chatcompletion_v2", "api_key": "xxx", "system_messages": [ { "role": "system", "content": "You are a helpful chatbot." } ], "greeting_message": "您好，有什么可以帮您？", "failure_message": "抱歉，我无法回答这个问题。", "max_history": 32, "params": { "model": "abab6.5s-chat", "max_token": 1024, "userName": "Tomas" } }, "asr": { "language": "zh-CN" }, "tts": { "vendor": "minimax", "params": { "group_id": "xxxx", "key": "xxxx", "model": "speech-01-turbo", "voice_setting": { "voice_id": "female-shaonv", "speed": 1, "vol": 1, "pitch": 0, "emotion": "happy" }, "audio_setting": { "sample_rate": 16000 } }, "skip_patterns": [ 1 ] } } } ' ``` #### 响应示例 [#响应示例] 请求成功时返回 200 状态码，响应体如下： ```json { "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB", "create_ts": 1737111452, "status": "RUNNING" } ``` ## 手动打断 [#手动打断] 声网对话式 AI 引擎支持通过调用 RESTful API 或客户端组件 API 主动发起打断请求，从而实现点击按钮或发送特定命令来打断智能体。 ### 方案一：调用 RESTful API [#方案一调用-restful-api] 你可以调用 [POST 打断智能体](/zh-CN/api-reference/api-ref/conversational-ai/interrupt)接口主动发起打断请求。 #### 请求示例 [#请求示例-1] 以 curl 为例： ```bash curl --request POST \ --url https://api.agora.io/cn/api/conversational-ai-agent/v2/projects/:appid/agents/:agentId/interrupt \ --header 'Authorization: agora token="007abcxxxxxxx123"' \ --data '{}' ``` #### 响应示例 [#响应示例-1] 请求成功时返回 200 状态码，响应体如下： ```json { "agent_id": "1NT29XxxxxxxxxELWEHC8OS", "channel": "test_channel", "start_ts": 1744877089 } ``` ### 方案二：调用客户端组件 API [#方案二调用客户端组件-api] 声网提供一套灵活可扩展、标准化的对话式 AI 引擎客户端组件（以下简称组件）。该组件支持 iOS、Android、Web 平台，封装了多个场景化 API，你只需要调用这些 API 即可结合声网[实时互动 (RTC) SDK](/zh-CN/realtime-media/rtc) 和[实时消息 (RTM) SDK](/zh-CN/realtime-media/rtm) 的能力实现以下功能： - [打断智能体](/zh-CN/ai/build/shape-the-conversation/interrupt-agent) - [实时字幕](/zh-CN/ai/build/transcripts) - [监听智能体相关事件](/zh-CN/ai/build/handle-runtime-events/event-notifications) - [设置最佳音频参数](/zh-CN/ai/build/harden-and-optimize/audio-setup) （仅支持 Android 和 iOS） - [发送图片消息](/zh-CN/ai/build/send-multimodal-messages) #### 前提条件 [#前提条件] 开始前，请确保完成以下准备工作： - 已集成 RTC SDK v4.5.1 及以上版本，且已在 App 中实现基本的实时音视频功能并获取相关设备权限。请参考[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。 - 已在[控制台](https://console.shengwang.cn/)为项目启用 RTM 服务，并在 App 中实现基本的实时消息功能。请参考[实现收发消息](/zh-CN/realtime-media/rtm/get-started/quick-start)。 - 已参考[实现对话式智能体](/zh-CN/ai/get-started/quick-start)实现与智能体对话的基本逻辑。 - 确保 RTC 可用、RTM 已登录，且 RTC 和 RTM 实例的生命周期大于组件的生命周期。组件内部不负责维护 RTC，RTM 的初始化、生命周期以及鉴权/登录状态的逻辑。 #### 集成组件 [#集成组件] Android iOS Web Maven 源码集成 #### Maven [#maven] 在 Android 项目的 `build.gradle` 文件中添加如下依赖： ```groovy implementation 'io.agora.agents:agora-agent-client-toolkit:2.10.0' ``` #### 源码集成 [#源码集成] 将 `convoaiApi` 文件夹拷贝到你的项目中，并在后续调用组件 API 前引入组件。 CocoaPods Swift Package Manager 源码集成 #### CocoaPods [#cocoapods] 在 `Podfile` 中添加如下依赖： ```ruby pod 'agent-client-toolkit-swift', '2.10.0' ``` #### Swift Package Manager [#swift-package-manager] 在 Xcode 中添加如下 Package URL，并将版本指定为 tag `2.10.0`： ```text https://github.com/AgoraIO/agent-client-toolkit-swift.git ``` #### 源码集成 [#源码集成-1] 将 `ConversationalAIAPI` 文件夹拷贝到你的项目中，并在后续调用组件 API 前引入组件。 Package Manager 源码集成 #### Package Manager [#package-manager] 根据你的项目类型安装组件依赖。 - Vanilla JS / TypeScript： ```shell pnpm add agora-agent-client-toolkit@2.10.0 ``` - React： ```shell pnpm add agora-agent-client-toolkit@2.10.0 agora-agent-client-toolkit-react@2.10.0 ``` #### 源码集成 [#源码集成-2] 将 `conversational-ai-api` 文件夹拷贝到你的项目中，并在后续调用组件 API 前引入组件。 :::info[信息] 如果在 Android 或 iOS 项目中同时集成多个声网 SDK 时出现库冲突，请参考[多 SDK 库冲突处理](/zh-CN/reference/faq/integration/rtm2_rtc_integration_issue)。 ::: #### 初始化组件 [#初始化组件] 为 RTC 和 RTM 实例创建配置对象，之后创建组件实例： ```kotlin tab="Android" tabGroup="language" val config = ConversationalAIAPIConfig( rtcEngine = rtcEngine, rtmClient = rtmClient, renderMode = TranscriptRenderMode.Word, enableLog = true, enableRenderModeFallback = true ) val api = ConversationalAIAPIImpl(config) ``` ```swift tab="iOS" tabGroup="language" let config = ConversationalAIAPIConfig( rtcEngine: rtcEngine, rtmEngine: rtmEngine, renderMode: .words, enableLog: true, enableRenderModeFallback: true ) convoAIAPI = ConversationalAIAPIImpl(config: config) ``` ```typescript tab="Web" tabGroup="language" const config: IConversationalAIAPIConfig = { rtcEngine: rtcEngine, rtmEngine: rtmEngine, renderMode: ETranscriptHelperMode.WORD, enableLog: true, enableRenderModeFallback: true, }; const conversationalAIAPI = await ConversationalAIAPI.init(config); ``` #### 智能体加入频道 [#智能体加入频道] 调用 [POST 创建对话式智能体](/zh-CN/api-reference/api-ref/conversational-ai/join)接口，并完成以下参数设置： - `advanced_features.enable_rtm: true` —— （必选）启动 RTM 服务 - `parameters.data_channel: "rtm"` —— （必选）开启 RTM 数据传输通道 - `parameters.enable_metrics: true` —— （按需开启）接收智能体性能数据 - `parameters.enable_error_message: true` —— （按需开启）接收智能体错误事件 调用成功后，智能体会加入指定 RTC 频道，用户可以开始与智能体互动。 #### 打断智能体 [#打断智能体] 调用 `interrupt` 方法，打断智能体。 ```kotlin tab="Android" tabGroup="language" api.interrupt("agentId") { error -> /* ... */ } ``` ```swift tab="iOS" tabGroup="language" convoAIAPI.interrupt(agentUserId: "\(agentUid)") { error in if let error = error { print("打断失败: \(error.message)") } else { print("打断成功") } } ``` ```typescript tab="Web" tabGroup="language" await conversationalAIAPI.interrupt(`${agent_rtc_uid}`) ``` #### 销毁组件实例 [#销毁组件实例] 结束 AI 对话场景后或关闭 App 前，你需要销毁组件实例，以释放组件的所有资源。 ```kotlin tab="Android" tabGroup="language" api.destroy() ``` ```swift tab="iOS" tabGroup="language" convoAIAPI.destroy() ``` ```typescript tab="Web" tabGroup="language" conversationalAIAPI.destroy() ``` ## 参考信息 [#参考信息] ### 示例项目 [#示例项目] 声网提供了开源的示例项目供你参考，你可以前往下载或查看其中的源代码。 ### API 参考 [#api-参考] #### RESTful API [#restful-api] - [POST 创建对话式智能体](/zh-CN/api-reference/api-ref/conversational-ai/join) - [POST 打断智能体](/zh-CN/api-reference/api-ref/conversational-ai/interrupt) #### 客户端组件 API [#客户端组件-api] Android iOS Web - [`interrupt`](/zh-CN/api-reference/conversational-ai/android/iconversationalaiapi#interrupt) - [`destroy`](/zh-CN/api-reference/conversational-ai/android/iconversationalaiapi#destroy) - [`interrupt`](/zh-CN/api-reference/conversational-ai/ios/conversationalaiapi#interrupt) - [`destroy`](/zh-CN/api-reference/conversational-ai/ios/conversationalaiapi#destroy) - [`interrupt`](/zh-CN/api-reference/conversational-ai/web/conversationalaiapi#interrupt) - [`destroy`](/zh-CN/api-reference/conversational-ai/web/conversationalaiapi#destroy)