ElevenAgents React SDK v1.0

Ya está disponible la versión 1.0.0 del SDK de JavaScript y React de Eleven Agents. Esta versión reestructura por completo los paquetes @elevenlabs/client, @elevenlabs/react y @elevenlabs/react-native, y se centra en el rendimiento de renderizado, una API unificada para web y React Native, y una API pública estable. Es un cambio incompatible, pero se mantiene el conocido hook useConversation, y hay disponible una skill para agentes de programación que automatiza la actualización.

Por qué una nueva versión principal

Esta versión responde a tres problemas.

APIs distintas en web y React Native

React y React Native tenían APIs, funciones y opciones de configuración distintas. El código y los conocimientos no se transferían entre plataformas, y las herramientas de programación con IA sugerían a menudo APIs que solo existían en una de ellas. Además, React Native no incluía ningún modo de conexión WebSocket.

Internamente, esto ocurría porque el SDK de React Native envolvía un SDK de React Native de terceros, en lugar de basarse en @elevenlabs/client. Había que publicar las funciones y correcciones dos veces, y las dos plataformas se distanciaban más con cada versión.

Bajo rendimiento de renderizado

Cualquier cambio de estado (estado, modo, silencio, volumen) volvía a renderizar todos los componentes que consumían el estado de la conversación. No había forma de suscribirse solo a la parte que necesitabas. Si tu componente solo necesitaba el estado de la conexión, también se volvía a renderizar cuando cambiaba el estado de silencio.

Esto se debía a que el SDK usaba un único proveedor de contexto para todo el estado de la conversación, con hooks poco específicos y callbacks transmitidos mediante objetos de opciones.

Actualizaciones frágiles

Actualizar el SDK podía romper tu código. Clases internas como Input, Output y Connection formaban parte de la API pública, y desarrolladores dependían de primitivas sin procesar 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 patrones de acceso.

Por nuestra parte, una jerarquía de clases basada en herencia dificultaba corregir esto de forma gradual, por lo que era necesaria una ruptura limpia.

Novedades

Una API para todas las plataformas

@elevenlabs/react-native ahora vuelve a exportar @elevenlabs/react con una fina capa de estrategia de plataforma: unas 40 líneas de código, frente a más de mil. El mismo ConversationProvider, los mismos hooks, los mismos métodos. El código escrito para web funciona en React Native cambiando solo la ruta de importación, los conocimientos se transfieren directamente entre plataformas y las herramientas de programación con IA dejan de inventar APIs específicas de cada plataforma.

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

Hooks granulares para mejorar el rendimiento de renderizado

Seis hooks nuevos se suscriben cada uno a una parte concreta del estado de la conversación. Los componentes solo se vuelven a renderizar cuando cambian los datos que consumen.

Un indicador de estado que antes se volvía a renderizar con cada cambio de estado ahora solo lo hace cuando cambia el propio estado de la conexión:

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

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

useConversation sigue disponible

El conocido hook useConversation sigue existiendo y devuelve la misma estructura de datos: estado, modo, estado de silencio y todos los métodos de control. Es un envoltorio práctico sobre los hooks granulares descritos anteriormente. Usuarios actuales pueden migrar a ConversationProvider + useConversation como primer paso y, después, adoptar hooks granulares de forma gradual donde el rendimiento de renderizado sea importante.

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

Herramientas dinámicas del cliente

useConversationClientTool permite a los componentes de React registrar herramientas que el agente puede invocar. Las herramientas están vinculadas al ciclo de vida del componente: se registran al montarse, se eliminan al desmontarse y siempre usan el valor de cierre más reciente.

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

Esto resulta útil cuando el controlador de una herramienta necesita acceder al estado o las props del componente que no están disponibles en el nivel del proveedor.

Una API estable

Las clases internas (Input, Output, bloqueo de activación) ahora son privadas. La API pública expone métodos documentados en lugar de primitivas sin procesar 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 permite sustituir la implementación de audio subyacente (por ejemplo, cambiando las capas de transporte) sin romper el código de usuarios.

Estado controlado

ConversationProvider acepta las props isMuted y onMutedChange para gestionar el estado externamente. Esto resulta útil para conservar el estado de silencio entre sesiones o sincronizarlo con el estado de la aplicación.

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

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

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

Cuando se omiten estas props, el estado de silencio se gestiona internamente como antes.

Inferencia inteligente del tipo de conexión

Las conversaciones de voz ahora usan WebRTC de forma predeterminada y las conversaciones de solo texto usan WebSocket. En la mayoría de los casos, no es necesario definir connectionType manualmente. Si necesitas un tipo de conexión específico, puedes seguir pasándolo de forma explícita.

Actualización

Este es un cambio incompatible que requiere actualizar las integraciones existentes. Estos son los cambios principales:

• Conversation ahora es un objeto de espacio de nombres y un alias de tipo, no una clase. Las comprobaciones con instanceof y la creación de subclases ya no funcionan.
• useConversation requiere un antecesor ConversationProvider.
• Input y Output 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 consultar la lista completa de cambios incompatibles, revisa el registro de cambios.

Migración automatizada con tu agente de programación

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

La skill resulta especialmente útil en bases de código grandes donde la migración afecta a varios archivos.

npx skills add elevenlabs/packages

Documentación actualizada

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

• SDK de JavaScript
• SDK de React
• SDK de React Native

Primeros pasos

Instala el paquete para tu plataforma:

# 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 vuelve a exportar todo desde @elevenlabs/client, así que no necesitas instalar ambos.

Envuelve tu aplicación 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 en la introducción, hay disponible una skill para agentes de programación que automatiza la actualización:

npx skills add elevenlabs/packages

Comentarios

Si encuentras problemas o tienes sugerencias, abre una incidencia en GitHub. Mantenemos el SDK de forma activa y revisamos todos los informes.