Salta al contenido
Inicia sesiónRegístrate
Contactar ventasIr a la app
BlogDesarrollador

ElevenAgents React SDK v1.0

Autores
Photograph of Kræn Hansen facing the camera.
Kræn Hansen, Developer Experience Engineer

ElevenAgents React SDK v1.0.0: una nueva arquitectura del SDK de JavaScript y React con hooks granulares, una API unificada para web y React Native, y una API pública estable.

Cover with ElevenAgents, React and SDK v1
Lee la documentaciónVer en GitHub

Ya está disponible la versión 1.0.0 del SDK de JavaScript y React de ElevenAgents. Esta versión es una reescritura completa de los paquetes @elevenlabs/client, @elevenlabs/react y @elevenlabs/react-native, centrada en el rendimiento de renderizado, una API unificada para web y React Native, y una API pública estable. Es un cambio importante, pero el conocido hook useConversation se mantiene, y hay una skill de agente de código disponible para automatizar la actualización.

Por qué una nueva versión principal

Tres problemas motivaron este lanzamiento.

APIs diferentes en web y React Native

React y React Native tenían APIs distintas, diferentes funciones y opciones de configuración. El código y el conocimiento no se podían reutilizar entre plataformas, y las herramientas de IA para programar sugerían APIs que solo existían en una de ellas. Además, React Native no tenía modo de conexión WebSocket.

Esto ocurría porque el SDK de React Native usaba un SDK de terceros en vez de construirse sobre @elevenlabs/client. Las funciones y correcciones había que implementarlas dos veces, y las dos plataformas se iban separando más con cada versión.

Rendimiento de renderizado mejorable

Cualquier cambio de estado (estado, modo, mute, volumen) hacía que se renderizasen de nuevo todos los componentes que usaban el estado de la conversación. No había forma de suscribirse solo a la parte que necesitabas. Incluso si tu componente solo necesitaba saber el estado de la conexión, se volvía a renderizar cuando cambiaba el mute.

Esto pasaba porque el SDK usaba un único context provider para todo el estado de la conversación, con hooks y callbacks poco específicos pasados por objetos de opciones.

Actualizaciones frágiles

Actualizar el SDK podía romper tu código. Clases internas como Entrada, Salida y Conexión formaban parte de la API pública, y desarrolladores dependían de primitivas del navegador como conversation.output.gain.gain.value para el volumen y conversation.input.analyser para la visualización de audio. Cualquier cambio interno podía romper estos accesos.

Por nuestra parte, una jerarquía de clases basada en herencia hacía difícil arreglar esto poco a poco, así que era necesario un cambio radical.

Novedades

Una sola API para todas las plataformas

@elevenlabs/react-native ahora reexporta @elevenlabs/react con una capa fina de adaptación para la plataforma: unas 40 líneas de código en vez de más de mil. El mismo ConversationProvider, los mismos hooks, los mismos métodos. El código escrito para web funciona en React Native solo cambiando la ruta de importación, el conocimiento se transfiere directamente entre plataformas y las herramientas de IA ya no inventan APIs específicas de una plataforma.

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 granulares para mejorar el renderizado

Seis nuevos hooks permiten suscribirse solo a una parte concreta del estado de la conversación. Los componentes solo se renderizan de nuevo cuando cambia la información que usan.

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 indicador de estado que antes se renderizaba con cada cambio de estado ahora solo lo hace cuando cambia el estado de la conexión:

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

useConversation sigue disponible

El conocido hook useConversation sigue existiendo y devuelve los mismos datos: estado, modo, mute y todos los métodos de control. Es un wrapper práctico sobre los hooks granulares mencionados antes. Si ya usas el SDK, puedes migrar a ConversationProvider + useConversation como primer paso, y luego ir usando los hooks granulares donde el rendimiento sea importante.

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}

Herramientas dinámicas para el cliente

useConversationClientTool permite que los componentes de React registren herramientas que el agente puede usar. Las herramientas se asocian al ciclo de vida del componente: se registran al montar, se eliminan al desmontar y siempre usan el valor más reciente del 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}

Esto es útil cuando el handler de una herramienta necesita acceder a estado o props del componente que no están disponibles a nivel del provider.

API pública estable

Las clases internas (Entrada, Salida, wake lock) ahora son privadas. La API pública expone métodos documentados en vez de primitivas del navegador:

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

Esto significa que se puede cambiar la implementación de audio interna (por ejemplo, cambiar la capa de transporte) sin romper el código del usuario.

Estado controlado

ConversationProvider acepta las props isMuted y onMutedChange para gestionar el estado desde fuera. Esto es útil para guardar el estado de mute entre sesiones o sincronizarlo con el estado global de la app.

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 no se pasan estas props, el estado de mute se gestiona internamente como antes.

Detección inteligente del tipo de conexión

Las conversaciones de voz ahora usan WebRTC por defecto y las de solo texto usan WebSocket. No hace falta establecer connectionType manualmente en la mayoría de los casos. Si necesitas un tipo de conexión concreto, puedes seguir pasándolo de forma explícita.

Actualización

Este es un cambio importante que requiere actualizar las integraciones existentes. Cambios clave de un vistazo:

  • Conversación ahora es un objeto namespace y un alias de tipo, no una clase. Las comprobaciones instanceof y la herencia ya no funcionan.
  • useConversation requiere un ConversationProvider como ancestro.
  • Entrada y Salida se sustituyen por métodos documentados en la instancia de conversación.
  • En React Native, ElevenLabsProvider se sustituye por ConversationProvider de @elevenlabs/react-native.

Para ver todos los cambios importantes, consulta el changelog.

Migración automática con tu agente de código

Hay una skill dedicada para automatizar la actualización. La skill lee tu integración actual, aplica los cambios necesarios en la API y actualiza los imports. Se encarga del trabajo mecánico de migrar a ConversationProvider, sustituir las referencias a clases eliminadas y actualizar las llamadas a métodos.

La skill es especialmente útil en proyectos grandes donde la migración afecta a varios archivos.

1npx skills add elevenlabs/packages

Documentación actualizada

La documentación del SDK se ha actualizado para reflejar la nueva API:

Primeros pasos

Instala el paquete para tu plataforma:

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 reexporta todo lo de @elevenlabs/client, así que no necesitas instalar ambos.

Envuelve tu app en un ConversationProvider, usa los hooks para iniciar una sesión y consulta la documentación del SDK para ver la referencia completa de la API.

Y como mencionamos al principio, hay una skill de agente de código disponible para automatizar la actualización:

1npx skills add elevenlabs/packages

Comentarios

Si tienes problemas o sugerencias, abre una incidencia en GitHub. El SDK se mantiene activamente y revisamos todos los reportes.

Descubre artículos del equipo de ElevenLabs

Crea con el audio IA de la más alta calidad

Contacta con VentasRegístrate