ElevenAgents React SDK v1.0

ElevenAgents JavaScript 및 React SDK 1.0.0 버전이 출시되었습니다. 이번 릴리스는 @elevenlabs/client, @elevenlabs/react, 그리고 @elevenlabs/react-native 패키지를 완전히 새롭게 설계한 것으로, 렌더링 성능, 웹과 React Native에서의 통합 API, 안정적인 공개 API에 중점을 두었습니다. 호환성에 영향을 주는 변경이지만, 익숙한 useConversation 훅은 그대로 유지되며, 업그레이드를 자동화할 수 있는 코딩 에이전트 스킬도 제공됩니다.

새로운 주요 버전이 필요한 이유

이번 릴리스를 이끈 세 가지 문제가 있었습니다.

웹과 React Native의 서로 다른 API

React와 React Native는 서로 다른 API, 기능, 설정 옵션을 가지고 있었습니다. 코드와 지식이 플랫폼 간에 공유되지 않았고, AI 코딩 도구는 한 플랫폼에만 존재하는 API를 자주 추천했습니다. React Native는 WebSocket 연결 모드도 아예 없었습니다.

내부적으로는, React Native SDK가 자체적으로 구축된 것이 아니라 타사 React Native SDK를 감쌌기 때문에 이런 문제가 발생했습니다. (@elevenlabs/client 기반이 아니었습니다.) 기능 추가나 버그 수정이 두 번씩 필요했고, 릴리스가 거듭될수록 두 플랫폼은 점점 더 달라졌습니다.

낮은 렌더링 성능

상태가 조금만 바뀌어도(상태, 모드, 음소거, 볼륨 등) 대화 상태를 사용하는 모든 컴포넌트가 다시 렌더링되었습니다. 필요한 부분만 구독할 방법이 없었고, 연결 상태만 신경 쓰는 컴포넌트도 음소거 상태가 바뀌면 함께 렌더링됐습니다.

이는 SDK가 모든 대화 상태를 하나의 컨텍스트 프로바이더로 관리하고, 옵션 객체를 통해서만 대략적인 훅과 콜백을 전달했기 때문입니다.

불안정한 업그레이드

SDK를 업그레이드하면 코드가 깨질 위험이 있었습니다. 입력, 출력, 연결 같은 내부 클래스가 공개 API에 포함되어 있었고, 개발자들은 브라우저의 원시 객체(예: conversation.output.gain.gain.value로 볼륨 조절, conversation.input.analyser로 오디오 시각화 등)에 직접 의존했습니다. 내부 구조가 조금만 바뀌어도 이런 접근 방식이 깨질 수 있었습니다.

저희 쪽에서도 상속 기반 클래스 구조 때문에 점진적으로 고치기 어려워, 완전히 새롭게 설계할 필요가 있었습니다.

새로워진 점

플랫폼 통합 API

@elevenlabs/react-native는 이제 @elevenlabs/react를 얇은 플랫폼 전략 레이어(약 40줄 코드, 기존 1,000줄 이상에서 대폭 감소)로 재내보냅니다. 동일한 ConversationProvider, 동일한 훅, 동일한 메서드를 제공합니다. 웹용으로 작성한 코드는 import 경로만 바꾸면 React Native에서도 동작하고, 지식도 바로 공유됩니다. AI 코딩 도구도 더 이상 플랫폼별 API를 잘못 추천하지 않습니다.

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

렌더링 성능을 위한 세분화된 훅

6개의 새로운 훅이 각각 대화 상태의 한 부분만 구독합니다. 컴포넌트는 자신이 사용하는 데이터가 바뀔 때만 다시 렌더링됩니다.

이전에는 상태가 바뀔 때마다 다시 렌더링되던 상태 표시기가, 이제는 연결 상태가 바뀔 때만 렌더링됩니다:

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

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

useConversation도 그대로

익숙한 useConversation 훅도 여전히 존재하며, status, mode, 음소거 상태, 모든 제어 메서드 등 동일한 형태의 데이터를 반환합니다. 위에서 설명한 세분화된 훅을 감싸는 편의용 래퍼입니다. 기존 사용자는 ConversationProvider + useConversation 조합으로 먼저 이전한 뒤, 렌더링 성능이 중요한 부분에만 세분화된 훅을 점진적으로 적용할 수 있습니다.

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

