ElevenAgents React SDK v1.0

Versie 1.0.0 van de ElevenAgents JavaScript- en React-SDK is nu beschikbaar. Deze release is een volledige herstructurering van de pakketten @elevenlabs/client, @elevenlabs/react en @elevenlabs/react-native, met focus op renderprestaties, een uniforme API voor web en React Native, en een stabiele openbare API. Het is een breaking change, maar de vertrouwde useConversation-hook blijft behouden en er is een coding agent skill beschikbaar om de upgrade te automatiseren.

Waarom een nieuwe hoofdversie

Drie problemen lagen aan de basis van deze release.

Verschillende API's voor web en React Native

React en React Native hadden verschillende API's, functiesets en configuratieopties. Code en kennis waren niet overdraagbaar tussen platforms, en AI-codingtools stelden vaak API's voor die slechts op één platform bestonden. React Native had bovendien helemaal geen WebSocket-verbindingsmodus.

Intern kwam dit doordat de React Native SDK een React Native SDK van derden omvatte in plaats van voort te bouwen op @elevenlabs/client. Functies en fixes moesten twee keer worden uitgebracht, en de twee platforms groeiden met elke release verder uit elkaar.

Slechte renderprestaties

Elke statuswijziging (status, modus, dempen, volume) zorgde ervoor dat elk component dat de gespreksstatus gebruikte opnieuw werd gerenderd. Je kon je niet alleen abonneren op het deel dat je nodig had. Als je component alleen de verbindingsstatus nodig had, werd het nog steeds opnieuw gerenderd wanneer de dempstatus veranderde.

Dit kwam doordat de SDK één contextprovider gebruikte voor de volledige gespreksstatus, met alleen grove hooks en callbacks die via optiesobjecten werden doorgegeven.

Kwetsbare upgrades

Door de SDK te upgraden kon je code kapotgaan. Interne klassen zoals Input, Output en Connection maakten deel uit van de openbare API, en ontwikkelaars vertrouwden op onbewerkte browserprimitieven zoals conversation.output.gain.gain.value voor volume en conversation.input.analyser voor audiovisualisatie. Elke interne wijziging kon deze toegangspatronen breken.

Aan onze kant maakte een op overerving gebaseerde klassenhiërarchie het lastig dit stapsgewijs op te lossen, dus was een duidelijke breuk nodig.

Wat is er nieuw

Eén API voor alle platforms

@elevenlabs/react-native exporteert nu opnieuw @elevenlabs/react met een dunne platformstrategielaag: ongeveer 40 regels code, in plaats van meer dan duizend. Dezelfde ConversationProvider, dezelfde hooks, dezelfde methoden. Code die voor het web is geschreven werkt ook op React Native met alleen een aangepast importpad, kennis is direct overdraagbaar tussen platforms en AI-codingtools hallucineren niet langer platformspecifieke API's.

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

Gedetailleerde hooks voor renderprestaties

Zes nieuwe hooks abonneren zich elk op een afzonderlijk deel van de gespreksstatus. Componenten worden alleen opnieuw gerenderd wanneer de data die ze gebruiken verandert.

Een statusindicator die eerder bij elke statuswijziging opnieuw werd gerenderd, wordt nu alleen opnieuw gerenderd wanneer de verbindingsstatus zelf verandert:

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

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

useConversation bestaat nog steeds

De vertrouwde useConversation-hook bestaat nog steeds en retourneert dezelfde datastructuur: status, modus, dempstatus en alle besturingsmethoden. Het is een handige wrapper rond de hierboven beschreven gedetailleerde hooks. Bestaande gebruikers kunnen als eerste stap migreren naar ConversationProvider + useConversation en vervolgens geleidelijk gedetailleerde hooks gebruiken waar renderprestaties belangrijk zijn.

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 clienttools

useConversationClientTool laat React-componenten tools registreren die de agent kan aanroepen. Tools zijn gekoppeld aan de componentlevenscyclus: ze worden geregistreerd bij mounten, verwijderd bij unmounten en gebruiken altijd de nieuwste closurewaarde.

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

Dit is nuttig wanneer de handler van een tool toegang nodig heeft tot de status of props van een component die niet beschikbaar zijn op providerniveau.

Stabiel API-oppervlak

Interne klassen (Input, Output, wake lock) zijn nu privé. De openbare API biedt gedocumenteerde methoden in plaats van onbewerkte browserprimitieven:

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

Dit betekent dat de onderliggende audio-implementatie kan worden vervangen, bijvoorbeeld door transportlagen te wisselen, zonder dat gebruikerscode kapotgaat.

Beheerde status

ConversationProvider accepteert de props isMuted en onMutedChange voor extern statusbeheer. Dit is nuttig om de dempstatus tussen sessies te behouden of die te synchroniseren met status op applicatieniveau.

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

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

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

Wanneer deze props worden weggelaten, wordt de dempstatus intern beheerd zoals voorheen.

Slimme afleiding van het verbindingstype

Spraakgesprekken gebruiken nu standaard WebRTC en gesprekken met alleen tekst standaard WebSocket. In de meeste gevallen hoef je connectionType niet handmatig in te stellen. Als je een specifiek verbindingstype nodig hebt, kun je het nog steeds expliciet doorgeven.

Upgraden

Dit is een breaking change waarvoor bestaande integraties moeten worden bijgewerkt. De belangrijkste wijzigingen op een rij:

• Conversation is nu een namespaceobject en typealias, geen klasse. instanceof-controles en overerving werken niet langer.
• useConversation vereist een bovenliggende ConversationProvider.
• Input- en Output-klassen zijn vervangen door gedocumenteerde methoden op de gespreksinstantie.
• Op React Native wordt ElevenLabsProvider vervangen door ConversationProvider uit @elevenlabs/react-native.

Bekijk de wijzigingslog voor de volledige lijst met breaking changes.

Geautomatiseerde migratie met je coding agent

Er is een speciale skill beschikbaar om de upgrade te automatiseren. De skill leest je bestaande integratie, past de benodigde API-wijzigingen toe en werkt imports bij. De skill regelt het technische werk van het migreren naar ConversationProvider, het vervangen van verwijzingen naar verwijderde klassen en het bijwerken van methodeaanroepen.

De skill is vooral nuttig voor grotere codebases waarbij de migratie meerdere bestanden raakt.

npx skills add elevenlabs/packages

Bijgewerkte documentatie

De SDK-documentatie is bijgewerkt voor de nieuwe API:

• JavaScript SDK
• React SDK
• React Native SDK

Aan de slag

Installeer het pakket voor je platform:

# 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 exporteert alles opnieuw uit @elevenlabs/client, dus je hoeft niet beide te installeren.

Plaats je app in een ConversationProvider, gebruik de hooks om een sessie te starten en raadpleeg de SDK-documentatie voor de volledige API-referentie.

En zoals we in de inleiding noemden, is er een coding agent skill beschikbaar om de upgrade te automatiseren:

npx skills add elevenlabs/packages

Feedback

Als je problemen ondervindt of suggesties hebt, open dan een issue op GitHub. De SDK wordt actief onderhouden en we beoordelen elke melding.