ElevenAgents React SDK v1.0

La versione 1.0.0 dell’SDK JavaScript e React di ElevenAgents è ora disponibile. Questa release è una completa riprogettazione dei pacchetti @elevenlabs/client, @elevenlabs/react e @elevenlabs/react-native, con focus sulle prestazioni di rendering, un’API unificata tra web e React Native e una API pubblica stabile. Si tratta di un cambiamento importante, ma il familiare hook useConversation è stato mantenuto ed è disponibile una skill per agenti di coding che automatizza l’aggiornamento.

Perché una nuova major release

Tre problemi principali hanno portato a questa release.

API diverse su web e React Native

React e React Native avevano API, funzionalità e opzioni di configurazione differenti. Il codice e le conoscenze non erano trasferibili tra le piattaforme e spesso gli strumenti di coding IA suggerivano API esistenti solo su una delle due. Inoltre, React Native non supportava affatto la modalità di connessione WebSocket.

Internamente, questo accadeva perché l’SDK React Native si basava su un SDK di terze parti invece di costruire su @elevenlabs/client. Le funzionalità e le correzioni dovevano essere rilasciate due volte e le due piattaforme si allontanavano sempre di più a ogni release.

Prestazioni di rendering insufficienti

Qualsiasi cambiamento di stato (status, modalità, mute, volume) causava il re-render di tutti i componenti che consumavano lo stato della conversazione. Non era possibile iscriversi solo alla parte di stato necessaria. Anche se il tuo componente si interessava solo allo stato della connessione, veniva comunque ri-renderizzato quando cambiava lo stato mute.

Questo succedeva perché l’SDK usava un unico context provider che gestiva tutto lo stato della conversazione, con hook e callback poco specifici passati tramite oggetti di opzioni.

Aggiornamenti fragili

Aggiornare l’SDK poteva rompere il tuo codice. Classi interne come Input, Output e Connessione facevano parte dell’API pubblica e gli sviluppatori si affidavano a primitive del browser come conversation.output.gain.gain.value per il volume e conversation.input.analyser per la visualizzazione audio. Qualsiasi modifica interna poteva interrompere questi pattern di accesso.

Dal nostro lato, una gerarchia di classi basata su ereditarietà rendeva difficile risolvere il problema in modo incrementale, quindi era necessario un cambiamento netto.

Novità

Un’unica API su tutte le piattaforme

@elevenlabs/react-native ora re-esporta @elevenlabs/react con un sottile layer di strategia per la piattaforma: circa 40 righe di codice invece di oltre mille. Stesso ConversationProvider, stessi hook, stessi metodi. Il codice scritto per il web funziona su React Native cambiando solo il path dell’import, le conoscenze si trasferiscono direttamente tra le piattaforme e gli strumenti di coding IA non suggeriscono più API specifiche per una sola piattaforma.

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

Hook granulari per prestazioni di rendering

Sei nuovi hook permettono di iscriversi a singole parti dello stato della conversazione. I componenti vengono ri-renderizzati solo quando cambiano i dati che utilizzano.

Un indicatore di stato che prima si aggiornava a ogni cambiamento ora si aggiorna solo quando cambia lo stato della connessione:

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

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

useConversation è sempre presente

Il familiare hook useConversation esiste ancora e restituisce la stessa struttura di dati: stato, modalità, mute e tutti i metodi di controllo. È un wrapper comodo sopra gli hook granulari descritti sopra. Gli utenti attuali possono migrare a ConversationProvider + useConversation come primo passo, adottando poi gli hook granulari dove servono migliori prestazioni di rendering.

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

Strumenti client dinamici

useConversationClientTool permette ai componenti React di registrare strumenti che l’agente può richiamare. Gli strumenti sono legati al ciclo di vita del componente: si registrano al mount, si deregistrano all’unmount e usano sempre il valore più aggiornato della 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} />;
}

Questo è utile quando l’handler di uno strumento deve accedere a stato o props del componente non disponibili a livello di provider.

API stabile

Le classi interne (Input, Output, wake lock) ora sono private. L’API pubblica espone metodi documentati invece di primitive del browser:

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

Questo significa che l’implementazione audio sottostante può essere sostituita (ad esempio cambiando il livello di trasporto) senza rompere il codice utente.

Stato controllato

ConversationProvider accetta le prop isMuted e onMutedChange per la gestione dello stato esterno. Questo è utile per mantenere lo stato mute tra le sessioni o sincronizzarlo con lo stato dell’applicazione.

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

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

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

Se queste prop non vengono fornite, lo stato mute viene gestito internamente come prima.

Riconoscimento intelligente del tipo di connessione

Le conversazioni vocali ora usano di default WebRTC, mentre quelle solo testuali usano WebSocket. Nella maggior parte dei casi non serve impostare manualmente connectionType. Se hai bisogno di un tipo di connessione specifico, puoi comunque indicarlo esplicitamente.

Aggiornamento

Si tratta di un cambiamento importante che richiede aggiornamenti alle integrazioni esistenti. Ecco le principali novità:

• Conversation ora è un oggetto namespace e un alias di tipo, non più una classe. I controlli instanceof e le sottoclassi non funzionano più.
• useConversation richiede un ConversationProvider come antenato.
• Le classi Input e Output
• sono sostituite da metodi documentati sull’istanza della conversazione.Su React Native, ElevenLabsProvider viene sostituito da ConversationProvider da @elevenlabs/react-native

.Per l’elenco completo dei cambiamenti breaking, consulta il changelog

.

Migrazione automatica con il tuo agente di codingÈ disponibile una skill dedicata per automatizzare l’aggiornamento. La skill legge la tua integrazione attuale, applica le modifiche necessarie all’API e aggiorna gli import. Si occupa del lavoro meccanico di migrazione a ConversationProvider

, sostituendo i riferimenti alle classi rimosse e aggiornando le chiamate ai metodi.

npx skills add elevenlabs/packages

La skill è particolarmente utile per codebase di grandi dimensioni dove la migrazione coinvolge più file.

Documentazione aggiornata

• La documentazione dell’SDK è stata aggiornata per riflettere la nuova API:
• SDK JavaScript
• SDK React

SDK React Native

Per iniziare

# 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

Installa il pacchetto per la tua piattaforma:@elevenlabs/react re-esporta tutto da @elevenlabs/client

, quindi non serve installarli entrambi.Avvolgi la tua app in un ConversationProvider, usa gli hook per avviare una sessione e consulta la documentazione SDK

per il riferimento completo all’API.

npx skills add elevenlabs/packages

Come accennato all’inizio, è disponibile una skill per agenti di coding che automatizza l’aggiornamento:

FeedbackSe riscontri problemi o hai suggerimenti, apri una issue su GitHub