ElevenAgents React SDK v1.0

Ostatnia aktualizacja 27 mar 2026 • 8 minut czytania

Photograph of Kræn Hansen facing the camera.

Kræn Hansen, Developer Experience Engineer

ElevenAgents React SDK v1.0.0: nowa wersja SDK JavaScript i React z dokładnymi hookami, wspólnym API dla weba i React Native oraz stabilnym publicznym API.

Cover with ElevenAgents, React and SDK v1

Przeczytaj dokumentację Zobacz na GitHubie

Wersja 1.0.0 ElevenAgents JavaScript i React SDK jest już dostępna. To całkowicie przebudowana wersja @elevenlabs/client, @elevenlabs/react i @elevenlabs/react-native skupiona na wydajności renderowania, wspólnym API dla weba i React Native oraz stabilnym publicznym API. To zmiana niekompatybilna wstecz, ale znany hook useConversation zostaje, a do automatycznej aktualizacji możesz użyć umiejętności agenta kodującego.

Dlaczego nowa główna wersja

Trzy problemy skłoniły nas do tej zmiany.

Różne API na webie i React Native

React i React Native miały inne API, różne funkcje i opcje konfiguracji. Kod i wiedza nie przenosiły się między platformami, a narzędzia AI często podpowiadały API dostępne tylko na jednej z nich. W React Native brakowało też trybu połączenia WebSocket.

Wynikało to z tego, że SDK React Native opierało się na zewnętrznym SDK zamiast na @elevenlabs/client. Funkcje i poprawki trzeba było wdrażać podwójnie, a platformy coraz bardziej się różniły.

Słaba wydajność renderowania

Każda zmiana stanu (status, tryb, wyciszenie, głośność) powodowała ponowne renderowanie wszystkich komponentów korzystających ze stanu rozmowy. Nie dało się subskrybować tylko wybranego fragmentu. Nawet jeśli komponent sprawdzał tylko status połączenia, renderował się też przy zmianie wyciszenia.

SDK korzystało z jednego providera contextu obejmującego cały stan rozmowy, a hooki i callbacki były przekazywane tylko przez obiekty options.

Kłopotliwe aktualizacje

Aktualizacja SDK mogła psuć twój kod. Klasy wewnętrzne jak Wejście, Wyjście i Połączenie były częścią publicznego API, a deweloperzy korzystali z surowych prymitywów przeglądarki jak conversation.output.gain.gain.value do głośności i conversation.input.analyser do wizualizacji dźwięku. Każda zmiana wewnątrz mogła to popsuć.

Po naszej stronie hierarchia klas oparta na dziedziczeniu utrudniała stopniowe poprawki, więc potrzebne było czyste odcięcie.

Co nowego

Jedno API na wszystkich platformach

@elevenlabs/react-native teraz eksportuje ponownie @elevenlabs/react z cienką warstwą strategii platformowej: ok. 40 linii kodu zamiast ponad tysiąca. Ten sam ConversationProvider, te same hooki, te same metody. Kod napisany na web działa w React Native po zmianie ścieżki importu, wiedza przechodzi bezpośrednio, a narzędzia AI nie wymyślają już API specyficznych dla platformy.

1// On React Native, change this import to '@elevenlabs/react-native'.
2import {
3  ConversationProvider,
4  useConversationControls,
5  useConversationStatus,
6} from '@elevenlabs/react';
7
8function App() {
9  return (
10    <ConversationProvider>
11      <Agent />
12    </ConversationProvider>
13  );
14}
15
16function Agent() {
17  const { startSession, endSession } = useConversationControls();
18  const { status } = useConversationStatus();
19
20  if (status === 'connected') {
21    return <button onClick={endSession}>End</button>;
22  }
23
24  return (
25    <button onClick={() => startSession({ agentId: 'agent_7101k5zvyjhmfg983brhmhkd98n6' })}>
26      Start
27    </button>
28  );
29}

Dokładne hooki dla wydajności

Sześć nowych hooków subskrybuje wybrane fragmenty stanu rozmowy. Komponenty renderują się tylko, gdy zmieniają się dane, z których korzystają.

Hook

Returns

Re-renders on

useConversationControls

Action methods (startSession, endSession, sendUserMessage, ...)

Never (stable references)

useConversationStatus

status, message

Connection status changes

useConversationInput

isMuted, setMuted

Mute state changes

useConversationMode

mode, isSpeaking, isListening

Mode changes

useConversationFeedback

canSendFeedback, sendFeedback

Feedback availability changes

useConversationClientTool

(registers a tool handler)

Never

Wskaźnik statusu, który wcześniej renderował się przy każdej zmianie stanu, teraz renderuje się tylko przy zmianie statusu połączenia:

1import { useConversationStatus } from '@elevenlabs/react';
2
3function StatusBadge() {
4  const { status } = useConversationStatus();
5  return <span>{status}</span>;
6}

`useConversation` nadal jest

