ElevenAgents React SDK v1.0

ElevenAgents JavaScript 和 React SDK 1.0.0 版本现已发布。本次发布对 @elevenlabs/client、@elevenlabs/react 和 @elevenlabs/react-native 进行了全新架构，重点提升渲染性能，实现 Web 与 React Native 统一 API，并提供稳定的公开 API。此版本为重大变更，但常用的 useConversation hook 依然保留，并提供智能体技能自动升级代码。

为何发布新主版本

本次发布主要解决了三个问题。

Web 与 React Native API 不统一

React 和 React Native 拥有不同的 API、功能和配置选项，代码和经验无法在平台间复用，AI 编码工具经常推荐只存在于某个平台的 API。React Native 还完全缺少 WebSocket 连接模式。

出现这种情况，是因为 React Native SDK 封装了第三方 React Native SDK，而不是基于 @elevenlabs/client 开发。每次发布都要重复开发功能和修复，两端差异越来越大。

渲染性能较差

任何状态变化（如状态、模式、静音、音量）都会导致所有使用会话状态的组件重新渲染，无法只订阅所需部分。如果组件只关心连接状态，静音状态变化时也会重新渲染。

原因在于 SDK 使用了一个包含所有会话状态的 context provider，只能通过粗粒度的 hooks 和回调传递选项。

升级不稳定

升级 SDK 时容易导致代码出错。像 输入、输出 和 连接 这样的内部类属于公开 API，开发者还依赖浏览器底层对象，如 conversation.output.gain.gain.value 控制音量，conversation.input.analyser 实现音频可视化。任何内部变动都可能破坏这些用法。

对于我们来说，基于继承的类层级结构难以逐步修复，因此需要彻底重构。

新特性

跨平台统一 API

@elevenlabs/react-native 现在直接复用 @elevenlabs/react，只加了一个约 40 行代码的平台适配层，远少于之前的上千行。相同的 ConversationProvider、相同的 hooks、相同的方法。Web 端代码只需修改导入路径即可在 React Native 上运行，经验可直接迁移，AI 编码工具也不会再推荐平台专属 API。

// On React Native, change this import to '@elevenlabs/react-native'.
import {
  ConversationProvider,
  useConversationControls,
  useConversationStatus,
} from '@elevenlabs/react';

function App() {
  return (
    <ConversationProvider>
      <Agent />
    </ConversationProvider>
  );
}

function Agent() {
  const { startSession, endSession } = useConversationControls();
  const { status } = useConversationStatus();

  if (status === 'connected') {
    return <button onClick={endSession}>End</button>;
  }

  return (
    <button onClick={() => startSession({ agentId: 'agent_7101k5zvyjhmfg983brhmhkd98n6' })}>
      Start
    </button>
  );
}

更细粒度的 hooks 提升渲染性能

新增 6 个 hooks，可分别订阅会话状态的不同部分。组件只会在实际依赖的数据变化时重新渲染。

以前每次状态变化都会重渲的状态指示器，现在只在连接状态变化时才会重渲：

import { useConversationStatus } from '@elevenlabs/react';

function StatusBadge() {
  const { status } = useConversationStatus();
  return <span>{status}</span>;
}

useConversation 依然可用

常用的 useConversation hook 依然存在，返回的数据结构未变，包括状态、模式、静音状态及所有控制方法。它是对上述细粒度 hooks 的便捷封装。现有用户可先迁移到 ConversationProvider + useConversation，再按需逐步使用细粒度 hooks 优化渲染性能。

import { useConversation } from '@elevenlabs/react';

function Agent() {
  const { status, isSpeaking, isMuted, setMuted, startSession, endSession } = useConversation();
  // Same API shape as before, just requires a ConversationProvider ancestor.
}

动态客户端工具

useConversationClientTool 允许 React 组件注册可被智能体调用的工具。工具与组件生命周期绑定：挂载时注册，卸载时注销，并始终使用最新闭包值。

import { useConversationClientTool } from '@elevenlabs/react';
import { useState } from 'react';

function MapComponent() {
  const [location, setLocation] = useState({ lat: 0, lng: 0 });

  useConversationClientTool('getLocation', () => {
    return `${location.lat},${location.lng}`;
  });

  useConversationClientTool('setLocation', (params: { lat: number; lng: number }) => {
    setLocation(params);
    return 'Location updated';
  });

  return <Map center={location} />;
}

当工具处理函数需要访问组件状态或 props，而这些在 provider 层不可用时，这一特性非常有用。

稳定的 API 接口

内部类（输入、输出、wake lock）现已私有化。公开 API 只暴露有文档的方法，不再直接操作浏览器底层对象：

• setVolume({ volume }) 替代 conversation.output.gain.gain.value = v
• getInputByteFrequencyData() 替代 conversation.input.analyser.getByteFrequencyData()
• setMicMuted(true) 替代 conversation.input.setMuted(true)

这样底层音频实现可随时替换（如更换传输层），不会影响用户代码。

受控状态

ConversationProvider 支持 isMuted 和 onMutedChange props，便于外部管理状态。适合在多次会话间持久化静音状态，或与应用全局状态同步。

import { ConversationProvider } from '@elevenlabs/react';
import { useState } from 'react';

function App() {
  const [muted, setMuted] = useState(false);

  return (
    <ConversationProvider isMuted={muted} onMutedChange={setMuted}>
      <YourComponents />
    </ConversationProvider>
  );
}

如未传入这些 props，静音状态将与之前一样由内部管理。

智能连接类型推断

语音会话默认使用 WebRTC，纯文本会话默认使用 WebSocket。大多数情况下无需手动设置 connectionType。如需指定连接类型，也可手动传入。

升级指南

本次为重大变更，需更新现有集成。主要变动如下：

• Conversation 现在是命名空间对象和类型别名，不再是类，instanceof 检查和继承已不可用。
• useConversation 需要 ConversationProvider 作为上级组件。
• 输入 和 输出 类已由会话实例上的文档化方法替代。
• React Native 端，ElevenLabsProvider 已被 ConversationProvider（来自 @elevenlabs/react-native）替代。

完整变更列表请参见 更新日志。

用智能体自动迁移

可用专属技能自动升级。该技能会读取现有集成，自动应用 API 变更并更新导入路径，完成迁移所需的机械性操作，包括迁移到 ConversationProvider、替换已移除的类引用、更新方法调用等。

对于大型代码库，涉及多文件迁移时尤为高效。

npx skills add elevenlabs/packages

文档已更新

SDK 文档已同步新 API：

• JavaScript SDK
• React SDK
• React Native SDK

快速开始

请为所用平台安装对应包：

# React (web)
npm install @elevenlabs/react

# React Native (Expo)
npx expo install @elevenlabs/react-native @livekit/react-native @livekit/react-native-webrtc

# Vanilla JavaScript
npm install @elevenlabs/client

@elevenlabs/react 会复用 @elevenlabs/client 的全部内容，无需重复安装。

用 ConversationProvider 包裹应用，使用 hooks 启动会话，详细 API 参考见 SDK 文档。

如前文所述，可用智能体技能自动升级：

npx skills add elevenlabs/packages

反馈

如遇问题或有建议，请在 GitHub 提交 issue。SDK 持续维护，所有反馈都会被认真处理。