ElevenAgents React SDK v1.0

Eleven Agents 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가 @elevenlabs/client를 기반으로 구축되지 않고 타사 React Native SDK를 래핑했기 때문에 이런 문제가 발생했습니다. 기능과 수정 사항을 두 번 배포해야 했고, 릴리스할 때마다 두 플랫폼의 차이는 더 커졌습니다.

낮은 렌더링 성능

상태(상태, 모드, 음소거, 볼륨)가 변경될 때마다 대화 상태를 사용하는 모든 컴포넌트가 다시 렌더링되었습니다. 필요한 상태 조각만 구독할 방법이 없었습니다. 컴포넌트가 연결 상태에만 관심이 있더라도 음소거 상태가 바뀌면 다시 렌더링되었습니다.

이는 SDK가 모든 대화 상태를 아우르는 단일 컨텍스트 프로바이더를 사용하고, 옵션 객체를 통해 대략적인 훅과 콜백만 전달했기 때문입니다.

불안정한 업그레이드

SDK를 업그레이드하면 코드가 깨질 위험이 있었습니다. Input, Output, Connection 같은 내부 클래스가 공개 API의 일부였고, 개발자는 볼륨을 위해 conversation.output.gain.gain.value 같은 원시 브라우저 프리미티브와 오디오 시각화를 위해 conversation.input.analyser를 사용했습니다. 내부 변경으로 이러한 접근 방식이 깨질 수 있었습니다.

내부적으로는 상속 기반 클래스 계층 구조 때문에 이를 점진적으로 수정하기 어려웠으므로, 명확한 단절이 필요했습니다.

새로운 기능

플랫폼 전반의 단일 API

@elevenlabs/react-native가 이제 @elevenlabs/react를 다시 내보냅니다. 얇은 플랫폼 전략 레이어를 적용해 코드가 1,000줄 이상에서 약 40줄로 줄었습니다. 동일한 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 훅은 여전히 제공되며 상태, 모드, 음소거 상태, 모든 제어 메서드 등 동일한 형태의 데이터를 반환합니다. 위에서 설명한 세분화된 훅을 편리하게 감싼 래퍼입니다. 기존 사용자는 먼저 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 표면

내부 클래스(Input, Output, wake lock)는 이제 비공개입니다. 공개 API는 원시 브라우저 프리미티브 대신 문서화된 메서드를 제공합니다:

• setVolume({ volume })가 conversation.output.gain.gain.value = v
• getInputByteFrequencyData()를 대체합니다: conversation.input.analyser.getByteFrequencyData()
• setMicMuted(true)가 conversation.input.setMuted(true)

즉, 사용자 코드를 깨지 않고도 기본 오디오 구현을 교체할 수 있습니다(예: 전송 레이어 교체).

제어되는 상태

ConversationProvider는 외부 상태 관리를 위해 isMuted 및 onMutedChange props를 받습니다. 세션 간 음소거 상태를 유지하거나 애플리케이션 수준 상태와 동기화할 때 유용합니다.

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

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

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

이 props를 생략하면 이전과 같이 음소거 상태가 내부적으로 관리됩니다.

스마트 연결 유형 추론

음성 대화는 이제 기본적으로 WebRTC를 사용하고, 텍스트 전용 대화는 기본적으로 WebSocket을 사용합니다. 대부분의 경우 connectionType을 수동으로 설정할 필요가 없습니다. 특정 연결 유형이 필요하다면 여전히 명시적으로 전달할 수 있습니다.

업그레이드

이번 호환성이 깨지는 변경에는 기존 통합 업데이트가 필요합니다. 주요 변경 사항은 다음과 같습니다:

• Conversation은 이제 클래스가 아니라 네임스페이스 객체 및 타입 별칭입니다. instanceof 검사와 서브클래싱은 더 이상 작동하지 않습니다.
• useConversation에는 상위 ConversationProvider가 필요합니다.
• Input 및 Output 클래스는 대화 인스턴스의 문서화된 메서드로 대체됩니다.
• React Native에서는 ElevenLabsProvider가 ConversationProvider로 대체됩니다. 출처: @elevenlabs/react-native.

호환성이 깨지는 변경 사항 전체 목록은 변경 로그에서 확인하세요.

코딩 에이전트를 활용한 자동 마이그레이션

업그레이드를 자동화하는 전용 스킬을 사용할 수 있습니다. 이 스킬은 기존 통합을 읽고 필요한 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는 활발히 유지 관리되고 있으며 모든 보고서를 검토합니다.