ElevenAgents React SDK v1.0

A versão 1.0.0 do SDK JavaScript e React do Eleven Agents já está disponível. Esta versão traz uma nova arquitetura, criada do zero, dos pacotes @elevenlabs/client, @elevenlabs/react e @elevenlabs/react-native, com foco no desempenho de renderização, em uma API unificada para web e React Native e em uma API pública estável. Esta é uma mudança incompatível, mas o conhecido hook useConversation foi mantido, e uma skill para agentes de programação está disponível para automatizar a atualização.

Por que uma nova versão principal

Três problemas motivaram esta versão.

APIs diferentes na web e no React Native

React e React Native tinham APIs, conjuntos de recursos e opções de configuração diferentes. O código e o conhecimento não eram transferidos entre as plataformas, e ferramentas de programação com IA sugeriam com frequência APIs que existiam em apenas uma delas. O React Native também não tinha suporte algum ao modo de conexão WebSocket.

Internamente, isso acontecia porque o SDK do React Native encapsulava um SDK de React Native de terceiros, em vez de se basear em @elevenlabs/client. Recursos e correções precisavam ser lançados duas vezes, e as duas plataformas se afastavam cada vez mais a cada versão.

Baixo desempenho de renderização

Qualquer alteração de estado (status, modo, mudo, volume) renderizava novamente todos os componentes que consumiam o estado da conversa. Não havia como assinar apenas a parte de que você precisava. Se o componente só precisava do status da conexão, ele ainda era renderizado novamente quando o estado de mudo mudava.

Isso acontecia porque o SDK usava um único provedor de contexto que abrangia todo o estado da conversa, com apenas hooks pouco específicos e callbacks transmitidos por objetos de opções.

Atualizações frágeis

Atualizar o SDK poderia quebrar seu código. Classes internas como Input, Output e Connection faziam parte da API pública, e os desenvolvedores dependiam de primitivas brutas do navegador, como conversation.output.gain.gain.value para volume e conversation.input.analyser para visualização de áudio. Qualquer mudança interna poderia quebrar esses padrões de acesso.

Do nosso lado, uma hierarquia de classes baseada em herança dificultava corrigir isso de forma incremental, então foi necessária uma ruptura clara.

Novidades

Uma API para todas as plataformas

@elevenlabs/react-native agora reexporta @elevenlabs/react com uma camada simples de estratégia de 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 escrito para a web funciona no React Native com apenas uma mudança no caminho de importação, o conhecimento é transferido diretamente entre as plataformas, e as ferramentas de programação com IA não inventam mais APIs específicas de 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 melhor desempenho de renderização

Cada um dos seis novos hooks assina uma parte específica do estado da conversa. Os componentes só são renderizados novamente quando os dados que consomem mudam.

Um indicador de status que antes era renderizado novamente a cada mudança de estado agora só é renderizado novamente quando o próprio 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 continua existindo e retorna a mesma estrutura de dados: status, modo, estado de mudo e todos os métodos de controle. Ele é um wrapper de conveniência sobre os hooks granulares descritos acima. Usuários atuais podem migrar para ConversationProvider + useConversation como primeiro passo e, depois, adotar hooks granulares gradualmente onde o desempenho 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 do cliente

useConversationClientTool permite que componentes React registrem ferramentas que o agente pode invocar. As ferramentas estão vinculadas ao ciclo de vida do componente: são registradas na montagem, removidas na desmontagem 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 manipulador de uma ferramenta precisa acessar o estado ou as props do componente que não estão disponíveis no nível do provedor.

Superfície estável da API

As classes internas (Input, Output, wake lock) agora são privadas. A API pública expõe métodos documentados em vez de primitivas brutas 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 permite substituir a implementação de áudio subjacente — por exemplo, trocando as camadas 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 no nível 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 são omitidas, o estado de mudo é gerenciado internamente como antes.

Inferência inteligente do tipo de conexão

Conversas por voz agora usam WebRTC por padrão, e conversas apenas por texto usam WebSocket. Na maioria dos casos, não é necessário definir connectionType manualmente. Se precisar de um tipo de conexão específico, você ainda pode passá-lo explicitamente.

Atualização

Esta é uma mudança incompatível que exige atualizações nas integrações existentes. Veja as principais mudanças:

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

Para a lista completa de mudanças incompatíveis, consulte o changelog.

Migração automatizada com seu agente de programação

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 as importações. Ela cuida do trabalho mecânico de migrar para ConversationProvider, substituir referências a classes removidas e atualizar chamadas de métodos.

Essa skill é especialmente útil para bases de código maiores, em que a migração afeta 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 de @elevenlabs/client, então você não precisa instalar ambos.

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

E, como mencionamos na introdução, há uma skill para agentes de programação disponível para automatizar a atualização:

npx skills add elevenlabs/packages

Feedback

Se você encontrar problemas ou tiver sugestões, abra uma issue no GitHub. O SDK recebe manutenção ativa, e analisamos cada relato.