ElevenAgents React SDK v1.0

Dernière mise à jour 27 mars 2026 • 9 minutes de lecture

Photograph of Kræn Hansen facing the camera.

Kræn Hansen, Developer Experience Engineer

ElevenAgents React SDK v1.0.0 : une refonte du SDK JavaScript et React avec des hooks plus précis, une API unifiée sur le web et React Native, et une API publique stable.

Cover with ElevenAgents, React and SDK v1

Lire la documentation Voir sur GitHub

La version 1.0.0 du SDK JavaScript et React ElevenAgents est maintenant disponible. Cette version est une refonte complète des @elevenlabs/client, @elevenlabs/react, et @elevenlabs/react-native axée sur les performances de rendu, une API unifiée sur le web et React Native, et une API publique stable. C’est un changement majeur, mais le hook familier useConversation est conservé, et une compétence d’agent de codage est disponible pour automatiser la mise à jour.

Pourquoi une nouvelle version majeure

Trois problèmes ont motivé cette version.

Des APIs différentes sur le web et React Native

React et React Native avaient des APIs différentes, des fonctionnalités différentes et des options de configuration distinctes. Le code et les connaissances ne se transféraient pas entre les plateformes, et les outils d’IA suggéraient souvent des APIs qui n’existaient que sur une seule plateforme. React Native ne proposait pas non plus de mode connexion WebSocket.

En interne, cela venait du fait que le SDK React Native utilisait un SDK tiers React Native au lieu de se baser sur @elevenlabs/client. Les fonctionnalités et correctifs devaient être publiés deux fois, et les deux plateformes s’éloignaient à chaque version.

Mauvaises performances de rendu

Chaque changement d’état (statut, mode, sourdine, volume) relançait le rendu de tous les composants utilisant l’état de la conversation. Impossible de s’abonner uniquement à la partie nécessaire. Même si votre composant ne s’intéressait qu’au statut de connexion, il se relançait aussi quand l’état de sourdine changeait.

Cela venait du fait que le SDK utilisait un seul provider de contexte couvrant tout l’état de la conversation, avec seulement quelques hooks généraux et des callbacks passés dans les options.

Mises à jour fragiles

Mettre à jour le SDK risquait de casser votre code. Des classes internes comme Entrée, Sortie, et Connexion faisaient partie de l’API publique, et les développeurs utilisaient directement des primitives du navigateur comme conversation.output.gain.gain.value pour le volume et conversation.input.analyser pour la visualisation audio. Tout changement interne pouvait casser ces accès.

De notre côté, une hiérarchie de classes basée sur l’héritage rendait difficile une correction progressive, donc une rupture nette était nécessaire.

Quoi de neuf

Une API unique sur toutes les plateformes

@elevenlabs/react-native ré-exporte maintenant @elevenlabs/react avec une fine couche d’adaptation spécifique à la plateforme : environ 40 lignes de code au lieu de plus d’un millier. Même ConversationProvider, mêmes hooks, mêmes méthodes. Le code écrit pour le web fonctionne sur React Native en changeant simplement le chemin d’import, les connaissances se transfèrent directement, et les outils d’IA ne proposent plus d’APIs spécifiques à une plateforme.

1// On React Native, change this import to '@elevenlabs/react-native'.
2import {
3  ConversationProvider,
4  useConversationControls,
5  useConversationStatus,
6} from '@elevenlabs/react';
7
8function App() {
9  return (
10    <ConversationProvider>
11      <Agent />
12    </ConversationProvider>
13  );
14}
15
16function Agent() {
17  const { startSession, endSession } = useConversationControls();
18  const { status } = useConversationStatus();
19
20  if (status === 'connected') {
21    return <button onClick={endSession}>End</button>;
22  }
23
24  return (
25    <button onClick={() => startSession({ agentId: 'agent_7101k5zvyjhmfg983brhmhkd98n6' })}>
26      Start
27    </button>
28  );
29}

Hooks précis pour de meilleures performances de rendu

Six nouveaux hooks permettent de s’abonner à une partie précise de l’état de la conversation. Les composants ne se relancent que lorsque les données qu’ils utilisent changent.

Hook

Returns

Re-renders on

useConversationControls

Action methods (startSession, endSession, sendUserMessage, ...)

Never (stable references)

useConversationStatus

status, message

Connection status changes

useConversationInput

isMuted, setMuted

Mute state changes

useConversationMode

mode, isSpeaking, isListening

Mode changes

useConversationFeedback

canSendFeedback, sendFeedback

Feedback availability changes

useConversationClientTool

(registers a tool handler)

Never

Un indicateur de statut qui se relançait à chaque changement d’état ne se relance plus que lorsque le statut de connexion change :

