ElevenAgents React SDK v1.0

A versão 1.0.0 do ElevenAgents JavaScript e React SDK já está disponível. Esta versão é uma reestruturação completa dos pacotes @elevenlabs/client, @elevenlabs/react e @elevenlabs/react-native, com foco em performance de renderização, API unificada para web e React Native, e uma API pública estável. É uma mudança incompatível com versões anteriores, mas o conhecido hook useConversation foi mantido, e uma skill de agente de código está disponível para automatizar a atualização.

Por que uma nova versão principal

Três problemas motivaram este lançamento.

APIs diferentes na web e no React Native

React e React Native tinham APIs diferentes, conjuntos de recursos distintos e opções de configuração variadas. O código e o conhecimento não eram reaproveitados entre as plataformas, e ferramentas de IA para programação frequentemente sugeriam APIs que só existiam em uma delas. O React Native também não tinha suporte ao modo de conexão WebSocket.

Isso acontecia porque o SDK do React Native usava um SDK de terceiros como base, em vez de construir sobre o @elevenlabs/client. Recursos e correções precisavam ser lançados duas vezes, e as plataformas ficavam cada vez mais diferentes a cada atualização.

Baixa performance de renderização

Qualquer alteração de estado (status, modo, mudo, volume) fazia todos os componentes que usavam o estado da conversa renderizarem novamente. Não havia como assinar apenas a parte do estado que você precisava. Mesmo que seu componente só se importasse com o status da conexão, ele ainda renderizava de novo quando o estado de mudo mudava.

Isso acontecia porque o SDK usava um único context provider para todo o estado da conversa, com hooks e callbacks pouco específicos passados por objetos de opções.

Atualizações frágeis

Atualizar o SDK podia quebrar seu código. Classes internas como Entrada, Saída e Conexão faziam parte da API pública, e desenvolvedores dependiam de recursos nativos do navegador como conversation.output.gain.gain.value para volume e conversation.input.analyser para visualização de áudio. Qualquer mudança interna podia quebrar esses acessos.

Do nosso lado, a hierarquia de classes baseada em herança dificultava corrigir isso aos poucos, então foi preciso uma mudança completa.

O que mudou

Uma API para todas as plataformas

@elevenlabs/react-native agora reexporta o @elevenlabs/react com uma camada fina de adaptação para a plataforma: cerca de 40 linhas de código, em vez de mais de mil. O mesmo ConversationProvider, os mesmos hooks, os mesmos métodos. O código feito para web funciona no React Native apenas mudando o caminho do import, o conhecimento é transferido diretamente entre plataformas e ferramentas de IA não sugerem mais APIs específicas de uma só 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 detalhados para melhor performance

Seis novos hooks permitem assinar partes específicas do estado da conversa. Os componentes só renderizam novamente quando os dados que usam mudam.

Um indicador de status que antes renderizava a cada mudança de estado agora só renderiza quando o status da conexão muda:

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

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

useConversation continua disponível

O conhecido hook useConversation ainda existe e retorna os mesmos dados: status, modo, estado de mudo e todos os métodos de controle. Ele é um atalho prático sobre os hooks detalhados citados acima. Usuários atuais podem migrar para ConversationProvider + useConversation como primeiro passo, e depois adotar os hooks detalhados onde a performance de renderização for 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.
}

Ferramentas dinâmicas para o cliente

useConversationClientTool permite que componentes React registrem ferramentas que o agente pode usar. As ferramentas acompanham o ciclo de vida do componente: registram ao montar, removem ao desmontar e sempre usam o valor mais recente do closure.

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

Isso é útil quando o handler da ferramenta precisa acessar estado ou props do componente que não estão disponíveis no nível do provider.

API pública estável

Classes internas (Entrada, Saída, wake lock) agora são privadas. A API pública expõe métodos documentados em vez de recursos nativos do navegador:

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

Isso significa que a implementação de áudio pode ser trocada (por exemplo, mudando a camada de transporte) sem quebrar o código do usuário.

Estado controlado

ConversationProvider aceita as props isMuted e onMutedChange para gerenciamento externo de estado. Isso é útil para manter o estado de mudo entre sessões ou sincronizá-lo com o estado da aplicação.

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 essas props não são usadas, o estado de mudo é gerenciado internamente como antes.

Detecção inteligente do tipo de conexão

Conversas por voz agora usam WebRTC por padrão e conversas só de texto usam WebSocket. Não é mais necessário definir connectionType manualmente na maioria dos casos. Se precisar de um tipo específico, ainda é possível passar explicitamente.

Como atualizar

Esta é uma mudança incompatível que exige atualização das integrações existentes. Principais mudanças:

• Conversation agora é um objeto namespace e um alias de tipo, não uma classe. instanceof e herança não funcionam mais.
• useConversation exige um ConversationProvider como ancestral.
• Entrada e Saída foram substituídas por métodos documentados na instância da conversa.
• No React Native, ElevenLabsProvider foi substituído por ConversationProvider do @elevenlabs/react-native.

Para ver todas as mudanças incompatíveis, consulte o changelog.

Migração automática com seu agente de código

Uma skill dedicada está disponível para automatizar a atualização. Ela lê sua integração atual, aplica as mudanças necessárias na API e atualiza os imports. Assim, cuida da parte mecânica da migração para o ConversationProvider, substituindo referências de classes removidas e atualizando chamadas de métodos.

Essa skill é especialmente útil para projetos grandes, onde a migração envolve vários arquivos.

npx skills add elevenlabs/packages

Documentação atualizada

A documentação do SDK foi atualizada para refletir a nova API:

• SDK JavaScript
• SDK React
• SDK React Native

Primeiros passos

Instale o pacote para sua 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 reexporta tudo do @elevenlabs/client, então não é necessário instalar ambos.

Envolva seu app com o ConversationProvider, use os hooks para iniciar uma sessão e consulte a documentação do SDK para ver a referência completa da API.

E como mencionamos na introdução, há uma skill de agente de código disponível para automatizar a atualização:

npx skills add elevenlabs/packages

Feedback

Se encontrar algum problema ou tiver sugestões, abra uma issue no GitHub. O SDK é mantido ativamente e analisamos todos os relatos.