ElevenAgents React SDK v1.0

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.

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

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ą.

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

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

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

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ść.

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.
}

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.

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

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.

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

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

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

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.

npx skills add elevenlabs/packages

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

Zaktualizowana dokumentacja

• Dokumentacja SDK została zaktualizowana i opisuje nowe API:
• JavaScript SDK
• React SDK

React Native SDK

Pierwsze kroki

# 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

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.

npx 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