ElevenAgents React SDK v1.0

Version 1.0.0 av ElevenAgents JavaScript- och React-SDK finns nu tillgänglig. Den här versionen är en total omarbetning av @elevenlabs/client, @elevenlabs/react och @elevenlabs/react-native-paketen, med fokus på renderingsprestanda, ett enhetligt API för webben och React Native, samt ett stabilt publikt API. Det är en förändring som bryter bakåtkompatibilitet, men den välkända useConversation-hooken finns kvar, och en kodagent-funktion finns tillgänglig för att automatisera uppgraderingen.

Varför en ny huvudversion

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

Olika API:er på webben och React Native

React och React Native hade olika API:er, olika funktioner och olika inställningsmöjligheter. Kod och kunskap gick inte att återanvända mellan plattformarna, och AI-kodverktyg föreslog ofta API:er som bara fanns på en plattform. React Native saknade dessutom helt WebSocket-läge.

Internt berodde det här på att React Native-SDK:n byggde på en tredjeparts-SDK istället för att bygga på @elevenlabs/client. Funktioner och buggfixar behövde släppas två gånger, och plattformarna gled längre ifrån varandra för varje version.

Dålig renderingsprestanda

Varje ändring av tillstånd (status, läge, mute, volym) renderade om alla komponenter som använde samtalstillståndet. 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 mute-läget ändrades.

Detta berodde på att SDK:n använde en enda context provider för allt samtalstillstånd, med bara grova hooks och callbacks via options-objekt.

Sköra uppgraderingar

Att uppgradera SDK:n riskerade att bryta din kod. Interna klasser som Inmatning, Utmatning och Anslutning var en del av det publika API:et, och utvecklare använde råa browser-primitiver som conversation.output.gain.gain.value för volym och conversation.input.analyser för ljudvisualisering. Alla interna ändringar kunde bryta dessa sätt att komma åt data.

För vår del gjorde ett arvbaserat klassystem det svårt att fixa detta stegvis, så en ren omstart behövdes.

Vad är nytt

Ett API för alla plattformar

@elevenlabs/react-native exporterar nu vidare @elevenlabs/react med ett tunt plattforms-lager: cirka 40 rader kod istället för över tusen. Samma ConversationProvider, samma hooks, samma metoder. Kod skriven för webben fungerar på React Native med bara en ändrad import-sökväg, kunskap kan användas direkt mellan plattformarna och AI-kodverktyg hittar inte längre på plattformsunika 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 prestanda

Sex nya hooks prenumererar var och en på en specifik del av samtalstillståndet. Komponenter renderas bara om när just deras data ä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älkända useConversation-hooken finns kvar och returnerar samma typ av data: status, läge, mute-läge och alla kontrollmetoder. Det är ett smidigt wrapper över de mer detaljerade hooks som beskrivs ovan. Befintliga användare kan börja med att byta till ConversationProvider + useConversation som första steg, och sedan gradvis använda mer detaljerade hooks där prestanda är viktigt.

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 använda. Verktygen kopplas till komponentens livscykel: de registreras vid mount, avregistreras vid unmount och använder alltid det senaste värdet från 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} />;
}

Det här är användbart när en verktygsfunktion behöver komma åt komponentens state eller props som inte finns tillgängliga på providernivå.

Stabilt API

Interna klasser (Inmatning, Utmatning, wake lock) är nu privata. Det publika API:et visar dokumenterade metoder istället för råa browser-primitiver:

• 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)

Detta innebär att den underliggande ljudlösningen kan bytas ut (till exempel byta transportlager) utan att användarens kod bryts.

Kontrollerat tillstånd

ConversationProvider accepterar isMuted och onMutedChange props för extern hantering av tillstånd. Det är användbart om du vill spara mute-läget mellan sessioner eller synka det med applikationens tillstånd.

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

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

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

Om dessa props utelämnas hanteras mute-läget internt som tidigare.

Smart val av anslutningstyp

Röstsamtal använder nu WebRTC som standard och textbaserade samtal använder WebSocket som standard. Du behöver oftast inte ange connectionType manuellt. Om du behöver en viss anslutningstyp kan du fortfarande ange det själv.

Uppgradering

Detta är en förändring som bryter bakåtkompatibilitet och kräver uppdateringar i befintliga integrationer. Här är de viktigaste ändringarna:

• Conversation är nu ett namespace-objekt och en typalias, inte en klass. instanceof-kontroller och subklassning fungerar inte längre.
• useConversation kräver en ConversationProvider som förälder.
• Inmatning och Utmatning-klasserna ersätts av dokumenterade metoder på samtalsinstansen.
• På React Native ersätts ElevenLabsProvider av ConversationProvider från @elevenlabs/react-native.

För hela listan över förändringar, se ändringslogg.

Automatiserad migrering med din kodagent

En särskild funktion finns för att automatisera uppgraderingen. Funktionen läser din nuvarande integration, gör nödvändiga API-ändringar och uppdaterar imports. Den tar hand om det mekaniska arbetet med att migrera till ConversationProvider, byter ut borttagna klassreferenser och uppdaterar metodanrop.

Funktionen är särskilt användbar för större kodbaser där migreringen påverkar många filer.

npx skills add elevenlabs/packages

Uppdaterad dokumentation

SDK-dokumentationen har uppdaterats för att visa det nya API:et:

• 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 exporterar allt från @elevenlabs/client, så du behöver inte installera båda.

Lägg in din app i en ConversationProvider, använd hooks för att starta en session och läs SDK-dokumentationen för hela API-referensen.

Och som vi nämnde i början finns en kodagent-funktion för att automatisera uppgraderingen:

npx skills add elevenlabs/packages

Feedback

Om du stöter på problem eller har förslag, skapa ett ärende på GitHub. SDK:n underhålls aktivt och vi går igenom alla rapporter.