ElevenAgents React SDK v1.0

Version 1.0.0 av ElevenAgents JavaScript- och React-SDK är nu tillgänglig. Den här versionen innebär en omstrukturering från grunden av paketen @elevenlabs/client, @elevenlabs/react och @elevenlabs/react-native, med fokus på renderingsprestanda, ett enhetligt API för webben och React Native samt ett stabilt offentligt API. Ändringen är inte bakåtkompatibel, men den välbekanta hooken useConversation finns kvar, och en skill för kodningsagenter kan automatisera uppgraderingen.

Varför en ny huvudversion

Tre problem låg bakom den här versionen.

Olika API:er för webben och React Native

React och React Native hade olika API:er, funktioner och konfigurationsalternativ. Kod och kunskap gick inte att överföra mellan plattformarna, och AI-verktyg för kodning föreslog ofta API:er som bara fanns på en av dem. React Native saknade dessutom helt anslutningsläget WebSocket.

Internt berodde det på att React Native SDK omslöt ett React Native SDK från tredje part i stället för att bygga på @elevenlabs/client. Funktioner och korrigeringar behövde släppas två gånger, och plattformarna gled längre ifrån varandra med varje version.

Dålig renderingsprestanda

Varje tillståndsändring (status, läge, avstängt ljud, volym) renderade om alla komponenter som använde konversationens tillstånd. Det gick inte att prenumerera på bara den del du behövde. Om din komponent bara brydde sig om anslutningsstatus renderades den ändå om när ljudavstängningen ändrades.

Det berodde på att SDK:t använde en enda context provider för hela konversationens tillstånd, med endast grova hooks och callbacks som skickades via alternativobjekt.

Bräckliga uppgraderingar

En uppgradering av SDK:t riskerade att bryta din kod. Interna klasser som Input, Output och Connection var en del av det offentliga API:t, och utvecklare förlitade sig på webbläsarprimitiver som conversation.output.gain.gain.value för volym och conversation.input.analyser för audiovisuell visualisering. Alla interna ändringar kunde bryta dessa åtkomstmönster.

På vår sida gjorde en arvbaserad klasshierarki det svårt att åtgärda detta stegvis, så ett rent avbrott behövdes.

Nyheter

Ett API för alla plattformar

@elevenlabs/react-native återexporterar nu @elevenlabs/react med ett tunt lager för plattformsstrategi: cirka 40 rader kod, jämfört med över tusen tidigare. Samma ConversationProvider, samma hooks, samma metoder. Kod som skrivits för webben fungerar i React Native med endast en ändrad importsökväg, kunskap överförs direkt mellan plattformarna och AI-verktyg för kodning hittar inte längre på plattformsspecifika API:er.

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

Detaljerade hooks för bättre renderingsprestanda

Sex nya hooks prenumererar var och en på en enskild del av konversationens tillstånd. Komponenter renderas bara om när datan de använder ändras.

En statusindikator som tidigare renderades om vid varje tillståndsändring renderas nu bara om när själva anslutningsstatusen ändras:

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

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

useConversation finns fortfarande kvar

Den välbekanta hooken useConversation finns fortfarande kvar och returnerar samma datastruktur: status, läge, ljudavstängning och alla kontrollmetoder. Den är ett praktiskt omslag kring de detaljerade hooks som beskrivs ovan. Befintliga användare kan först migrera till ConversationProvider + useConversation och sedan stegvis använda detaljerade hooks där renderingsprestanda är viktig.

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

Dynamiska klientverktyg

useConversationClientTool låter React-komponenter registrera verktyg som agenten kan anropa. Verktygen är knutna till komponentens livscykel: de registreras vid montering, avregistreras vid avmontering och använder alltid det senaste closure-värdet.

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

Detta är användbart när ett verktygs handler behöver åtkomst till komponenttillstånd eller props som inte är tillgängliga på providernivå.

Stabil API-yta

Interna klasser (Input, Output, wake lock) är nu privata. Det offentliga API:t erbjuder dokumenterade metoder i stället för råa webbläsarprimitiver:

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

Det innebär att den underliggande ljudimplementeringen kan bytas ut, till exempel genom att byta transportlager, utan att användarkoden bryts.

Kontrollerat tillstånd

ConversationProvider accepterar propsen isMuted och onMutedChange för extern tillståndshantering. Det är användbart för att behålla ljudavstängning mellan sessioner eller synkronisera den med tillstånd på applikationsnivå.

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

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

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

När dessa props utelämnas hanteras ljudavstängningen internt som tidigare.

Smart härledning av anslutningstyp

Röstkonversationer använder nu WebRTC som standard och konversationer med enbart text använder WebSocket. I de flesta fall behöver du inte ange connectionType manuellt. Om du behöver en specifik anslutningstyp kan du fortfarande ange den uttryckligen.

Uppgradering

Detta är en ändring som inte är bakåtkompatibel och som kräver uppdateringar av befintliga integreringar. Här är de viktigaste ändringarna:

• Conversation är nu ett namespace-objekt och typalias, inte en klass. Kontroller med instanceof och underklassning fungerar inte längre.
• useConversation kräver en överordnad ConversationProvider.
• Input och Output-klasserna ersätts av dokumenterade metoder på konversationsinstansen.
• I React Native ersätts ElevenLabsProvider av ConversationProvider från @elevenlabs/react-native.

Den fullständiga listan över ändringar som inte är bakåtkompatibla finns i ändringsloggen.

Automatiserad migrering med din kodningsagent

En särskild skill finns för att automatisera uppgraderingen. Skillen läser din befintliga integrering, gör nödvändiga API-ändringar och uppdaterar importer. Den hanterar det mekaniska arbetet med att migrera till ConversationProvider, ersätta borttagna klassreferenser och uppdatera metodanrop.

Skillen är särskilt användbar för större kodbaser där migreringen berör flera filer.

npx skills add elevenlabs/packages

Uppdaterad dokumentation

SDK-dokumentationen har uppdaterats för att återspegla det nya API:t:

• JavaScript SDK
• React SDK
• React Native SDK

Kom igång

Installera paketet för din 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 återexporterar allt från @elevenlabs/client, så du behöver inte installera båda.

Omslut din app med en ConversationProvider, använd hooks för att starta en session och se SDK-dokumentationen för den fullständiga API-referensen.

Och som vi nämnde i inledningen finns en skill för kodningsagenter som kan automatisera uppgraderingen:

npx skills add elevenlabs/packages

Feedback

Om du stöter på problem eller har förslag kan du öppna ett ärende på GitHub. SDK:t underhålls aktivt och vi granskar varje rapport.