ElevenAgents React SDK v1.0

La versione 1.0.0 dell'SDK JavaScript e React di ElevenAgents è ora disponibile. Questa release ristruttura da zero i pacchetti @elevenlabs/client, @elevenlabs/react, e @elevenlabs/react-native, con particolare attenzione alle prestazioni di rendering, a un'API unificata per web e React Native e a un'API pubblica stabile. È una breaking change, ma il familiare hook useConversation viene mantenuto ed è disponibile una skill per coding agent che automatizza l'aggiornamento.

Perché una nuova versione principale

Questa release è stata guidata da tre problemi.

API diverse sul web e in React Native

React e React Native avevano API, set di funzionalità e opzioni di configurazione diversi. Il codice e le conoscenze non si trasferivano tra le piattaforme e gli strumenti di coding IA suggerivano spesso API disponibili su una sola piattaforma. React Native era inoltre completamente privo della modalità di connessione WebSocket.

Internamente, ciò accadeva perché l'SDK React Native incapsulava un SDK React Native di terze parti anziché basarsi su @elevenlabs/client. Funzionalità e correzioni dovevano essere rilasciate due volte e, a ogni release, le due piattaforme si allontanavano ulteriormente.

Prestazioni di rendering insufficienti

Ogni modifica dello stato (status, modalità, mute, volume) provocava il re-rendering di ogni componente che utilizzava lo stato della conversazione. Non c'era modo di iscriversi solo alla porzione necessaria. Se il tuo componente si interessava solo allo stato della connessione, veniva comunque renderizzato di nuovo quando cambiava lo stato di mute.

Questo accadeva perché l'SDK usava un unico context provider che comprendeva tutto lo stato della conversazione, con hook poco granulari e callback passati tramite oggetti di opzioni.

Aggiornamenti fragili

L'aggiornamento dell'SDK rischiava di compromettere il tuo codice. Classi interne come Input, Output, e Connection facevano parte dell'API pubblica e gli sviluppatori si affidavano a primitive del browser non elaborate come conversation.output.gain.gain.value per il volume e conversation.input.analyser per la visualizzazione audio. Qualsiasi modifica interna poteva interrompere questi schemi di accesso.

Dal nostro lato, una gerarchia di classi basata sull'ereditarietà rendeva difficile risolvere il problema in modo incrementale, quindi era necessaria una separazione netta.

Novità

Un'unica API per tutte le piattaforme

@elevenlabs/react-native ora riesporta @elevenlabs/react con un sottile livello di strategia della piattaforma: circa 40 righe di codice, rispetto alle oltre mille precedenti. Lo stesso ConversationProvider, gli stessi hook, gli stessi metodi. Il codice scritto per il web funziona in React Native cambiando solo l'import path, le conoscenze si trasferiscono direttamente tra le piattaforme e gli strumenti di coding IA non allucinano più API specifiche della 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 le prestazioni di rendering

Sei nuovi hook si iscrivono ciascuno a una singola porzione dello stato della conversazione. I componenti vengono renderizzati di nuovo solo quando cambiano i dati che utilizzano.

Un indicatore di stato che prima veniva renderizzato di nuovo a ogni modifica dello stato ora viene renderizzato di nuovo solo quando cambia lo stato della connessione:

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

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

useConversation è ancora disponibile

Il familiare hook useConversation esiste ancora e restituisce la stessa struttura di dati: status, modalità, stato di mute e tutti i metodi di controllo. È un wrapper pratico sugli hook granulari descritti sopra. Gli utenti esistenti possono passare a ConversationProvider + useConversation come primo passo, quindi adottare gradualmente gli hook granulari dove le prestazioni di rendering sono importanti.

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 consente ai componenti React di registrare strumenti che l'agente può invocare. Gli strumenti sono legati al ciclo di vita del componente: vengono registrati al mount, annullano la registrazione all'unmount e usano sempre il valore di closure più recente.

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

È utile quando l'handler di uno strumento deve accedere allo stato del componente o a props non disponibili a livello di provider.

Superficie API stabile

Le classi interne (Input, Output, wake lock) sono ora private. L'API pubblica espone metodi documentati anziché primitive del browser non elaborate:

• 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 i livelli di trasporto, senza compromettere il codice degli utenti.

Stato controllato

ConversationProvider accetta le props isMuted e onMutedChange per la gestione esterna dello stato. È utile per mantenere lo stato di mute tra le sessioni o sincronizzarlo con lo stato a livello di 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>
  );
}

Quando queste props vengono omesse, lo stato di mute viene gestito internamente come prima.

Inferenza intelligente del tipo di connessione

Le conversazioni vocali ora usano WebRTC per impostazione predefinita, mentre quelle di solo testo usano WebSocket. Nella maggior parte dei casi non è necessario impostare connectionType manualmente. Se ti serve un tipo di connessione specifico, puoi comunque passarlo esplicitamente.

Aggiornamento

Si tratta di una breaking change che richiede aggiornamenti alle integrazioni esistenti. Ecco le modifiche principali:

• Conversation ora è un oggetto namespace e un type alias, non una classe. Le verifiche instanceof e il subclassing non funzionano più.
• useConversation richiede un ConversationProvider antenato.
• Input e Output vengono sostituite da metodi documentati sull'istanza della conversazione.
• In React Native, ElevenLabsProvider viene sostituito da ConversationProvider di @elevenlabs/react-native.

Per l'elenco completo delle breaking change, consulta il changelog.

Migrazione automatizzata con il tuo coding agent

È disponibile una skill dedicata per automatizzare l'aggiornamento. La skill legge la tua integrazione esistente, applica le modifiche API necessarie e aggiorna gli import. Si occupa del lavoro meccanico necessario per la migrazione a ConversationProvider, la sostituzione dei riferimenti alle classi rimosse e l'aggiornamento delle chiamate dei metodi.

La skill è particolarmente utile per codebase più grandi, in cui la migrazione riguarda più file.

npx skills add elevenlabs/packages

Documentazione aggiornata

La documentazione dell'SDK è stata aggiornata per riflettere la nuova API:

• SDK JavaScript
• SDK React
• SDK React Native

Per iniziare

Installa il pacchetto per la tua piattaforma:

# 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 riesporta tutto da @elevenlabs/client, quindi non devi installarli entrambi.

Racchiudi la tua app in un ConversationProvider, usa gli hook per avviare una sessione e consulta la documentazione dell'SDK per il riferimento API completo.

Come accennato nell'introduzione, è disponibile una skill per coding agent che automatizza l'aggiornamento:

npx skills add elevenlabs/packages

Feedback

Se riscontri problemi o hai suggerimenti, apri una issue su GitHub. L'SDK viene gestito attivamente ed esaminiamo ogni segnalazione.