ElevenAgents React SDK v1.0

Version 1.0.0 des ElevenAgents JavaScript- und React-SDK ist jetzt verfügbar. Dieses Release gestaltet die Pakete @elevenlabs/client, @elevenlabs/react und @elevenlabs/react-native von Grund auf neu. Im Fokus stehen die Render-Performance, eine einheitliche API für Web und React Native sowie eine stabile öffentliche API. Es handelt sich um eine Breaking Change, aber der vertraute useConversation Hook bleibt erhalten. Außerdem steht ein Coding-Agent-Skill zur Automatisierung des Upgrades bereit.

Warum eine neue Hauptversion

Drei Probleme waren ausschlaggebend für dieses Release.

Unterschiedliche APIs für Web und React Native

React und React Native hatten unterschiedliche APIs, Funktionsumfänge und Konfigurationsoptionen. Code und Wissen ließen sich nicht zwischen den Plattformen übertragen, und KI-Coding-Tools schlugen häufig APIs vor, die nur auf einer Plattform existierten. React Native fehlte außerdem vollständig ein WebSocket-Verbindungsmodus.

Intern lag das daran, dass das React-Native-SDK ein React-Native-SDK eines Drittanbieters umschloss, statt auf @elevenlabs/client aufzubauen. Features und Fehlerbehebungen mussten doppelt veröffentlicht werden, und die beiden Plattformen entwickelten sich mit jedem Release weiter auseinander.

Schwache Render-Performance

Jede Statusänderung (Status, Modus, Stummschaltung, Lautstärke) führte zum erneuten Rendern jeder Komponente, die den Gesprächsstatus nutzte. Es gab keine Möglichkeit, nur den benötigten Teil zu abonnieren. Wenn Ihre Komponente sich nur für den Verbindungsstatus interessierte, wurde sie trotzdem erneut gerendert, wenn sich die Stummschaltung änderte.

Der Grund war, dass das SDK einen einzigen Context Provider für den gesamten Gesprächsstatus verwendete, mit nur grobgranularen Hooks und Callbacks, die über Optionsobjekte übergeben wurden.

Anfällige Upgrades

Ein SDK-Upgrade konnte Ihren Code beschädigen. Interne Klassen wie Input, Output und Connection waren Teil der öffentlichen API. Entwickler verwendeten Browser-Primitiven wie conversation.output.gain.gain.value für die Lautstärke und conversation.input.analyser zur Audiovisualisierung. Jede interne Änderung konnte diese Zugriffsmuster beeinträchtigen.

Auf unserer Seite erschwerte eine vererbungsbasierte Klassenhierarchie schrittweise Korrekturen. Daher war ein klarer Schnitt nötig.

Was ist neu

Eine API für alle Plattformen

@elevenlabs/react-native exportiert jetzt @elevenlabs/react über eine schlanke Plattformstrategie erneut: rund 40 statt über tausend Codezeilen. Derselbe ConversationProvider, dieselben Hooks, dieselben Methoden. Für das Web geschriebener Code funktioniert in React Native mit lediglich einem geänderten Importpfad. Wissen lässt sich direkt zwischen Plattformen übertragen, und KI-Coding-Tools halluzinieren keine plattformspezifischen APIs mehr.

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

Granulare Hooks für bessere Render-Performance

Sechs neue Hooks abonnieren jeweils einen einzelnen Teil des Gesprächsstatus. Komponenten werden nur erneut gerendert, wenn sich die Daten ändern, die sie nutzen.

Ein Statusindikator, der bisher bei jeder Statusänderung erneut gerendert wurde, wird nun nur noch bei Änderungen des Verbindungsstatus selbst erneut gerendert:

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

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

useConversation ist weiterhin verfügbar

Der vertraute useConversation Hook existiert weiterhin und gibt dieselbe Datenstruktur zurück: Status, Modus, Stummschaltung und alle Steuerungsmethoden. Er ist ein praktischer Wrapper für die oben beschriebenen granularen Hooks. Bestehende Nutzer können zunächst zu ConversationProvider + useConversation migrieren und anschließend granulare Hooks dort schrittweise einführen, wo die Render-Performance wichtig ist.

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

