ElevenAgents React SDK v1.0

ElevenAgents 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がサードパーティのReact Native SDKをラップしていたため、@elevenlabs/clientの上に構築されていませんでした。機能や修正を2回リリースする必要があり、リリースごとに2つのプラットフォームの差が広がっていました。

レンダリングパフォーマンスの低下

状態（ステータス、モード、ミュート、音量）が変わるたびに、会話状態を利用するすべてのコンポーネントが再レンダリングされていました。必要な部分だけ購読する方法がなく、接続ステータスだけ気にしているコンポーネントもミュート状態が変わると再レンダリングされていました。

これは、SDKが会話状態全体をカバーする単一のコンテキストプロバイダーを使い、粗いフックやコールバックのみをオプションオブジェクト経由で渡していたためです。

アップグレードの脆弱さ

SDKをアップグレードするとコードが壊れるリスクがありました。内部クラスである入力、出力、接続がパブリックAPIの一部で、デベロッパーは生のブラウザプリミティブ（例：conversation.output.gain.gain.valueで音量調整や、conversation.input.analyserでオーディオ可視化）に依存していました。内部の変更でこれらのアクセス方法が壊れる可能性がありました。

また、継承ベースのクラス構造のため、段階的な修正が難しく、クリーンな切り替えが必要でした。

新機能

プラットフォーム共通のAPI

@elevenlabs/react-nativeは現在、@elevenlabs/reactを薄いプラットフォーム戦略レイヤーで再エクスポートしています：コードは約40行に減り、以前は1000行以上ありました。同じ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サーフェス

内部クラス（入力、出力、ウェイクロック）は非公開になりました。パブリックAPIは生のブラウザプリミティブではなく、ドキュメント化されたメソッドを公開します：

• setVolume（{ volume }）はconversation.output.gain.gain.value = v
• の代わりですgetInputByteFrequencyData()は
• 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のラップが必要です。
• 入力と出力クラスは、会話インスタンス上のドキュメント化されたメソッドに置き換えられました。
• 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でラップし、フックを使ってセッションを開始し、SDKドキュメントでAPIリファレンスを確認してください。

また、冒頭で紹介した通り、アップグレードを自動化するコーディングエージェントスキルも利用できます：

npx skills add elevenlabs/packages

フィードバック

問題やご要望があれば、GitHubでIssueを作成してください。SDKは積極的にメンテナンスされており、すべての報告を確認しています。