Znany hook useConversation dalej istnieje i zwraca te same dane: status, tryb, wyciszenie i wszystkie metody sterujące. To wygodna nakładka na dokładne hooki opisane wyżej. Możesz najpierw przejść na ConversationProvider + useConversation, a potem stopniowo wdrażać dokładne hooki tam, gdzie liczy się wydajność.

1import { useConversation } from '@elevenlabs/react';
2
3function Agent() {
4  const { status, isSpeaking, isMuted, setMuted, startSession, endSession } = useConversation();
5  // Same API shape as before, just requires a ConversationProvider ancestor.
6}

Dynamiczne narzędzia klienta

useConversationClientTool pozwala komponentom React rejestrować narzędzia, które agent może wywołać. Narzędzia są powiązane z cyklem życia komponentu: rejestrują się przy montowaniu, usuwają przy odmontowaniu i zawsze korzystają z najnowszej wartości.

1import { useConversationClientTool } from '@elevenlabs/react';
2import { useState } from 'react';
3
4function MapComponent() {
5  const [location, setLocation] = useState({ lat: 0, lng: 0 });
6
7  useConversationClientTool('getLocation', () => {
8    return `${location.lat},${location.lng}`;
9  });
10
11  useConversationClientTool('setLocation', (params: { lat: number; lng: number }) => {
12    setLocation(params);
13    return 'Location updated';
14  });
15
16  return <Map center={location} />;
17}

To przydatne, gdy handler narzędzia potrzebuje dostępu do stanu lub propsów komponentu, których nie ma na poziomie providera.

Stabilne publiczne API

Klasy wewnętrzne (Wejście, Wyjście, wake lock) są teraz prywatne. Publiczne API udostępnia udokumentowane metody zamiast surowych prymitywów przeglądarki:

setVolume({ volume }) zastępuje conversation.output.gain.gain.value = v
getInputByteFrequencyData() zastępuje conversation.input.analyser.getByteFrequencyData()
setMicMuted(true) zastępuje conversation.input.setMuted(true)

Dzięki temu możemy zmienić implementację audio (np. warstwę transportową) bez psucia twojego kodu.

Sterowanie stanem

ConversationProvider przyjmuje propsy isMuted i onMutedChange do zewnętrznego zarządzania stanem. To przydatne, jeśli chcesz zapamiętać wyciszenie między sesjami lub zsynchronizować je ze stanem aplikacji.

1import { ConversationProvider } from '@elevenlabs/react';
2import { useState } from 'react';
3
4function App() {
5  const [muted, setMuted] = useState(false);
6
7  return (
8    <ConversationProvider isMuted={muted} onMutedChange={setMuted}>
9      <YourComponents />
10    </ConversationProvider>
11  );
12}

Jeśli nie podasz tych propsów, stan wyciszenia jest zarządzany wewnętrznie jak wcześniej.

Automatyczne wykrywanie typu połączenia

Rozmowy głosowe domyślnie używają WebRTC, a tekstowe WebSocket. W większości przypadków nie musisz ustawiać connectionType ręcznie. Jeśli potrzebujesz konkretnego typu, możesz go nadal podać.

Aktualizacja

To zmiana niekompatybilna wstecz, więc wymaga aktualizacji integracji. Najważniejsze zmiany:

Conversation to teraz obiekt namespace i alias typu, nie klasa. instanceof i dziedziczenie już nie działają.
useConversation wymaga przodka ConversationProvider.
Klasy Input i Output
zastąpiono udokumentowanymi metodami na instancji rozmowy.W React Native ElevenLabsProvider zastępuje ConversationProvider z @elevenlabs/react-native

.Pełną listę zmian znajdziesz w changelog

.

Automatyczna migracja z agentem kodującymDostępna jest dedykowana umiejętność do automatycznej aktualizacji. Odczytuje twoją integrację, wprowadza potrzebne zmiany w API i aktualizuje importy. Zajmuje się mechaniczną stroną migracji na ConversationProvider

, zamienia usunięte klasy i aktualizuje wywołania metod.

1npx skills add elevenlabs/packages

To szczególnie przydatne przy większych projektach, gdzie migracja dotyczy wielu plików.

Zaktualizowana dokumentacja

React Native SDK

Pierwsze kroki

1# React (web)
2npm install @elevenlabs/react
3
4# React Native (Expo)
5npx expo install @elevenlabs/react-native @livekit/react-native @livekit/react-native-webrtc
6
7# Vanilla JavaScript
8npm install @elevenlabs/client

Zainstaluj paczkę dla swojej platformy:@elevenlabs/react eksportuje wszystko z @elevenlabs/client

, więc nie musisz instalować obu.Owiń aplikację w ConversationProvider, użyj hooków, żeby rozpocząć sesję i zajrzyj do dokumentacji SDK

po pełny opis API.

1npx skills add elevenlabs/packages

Jak wspomnieliśmy na początku, możesz użyć umiejętności agenta kodującego do automatycznej aktualizacji:

Masz uwagi?Jeśli napotkasz problem lub masz sugestie, zgłoś issue na GitHubie

Przeglądaj artykuły zespołu ElevenLabs

ElevenAgents Stories