ElevenAgents React SDK v1.0

Eleven Agents JavaScript 和 React SDK 现已发布 1.0.0 版本。本次发布全面重构了 @elevenlabs/client、@elevenlabs/react 和 @elevenlabs/react-native 包，重点提升渲染性能、统一 Web 与 React Native 的 API，并提供稳定的公共 API。这是一次破坏性变更，但保留了熟悉的 useConversation hook，并提供了可自动完成升级的编程智能体 skill。

为何推出新的主版本

此次发布主要解决了 3 个问题。

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 可能导致代码失效。Input、Output 和 Connection 等内部类曾是公共 API 的一部分，开发者还依赖 conversation.output.gain.gain.value 等原始浏览器接口控制音量，以及 conversation.input.analyser 实现音频可视化。任何内部变更都可能破坏这些访问方式。

继承式类层级结构也使我们难以渐进式修复，因此需要彻底重构。

新功能

跨平台统一 API

@elevenlabs/react-native 现在通过一个轻量的平台策略层重新导出 @elevenlabs/react：代码从超过 1,000 行减少到约 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 个新 hook 分别订阅对话状态中的单独片段。只有使用的数据变化时，组件才会重新渲染。

过去会随每次状态变化重新渲染的状态指示器，现在仅在连接状态本身变化时重新渲染：

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} />;
}

当工具处理程序需要访问 provider 层级无法获取的组件状态或 props 时，这项功能尤其有用。

稳定的 API 接口

内部类（Input、Output、唤醒锁）现已设为私有。公共 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。
• Input 和 Output 类已由对话实例中有文档说明的方法取代。
• 在 React Native 中，ElevenLabsProvider 已替换为来自 ConversationProvider 的 @elevenlabs/react-native。

完整的破坏性变更列表请参阅更新日志。

使用编程智能体自动迁移

我们提供专用 skill，可自动完成升级。它会读取现有集成，应用必要的 API 变更并更新导入。它可处理迁移到 ConversationProvider、替换已移除的类引用及更新方法调用等机械性工作。

对于迁移涉及多个文件的大型代码库，这个 skill 尤其有用。

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 启动会话，并参阅SDK 文档获取完整 API 参考。

如开头所述，我们还提供了可自动完成升级的编程智能体 skill：

npx skills add elevenlabs/packages

反馈

如遇到问题或有任何建议，请在 GitHub 上提交 issue。SDK 正在持续维护，我们会审阅每一份报告。