1import { useConversationStatus } from '@elevenlabs/react';
2
3function StatusBadge() {
4  const { status } = useConversationStatus();
5  return <span>{status}</span>;
6}

`useConversation` est toujours là

Le hook familier useConversation existe toujours et retourne la même structure de données : statut, mode, état de sourdine et toutes les méthodes de contrôle. C’est un raccourci pratique basé sur les hooks précis décrits ci-dessus. Les utilisateurs actuels peuvent migrer vers ConversationProvider + useConversation comme première étape, puis adopter progressivement les hooks précis là où les performances de rendu sont importantes.

1import { useConversation } from '@elevenlabs/react';
2
3function Agent() {
4  const { status, isSpeaking, isMuted, setMuted, startSession, endSession } = useConversation();
5  // Same API shape as before, just requires a ConversationProvider ancestor.
6}

Outils client dynamiques

useConversationClientTool permet aux composants React d’enregistrer des outils que l’agent peut utiliser. 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 la closure.

1import { useConversationClientTool } from '@elevenlabs/react';
2import { useState } from 'react';
3
4function MapComponent() {
5  const [location, setLocation] = useState({ lat: 0, lng: 0 });
6
7  useConversationClientTool('getLocation', () => {
8    return `${location.lat},${location.lng}`;
9  });
10
11  useConversationClientTool('setLocation', (params: { lat: number; lng: number }) => {
12    setLocation(params);
13    return 'Location updated';
14  });
15
16  return <Map center={location} />;
17}

C’est utile quand le gestionnaire d’un outil a besoin d’accéder à l’état ou aux props du composant qui ne sont pas disponibles au niveau du provider.

API publique stable

Les classes internes (Entrée, Sortie, wake lock) sont maintenant privées. L’API publique expose des méthodes documentées au lieu de primitives du navigateur :

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

Cela signifie que l’implémentation audio sous-jacente peut être remplacée (par exemple, changer de couche de transport) sans casser le code utilisateur.

État contrôlé

ConversationProvider accepte les props isMuted et onMutedChange pour une gestion externe de l’état. Pratique pour garder l’état de sourdine entre les sessions ou le synchroniser avec l’état global de l’application.

1import { ConversationProvider } from '@elevenlabs/react';
2import { useState } from 'react';
3
4function App() {
5  const [muted, setMuted] = useState(false);
6
7  return (
8    <ConversationProvider isMuted={muted} onMutedChange={setMuted}>
9      <YourComponents />
10    </ConversationProvider>
11  );
12}

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

Détection intelligente du type de connexion

Les conversations vocales utilisent désormais WebRTC par défaut et les conversations texte uniquement utilisent WebSocket. Plus besoin de définir connectionType manuellement dans la plupart des cas. Si vous avez besoin d’un type de connexion spécifique, vous pouvez toujours le préciser.

Mise à jour

C’est un changement majeur qui nécessite de mettre à jour vos intégrations existantes. Les principaux changements en résumé :

Conversation est maintenant un objet namespace et un alias de type, plus une classe. instanceof et l’héritage ne fonctionnent plus.
useConversation nécessite un ConversationProvider parent.
Entrée et Sortie sont remplacés par des méthodes documentées sur l’instance de conversation.
Sur React Native, ElevenLabsProvider est remplacé par ConversationProvider de @elevenlabs/react-native.

Pour la liste complète des changements majeurs, consultez le journal des modifications.

Migration automatisée avec votre agent de codage

Une compétence dédiée est disponible pour automatiser la mise à jour. Elle lit votre intégration actuelle, applique les changements nécessaires à l’API et met à jour les imports. Elle s’occupe de la migration technique vers ConversationProvider, remplace les références de classes supprimées et met à jour les appels de méthodes.

Cette compétence est particulièrement utile pour les grands projets où la migration concerne plusieurs fichiers.

1npx skills add elevenlabs/packages

Documentation mise à jour

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

Premiers pas

Installez le package adapté à votre plateforme :

1# React (web)
2npm install @elevenlabs/react
3
4# React Native (Expo)
5npx expo install @elevenlabs/react-native @livekit/react-native @livekit/react-native-webrtc
6
7# Vanilla JavaScript
8npm install @elevenlabs/client

@elevenlabs/react ré-exporte tout depuis @elevenlabs/client, donc inutile 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 l’ensemble de l’API.

Et comme mentionné plus haut, une compétence d’agent de codage est disponible pour automatiser la mise à jour :

1npx skills add elevenlabs/packages

Retour

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

Découvrez les articles de l'équipe ElevenLabs

ElevenAgents Stories