Dynamische Client-Tools

useConversationClientTool ermöglicht React-Komponenten, Tools zu registrieren, die der Agent aufrufen kann. Tools sind an den Lebenszyklus der Komponente gebunden: Sie werden beim Mounten registriert, beim Unmounten abgemeldet und verwenden immer den neuesten Closure-Wert.

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

Das ist nützlich, wenn der Handler eines Tools Zugriff auf Komponentenstatus oder Props benötigt, die auf Provider-Ebene nicht verfügbar sind.

Stabile API-Oberfläche

Interne Klassen (Input, Output, Wake Lock) sind jetzt privat. Die öffentliche API stellt dokumentierte Methoden statt roher Browser-Primitiven bereit:

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

Dadurch kann die zugrunde liegende Audioimplementierung ersetzt werden, etwa durch einen Austausch der Transportebenen, ohne den Code der Nutzer zu beeinträchtigen.

Kontrollierter Status

ConversationProvider akzeptiert isMuted und onMutedChange Props für die externe Statusverwaltung. Das ist nützlich, um die Stummschaltung sitzungsübergreifend zu speichern oder mit dem Status auf Anwendungsebene zu synchronisieren.

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

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

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

Wenn diese Props nicht angegeben werden, wird die Stummschaltung wie bisher intern verwaltet.

Intelligente Ermittlung des Verbindungstyps

Sprachgespräche verwenden nun standardmäßig WebRTC, reine Textgespräche WebSocket. In den meisten Fällen müssen Sie connectionType nicht manuell festlegen. Falls Sie einen bestimmten Verbindungstyp benötigen, können Sie ihn weiterhin explizit übergeben.

Upgrade

Dies ist eine Breaking Change, die Anpassungen bestehender Integrationen erfordert. Die wichtigsten Änderungen im Überblick:

• Conversation ist jetzt ein Namespace-Objekt und Typalias, keine Klasse. instanceof-Prüfungen und Vererbung funktionieren nicht mehr.
• useConversation benötigt einen übergeordneten ConversationProvider.
• Input- und Output-Klassen werden durch dokumentierte Methoden der Gesprächsinstanz ersetzt.
• In React Native wird ElevenLabsProvider durch ConversationProvider aus @elevenlabs/react-native ersetzt.

Die vollständige Liste der Breaking Changes finden Sie im Changelog.

Automatisierte Migration mit Ihrem Coding-Agent

Ein spezieller Skill steht zur Verfügung, um das Upgrade zu automatisieren. Der Skill liest Ihre bestehende Integration, nimmt die erforderlichen API-Änderungen vor und aktualisiert Imports. Er übernimmt die mechanische Arbeit bei der Migration zu ConversationProvider, beim Ersetzen entfernter Klassenreferenzen und beim Aktualisieren von Methodenaufrufen.

Der Skill ist besonders nützlich für größere Codebasen, bei denen die Migration mehrere Dateien betrifft.

npx skills add elevenlabs/packages

Aktualisierte Dokumentation

Die SDK-Dokumentation wurde für die neue API aktualisiert:

• JavaScript SDK
• React SDK
• React Native SDK

Erste Schritte

Installieren Sie das Paket für Ihre Plattform:

# 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 exportiert alles aus @elevenlabs/client erneut. Sie müssen daher nicht beide installieren.

Umschließen Sie Ihre App mit einem ConversationProvider, verwenden Sie die Hooks zum Starten einer Sitzung und lesen Sie die SDK-Dokumentation für die vollständige API-Referenz.

Wie in der Einleitung erwähnt, steht außerdem ein Coding-Agent-Skill zur Automatisierung des Upgrades bereit:

npx skills add elevenlabs/packages

Feedback

Wenn Probleme auftreten oder Sie Vorschläge haben, eröffnen Sie ein Issue auf GitHub. Das SDK wird aktiv gepflegt, und wir prüfen jede Meldung.