ElevenAgents React SDK v1.0

Eleven Agents JavaScript・React SDKのバージョン1.0.0が利用可能になりました。このリリースでは、@elevenlabs/client、@elevenlabs/react、@elevenlabs/react-nativeパッケージをゼロから再設計しました。レンダリングパフォーマンス、WebとReact Nativeで統一されたAPI、安定した公開APIに注力しています。破壊的変更を含みますが、おなじみのuseConversationフックは維持され、アップグレードを自動化するコーディングエージェント用スキルも利用できます。

新しいメジャーバージョンの理由

このリリースは、3つの課題を解決するために行いました。

Webと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も、フックも、メソッドも同じです。Web向けに書いたコードはインポートパスを変えるだけで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、ウェイクロック）は非公開になりました。公開APIでは、生のブラウザプリミティブではなく、ドキュメント化されたメソッドを提供します：

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

を置き換えます。これにより、ユーザーコードを壊さずに基盤となるオーディオ実装（たとえばトランスポートレイヤー）を置き換えられます。

制御された状態

ConversationProviderは、外部で状態を管理するためのisMutedとonMutedChangepropsを受け取ります。セッションをまたいでミュート状態を保持したり、アプリケーションレベルの状態と同期したりする場合に便利です。

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変更を適用し、インポートを更新します。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でissueを作成してください。SDKは積極的にメンテナンスしており、すべての報告を確認しています。