Changelog

ElevenAgents

• 智能体 workflow 中的 MCP 工具范围控制：现在可以限制智能体 workflow 节点中子智能体可调用的 MCP 工具。节点禁用工具继承后，该子智能体仅会加载明确选择的 MCP 工具，让团队能够精确控制每个 workflow 步骤的工具访问权限。

• 对话文件上传：创建智能体和更新智能体端点现在支持 ConversationConfig 中的 file_input 字段。启用后，终端用户可在聊天中附加图片或 PDF（需要支持多模态输入的 LLM）。可通过 enabled（布尔值）和 max_files_per_conversation（整数）配置。

• 重新运行对话分析：新的运行对话分析端点（POST /v1/convai/conversations/{conversation_id}/analysis/run）会使用智能体当前的评估标准和数据收集设置，重新评估已完成的对话，无需发起新通话。

• 测试中的工具响应模拟：智能体模拟测试和测试套件调用现在支持 tool_mock_config 字段，可控制测试期间如何处理工具调用。使用 MockingStrategy（all、selected、none）选择要模拟的工具，并使用 MockNoMatchBehavior（call_real_tool、raise_error）设置没有模拟匹配时的回退行为。

• 文本搜索排序顺序：文本搜索对话端点现在接受 sort_by 查询参数，取值为 search_score（默认）或 created_at，可控制结果按相关性还是新近程度排序。

• mTLS 身份验证连接：除现有选项外，智能体身份验证连接现在支持将双向 TLS（mtls）作为 auth_type。新增 CreateMTLSAuthRequest 和 MTLSAuthResponse schema，可用于创建和获取经 mTLS 身份验证的连接。

• 最长时长消息：智能体配置新增 max_conversation_duration_message 字段。设为非空字符串后，对话达到最长时长时，智能体会向用户发送此消息。

• 对话发起中的分支和环境：对话发起客户端数据（ConversationInitiationClientDataRequest）和提交批量通话请求正文新增可选字段 branch_id 和 environment，支持路由到指定智能体分支和环境。

音乐

• 视频转音乐：新的 POST /v1/music/video-to-music 端点可根据一个或多个视频文件生成背景音乐。视频会按顺序合并。可选的 description（最多 1,000 个字符）和 tags（最多 10 个风格标签，例如 upbeat 或 cinematic）可影响生成的曲目。

语音转文本

• 从 URL 转录：将语音转换为文本端点现在接受 source_url 参数（字符串，可选），可从托管 URL 转录音频或视频，包括 YouTube 视频、TikTok 视频和其他视频托管服务。这可作为直接上传文件的替代方式。

音色

• 共享音色列表中的总数：列出共享音色响应现在包含 total_count 字段，更便于实现分页和显示结果数量。

SDK 发布

JavaScript SDK

• v2.41.0 - 在 ElevenAgents 实时对话中新增对 multimodal_message WebSocket 事件类型的支持。包含针对最新 API schema 更新的 Fern 重新生成。
• v2.41.1 - Fern 重新生成，以匹配 2026 年 4 月 1 日的 API schema。

Python SDK

• v2.41.0 - 将纯文本对话模式中的 audio_interface 修复为可选项，解决未使用音频启动会话时的运行时错误。包含针对最新 API schema 更新的 Fern 重新生成。

软件包

此版本包含新版 v1.0.0 客户端智能体 SDK。@elevenlabs/client、@elevenlabs/react 和 @elevenlabs/react-native 包含重大破坏性变更。升级前请查看以下迁移指南。

为帮助升级，我们发布了一个 Skill，可让智能体帮你完成升级。安装方式：

npx skills add elevenlabs/packages

可在我们的开发者博客了解更多关于 v1 版本及其改进的信息。

