SDK React ElevenAgents v1.0

La version 1.0.0 du SDK JavaScript et React d’Eleven Agents est désormais disponible. Cette version repense entièrement les packages @elevenlabs/client, @elevenlabs/react et @elevenlabs/react-native, en privilégiant les performances de rendu, une API unifiée pour le web et React Native, et une API publique stable. Ce changement majeur n’est pas rétrocompatible, mais le hook familier useConversation est conservé, et une skill pour agent de code permet d’automatiser l’upgrade.

Pourquoi une nouvelle version majeure

Trois problèmes ont motivé cette version.

Des API différentes sur le web et React Native

React et React Native disposaient d’API, de fonctionnalités et d’options de configuration différentes. Le code et les connaissances ne se transféraient pas d’une plateforme à l’autre, et les outils de code IA suggéraient souvent des API qui n’existaient que sur une seule plateforme. React Native ne disposait pas non plus du mode de connexion WebSocket.

En interne, cela s’expliquait par le fait que le SDK React Native encapsulait un SDK React Native tiers au lieu de s’appuyer sur @elevenlabs/client. Les fonctionnalités et correctifs devaient être publiés deux fois, et les deux plateformes divergeaient davantage à chaque version.

Performances de rendu insuffisantes

Chaque changement d’état (statut, mode, sourdine, volume) entraînait un nouveau rendu de chaque composant qui utilisait l’état de la conversation. Il était impossible de s’abonner uniquement à la portion nécessaire. Si votre composant ne s’intéressait qu’au statut de connexion, il était tout de même restitué lorsque l’état de sourdine changeait.

Cela venait du fait que le SDK utilisait un unique fournisseur de contexte couvrant tout l’état de la conversation, avec seulement des hooks généraux et des callbacks transmis via des objets d’options.

Upgrades fragiles

L’upgrade du SDK risquait de casser votre code. Des classes internes comme Input, Output et Connection faisaient partie de l’API publique, et les développeurs s’appuyaient sur des primitives brutes du navigateur telles que conversation.output.gain.gain.value pour le volume et conversation.input.analyser pour la visualisation audio. Toute modification interne pouvait casser ces modes d’accès.

De notre côté, une hiérarchie de classes fondée sur l’héritage compliquait les corrections progressives ; une rupture nette était donc nécessaire.

Nouveautés

Une API pour toutes les plateformes

@elevenlabs/react-native réexporte désormais @elevenlabs/react avec une fine couche de stratégie de plateforme : environ 40 lignes de code, contre plus d’un millier auparavant. Le même ConversationProvider, les mêmes hooks, les mêmes méthodes. Le code écrit pour le web fonctionne sur React Native avec un simple changement de chemin d’importation, les connaissances se transfèrent directement entre les plateformes et les outils de code IA n’inventent plus d’API propres à chaque plateforme.

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

Des hooks granulaires pour optimiser le rendu

Les six nouveaux hooks s’abonnent chacun à une portion précise de l’état de la conversation. Les composants ne sont restitués que lorsque les données qu’ils utilisent changent.

Un indicateur de statut auparavant restitué à chaque changement d’état ne l’est désormais que lorsque le statut de connexion change :

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

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

useConversation est toujours disponible

Le hook familier useConversation existe toujours et renvoie la même structure de données : statut, mode, état de sourdine et toutes les méthodes de contrôle. Il sert de wrapper pratique aux hooks granulaires décrits plus haut. Les utilisateurs existants peuvent d’abord migrer vers ConversationProvider + useConversation, puis adopter progressivement les hooks granulaires là où les performances de rendu sont importantes.

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

Outils client dynamiques

useConversationClientTool permet aux composants React d’enregistrer des outils que l’agent peut invoquer. Les outils sont liés au cycle de vie du composant : ils s’enregistrent au montage, se désenregistrent au démontage et utilisent toujours la dernière valeur de fermeture.

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

Cela est utile lorsqu’un gestionnaire d’outil doit accéder à l’état ou aux props d’un composant qui ne sont pas disponibles au niveau du fournisseur.

Surface d’API stable

Les classes internes (Input, Output, verrouillage de réveil) sont désormais privées. L’API publique expose des méthodes documentées au lieu de primitives brutes du navigateur :

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

L’implémentation audio sous-jacente peut ainsi être remplacée, par exemple en changeant les couches de transport, sans casser le code utilisateur.

État contrôlé

ConversationProvider accepte les props isMuted et onMutedChange pour la gestion externe de l’état. Cela permet de conserver l’état de sourdine entre les sessions ou de le synchroniser avec l’état de l’application.

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

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

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

Lorsque ces props sont omises, l’état de sourdine est géré en interne comme auparavant.

Inférence intelligente du type de connexion

Les conversations vocales utilisent désormais WebRTC par défaut, tandis que les conversations uniquement textuelles utilisent WebSocket. Dans la plupart des cas, il n’est pas nécessaire de définir connectionType manuellement. Si vous avez besoin d’un type de connexion précis, vous pouvez toujours le transmettre explicitement.

Upgrade

Ce changement non rétrocompatible nécessite de mettre à jour les intégrations existantes. Voici les principaux changements :

• Conversation est désormais un objet d’espace de noms et un alias de type, et non une classe. Les vérifications instanceof et le sous-classement ne fonctionnent plus.
• useConversation requiert un ConversationProvider ancêtre.
• Input et Output sont remplacées par des méthodes documentées sur l’instance de conversation.
• Sur React Native, ElevenLabsProvider est remplacé par ConversationProvider de @elevenlabs/react-native.

Pour consulter la liste complète des changements non rétrocompatibles, consultez le journal des modifications.

Migration automatisée avec votre agent de code

Une skill dédiée permet d’automatiser l’upgrade. Elle lit votre intégration existante, applique les modifications nécessaires à l’API et met à jour les importations. Elle prend en charge le travail mécanique de migration vers ConversationProvider, du remplacement des références aux classes supprimées et de la mise à jour des appels de méthode.

Cette skill est particulièrement utile pour les grandes bases de code, lorsque la migration concerne plusieurs fichiers.

npx skills add elevenlabs/packages

Documentation mise à jour

La documentation du SDK a été mise à jour pour refléter la nouvelle API :

• SDK JavaScript
• SDK React
• SDK React Native

Premiers pas

Installez le package adapté à votre plateforme :

# 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 réexporte tous les éléments de @elevenlabs/client, vous n’avez donc pas besoin d’installer les deux.

Encapsulez votre application dans un ConversationProvider, utilisez les hooks pour démarrer une session et consultez la documentation du SDK pour accéder à la référence complète de l’API.

Comme indiqué en introduction, une skill pour agent de code permet d’automatiser l’upgrade :

npx skills add elevenlabs/packages

Commentaires

Si vous rencontrez des problèmes ou avez des suggestions, ouvrez un ticket sur GitHub. Le SDK est activement maintenu et nous examinons chaque signalement.