ElevenAgents React SDK v1.0

Dostępna jest już wersja 1.0.0 JavaScript i React SDK Eleven Agents. To wydanie to przebudowa od podstaw pakietów @elevenlabs/client, @elevenlabs/react i @elevenlabs/react-native, skupiona na wydajności renderowania, wspólnym API dla webu i React Native oraz stabilnym publicznym API. To zmiana niekompatybilna wstecznie, ale znany hook useConversation pozostaje dostępny, a skill dla agenta programistycznego pozwala zautomatyzować aktualizację.

Dlaczego nowa główna wersja

Za tym wydaniem stoją trzy problemy.

Różne API w webie i React Native

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

Wynikało to z tego, że React Native SDK wewnętrznie opakowywał SDK React Native innej firmy, zamiast bazować na @elevenlabs/client. Funkcje i poprawki trzeba było wdrażać dwukrotnie, a obie platformy z każdym wydaniem coraz bardziej się od siebie oddalały.

Słaba wydajność renderowania

Każda zmiana stanu (statusu, trybu, wyciszenia, głośności) powodowała ponowne renderowanie wszystkich komponentów korzystających ze stanu rozmowy. Nie można było subskrybować tylko potrzebnego fragmentu stanu. Jeśli komponent interesował tylko status połączenia, i tak renderował się ponownie przy zmianie wyciszenia.

Działo się tak, ponieważ SDK używało jednego providera kontekstu dla całego stanu rozmowy, tylko z ogólnymi hookami i callbackami przekazywanymi przez obiekty opcji.

Kruche aktualizacje

Aktualizacja SDK mogła zepsuć twój kod. Wewnętrzne klasy, takie jak Input, Output i Connection, były częścią publicznego API, a deweloperzy korzystali z surowych prymitywów przeglądarki, takich jak conversation.output.gain.gain.value do sterowania głośnością oraz conversation.input.analyser do wizualizacji audio. Każda zmiana wewnętrzna mogła zepsuć te sposoby dostępu.

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

Co nowego

Jedno API na wszystkich platformach

@elevenlabs/react-native teraz ponownie eksportuje @elevenlabs/react z cienką warstwą strategii platformy: około 40 linii kodu zamiast ponad tysiąca. Ten sam ConversationProvider, te same hooki, te same metody. Kod napisany dla webu działa w React Native po zmianie samej ścieżki importu, wiedza przenosi się bezpośrednio między platformami, a narzędzia AI do programowania nie halucynują już API specyficznych dla platform.

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

Granularne hooki dla lepszej wydajności renderowania

Sześć nowych hooków subskrybuje po jednym fragmencie stanu rozmowy. Komponenty renderują się ponownie tylko wtedy, gdy zmieniają się dane, z których korzystają.

Wskaźnik statusu, który wcześniej renderował się ponownie przy każdej zmianie stanu, teraz robi to tylko wtedy, gdy zmieni się sam status połączenia:

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

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

useConversation nadal jest dostępny

Znany hook useConversation nadal istnieje i zwraca dane w tym samym formacie: status, tryb, stan wyciszenia i wszystkie metody sterujące. To wygodna nakładka na opisane wyżej granularne hooki. Obecni użytkownicy mogą najpierw przejść na ConversationProvider + useConversation, a potem stopniowo wdrażać granularne hooki tam, gdzie wydajność renderowania ma znaczenie.

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 klienckie

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

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

Przydaje się to, gdy handler narzędzia potrzebuje dostępu do stanu komponentu lub propsów niedostępnych na poziomie providera.

Stabilna powierzchnia API

Wewnętrzne klasy (Input, Output, 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żna wymienić bazową implementację audio (na przykład warstwy transportu) bez psucia kodu użytkownika.

Stan kontrolowany

ConversationProvider przyjmuje propy isMuted i onMutedChange do zewnętrznego zarządzania stanem. Jest to przydatne do zachowania stanu wyciszenia między sesjami lub synchronizacji go 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>
  );
}

Gdy te propy są pominięte, stan wyciszenia jest zarządzany wewnętrznie, tak jak wcześniej.

Inteligentne wykrywanie typu połączenia

Rozmowy głosowe domyślnie korzystają teraz z WebRTC, a rozmowy tylko tekstowe z WebSocket. W większości przypadków nie trzeba ręcznie ustawiać connectionType. Jeśli potrzebujesz konkretnego typu połączenia, nadal możesz przekazać go jawnie.

Aktualizacja

To zmiana niekompatybilna wstecznie, która wymaga aktualizacji istniejących integracji. Najważniejsze zmiany w skrócie:

• Conversation jest teraz obiektem przestrzeni nazw i aliasem typu, a nie klasą. Sprawdzenia instanceof oraz dziedziczenie nie działają już.
• useConversation wymaga nadrzędnego ConversationProvider.
• Input i Output są zastąpione udokumentowanymi metodami instancji rozmowy.
• W React Native ElevenLabsProvider zastępuje ConversationProvider z @elevenlabs/react-native.

Pełną listę zmian niekompatybilnych wstecznie znajdziesz w changelogu.

Automatyczna migracja z agentem programistycznym

Dostępny jest specjalny skill, który automatyzuje aktualizację. Odczytuje on istniejącą integrację, wprowadza potrzebne zmiany w API i aktualizuje importy. Wykonuje techniczną pracę związaną z migracją do ConversationProvider, zastępowaniem usuniętych odwołań do klas i aktualizacją wywołań metod.

Skill jest szczególnie przydatny w większych bazach kodu, gdzie migracja obejmuje wiele plików.

npx skills add elevenlabs/packages

Zaktualizowana dokumentacja

Dokumentacja SDK została zaktualizowana pod kątem nowego API:

• JavaScript SDK
• React SDK
• React Native SDK

Pierwsze kroki

Zainstaluj pakiet dla swojej platformy:

# 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 ponownie eksportuje wszystko z @elevenlabs/client, więc nie musisz instalować obu pakietów.

Owiń aplikację w ConversationProvider, użyj hooków, aby rozpocząć sesję, a pełną dokumentację API znajdziesz w dokumentacji SDK.

Jak wspomnieliśmy we wstępie, dostępny jest skill dla agenta programistycznego, który automatyzuje aktualizację:

npx skills add elevenlabs/packages

Opinie

Jeśli napotkasz problemy lub masz sugestie, otwórz zgłoszenie na GitHubie. SDK jest aktywnie rozwijane i sprawdzamy każde zgłoszenie.