• @elevenlabs/client@1.0.0 — 破坏性变更：

  • 不再导出 Input 和 Output 类。请改用 @elevenlabs/client 中的 InputController 和 OutputController 接口。
  • Conversation 不再是一个类，而是命名空间对象，以及 TextConversation | VoiceConversation 的类型别名。请移除所有 instanceof Conversation 检查和子类。
  • 默认 connectionType 现在根据对话模式推断：语音对话默认使用 "webrtc"，纯文本对话默认使用 "websocket"。若要保留之前的语音行为，请显式传入 connectionType: "websocket"。
  • VoiceConversation.wakeLock 现在为私有属性。请在会话选项中传入 useWakeLock: false，以禁用唤醒锁管理。
  • changeInputDevice() 和 changeOutputDevice() 现在返回 Promise<void>，而非 Promise<Input> 或 Promise<Output>。
  • 请将 conversation.input.analyser.getByteFrequencyData(data) 替换为 conversation.getInputByteFrequencyData()。
  • 请将 conversation.input.setMuted(v) 替换为 conversation.setMicMuted(v)。
  • 请将 conversation.output.gain.gain.value = v 替换为 conversation.setVolume({ volume: v })。
  • 未激活对话时，getInputVolume()、getOutputVolume()、getInputByteFrequencyData() 和 getOutputByteFrequencyData() 现在会返回 0 或空的 Uint8Array，而非抛出错误。

• @elevenlabs/react@1.0.0 — 破坏性变更：

  • useConversation 现在需要有 ConversationProvider 父级组件。请使用 <ConversationProvider> 包裹组件树，并将选项移至 provider 或 hook 中。
  • 已移除 DeviceFormatConfig 和 DeviceInputConfig 导出。请改用 @elevenlabs/client 中的 FormatConfig 和 InputDeviceConfig。
  • 新的细粒度 hook 取代了整体式 useConversation，以提升渲染性能：useConversationControls()、useConversationStatus()、useConversationInput()、useConversationMode()、useConversationFeedback() 和 useRawConversation()。每个 hook 仅订阅所需状态，避免不必要的重新渲染。
  • 新增 useConversationClientTool(name, handler) hook，用于注册智能体可调用的客户端工具，并会在卸载时自动清理。
  • 通过 ConversationProvider 上的 isMuted 和 onMutedChange props 新增受控静音支持。

• @elevenlabs/react-native@1.0.0 — 破坏性变更：

  • 之前的 ElevenLabsProvider 和 useConversation API 已移除，改为从 @elevenlabs/react 重新导出。请将 ElevenLabsProvider 替换为 ConversationProvider，并将 useConversation 替换为细粒度 hook（useConversationControls、useConversationStatus 等）。
  • 在 React Native 中，该软件包现在会在导入时填充 WebRTC 全局对象、配置原生 AudioSession，并注册平台特定的语音会话策略。

• @elevenlabs/types@0.8.0 - 导出运行时数组 CALLBACK_KEYS，其中包含 Callbacks 接口的所有键，供 React SDK 在内部组合回调时使用。

• @elevenlabs/client@0.16.0 - 新增服务端到客户端的 guardrail_triggered WebSocket 事件及 onGuardrailTriggered 回调，服务器在对话期间检测到安全护栏违规时会触发该回调。还为 TextConversation 和 VoiceConversation 添加类型判别属性，以支持判别联合类型收窄；并添加 startSession 重载，可根据 textOnly 选项收窄返回类型。

• @elevenlabs/react-native@0.6.0 - 新增 guardrail_triggered WebSocket 事件和 onGuardrailTriggered 回调，与 @elevenlabs/client@0.16.0 保持一致。

• @elevenlabs/client@1.1.0 - 新增在智能体对话中模拟工具响应的客户端支持，可在不调用真实工具的情况下模拟工具调用结果进行测试。

• @elevenlabs/types@0.9.0 - 新增智能体对话中工具响应模拟的类型定义。

• @elevenlabs/react@1.0.1 - 更新为依赖 @elevenlabs/client@1.1.0。

• @elevenlabs/react-native@1.0.1 - 更新为依赖 @elevenlabs/client@1.1.0 和 @elevenlabs/react@1.0.1。

API