동적으로 등록하는 클라이언트 도구

useConversationClientTool을 사용하면 React 컴포넌트에서 에이전트가 호출할 수 있는 도구를 등록할 수 있습니다. 도구는 컴포넌트 생명주기에 따라 등록/해제되며, 항상 최신 클로저 값을 사용합니다.

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

도구의 핸들러가 프로바이더 레벨에서는 접근할 수 없는 컴포넌트 상태나 props에 접근해야 할 때 유용합니다.

안정적인 API 표면

내부 클래스(입력, 출력, wake lock)는 이제 비공개로 전환되었습니다. 공개 API는 브라우저의 원시 객체 대신 문서화된 메서드만 노출합니다:

• setVolume({ volume })는 conversation.output.gain.gain.value = v
• 를 대체하고,getInputByteFrequencyData()는
• conversation.input.analyser.getByteFrequencyData()를 대체하며,conversation.input.setMuted(true)

를

setMicMuted(true)

로 대체합니다. 즉, 내부 오디오 구현(예: 전송 계층 교체 등)이 바뀌어도 사용자 코드는 그대로 동작합니다.제어 가능한 상태ConversationProvider는 외부 상태 관리를 위해 isMuted와

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

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

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

onMutedChange

props를 지원합니다. 이를 통해 음소거 상태를 세션 간에 유지하거나 앱 전체 상태와 동기화할 수 있습니다.

이 props를 생략하면 기존처럼 내부적으로 음소거 상태가 관리됩니다.스마트한 연결 타입 자동 추론음성 대화는 기본적으로 WebRTC, 텍스트 전용 대화는 WebSocket이 기본값입니다. 대부분의 경우

connectionType

을 직접 지정할 필요가 없습니다. 특정 연결 타입이 필요하다면 명시적으로 전달할 수도 있습니다.

• 업그레이드 안내이번 릴리스는 기존 통합에 업데이트가 필요한 호환성 파괴 변경입니다. 주요 변경 사항은 다음과 같습니다:Conversation은 이제 클래스가 아니라 네임스페이스 객체 및 타입 별칭입니다.
• instanceof 검사나 서브클래싱이 더 이상 동작하지 않습니다.useConversation을 사용하려면
• ConversationProvider 상위 컴포넌트가 필요합니다.Input 및
• Output 클래스는 대화 인스턴스의 문서화된 메서드로 대체되었습니다.React Native에서는 ElevenLabsProvider가 ConversationProvider(으)로 대체되었습니다.

전체 호환성 파괴 변경 목록은 변경 내역에서 확인할 수 있습니다.

코딩 에이전트로 자동 마이그레이션

업그레이드를 자동화할 수 있는 전용 스킬이 제공됩니다. 이 스킬은 기존 통합 코드를 읽고, 필요한 API 변경을 적용하며, import 경로도 업데이트합니다. ConversationProvider로의 이전, 제거된 클래스 참조 대체, 메서드 호출 업데이트 등 마이그레이션 작업을 자동으로 처리합니다.

특히 여러 파일에 걸쳐 마이그레이션이 필요한 대규모 코드베이스에서 유용합니다.

npx skills add elevenlabs/packages

업데이트된 문서

SDK 문서도 새로운 API에 맞게 업데이트되었습니다:

• JavaScript SDK
• React SDK
• React Native SDK

시작하기

플랫폼에 맞는 패키지를 설치하세요:

# 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는 @elevenlabs/client의 모든 기능을 재내보내므로, 두 패키지를 모두 설치할 필요가 없습니다.

앱을 ConversationProvider로 감싸고, 훅을 사용해 세션을 시작한 뒤, 전체 API는 SDK 문서에서 확인하세요.

그리고 앞서 언급한 것처럼, 업그레이드를 자동화할 수 있는 코딩 에이전트 스킬도 제공됩니다:

npx skills add elevenlabs/packages

피드백

문제가 발생하거나 제안이 있다면 GitHub에 이슈를 남겨주세요. SDK는 활발히 관리되고 있으며, 모든 리포트를 꼼꼼히 검토합니다.