elevenlabs-agents

ElevenLabs Agents Platform

概要

ElevenLabs Agents Platform は、本番環境ですぐに使える会話型音声エージェントを構築するための包括的なソリューションです。このプラットフォームは、次の 4 つの主要コンポーネントを連携させます。

1. ASR（自動音声認識） - 音声をテキストに変換します（32 以上の言語、1 秒未満の低遅延）
2. LLM（大規模言語モデル） - 推論と応答の生成を行います（GPT、Claude、Gemini、カスタムモデル）
3. TTS（テキスト読み上げ） - テキストを音声に変換します（5000 以上の音声、31 言語、低遅延）
4. ターンテイキングモデル - 会話のタイミングや割り込みを処理する独自モデル

🚨 パッケージの移行（2025 年 8 月）

非推奨（使用しないでください）： @11labs/react と @11labs/client

現行のパッケージ：

bun add @elevenlabs/[email protected]        # React SDK
bun add @elevenlabs/[email protected]       # JavaScript SDK
bun add @elevenlabs/[email protected]  # React Native SDK
bun add @elevenlabs/[email protected] # Base SDK
bun add -g @elevenlabs/[email protected]  # CLI

移行する場合は、最初に古いパッケージをアンインストールしてください：npm uninstall @11labs/react @11labs/client

---

クイックスタート

パス A：React SDK（埋め込み型音声チャット）

React アプリケーションで音声チャットインターフェースを構築する場合に使用します。

インストール：

bun add @elevenlabs/react zod

基本的な例：

import { useConversation } from '@elevenlabs/react';
import { z } from 'zod';

export default function VoiceChat() {
  const { startConversation, stopConversation, status } = useConversation({
    // Authentication (choose one)
    agentId: 'your-agent-id',  // Public agent (no key needed)
    // apiKey: process.env.NEXT_PUBLIC_ELEVENLABS_API_KEY,  // Private (dev only)
    // signedUrl: '/api/elevenlabs/auth',  // Signed URL (production)

    // Client-side tools
    clientTools: {
      updateCart: {
        description: "Update the shopping cart",
        parameters: z.object({
          item: z.string(),
          quantity: z.number()
        }),
        handler: async ({ item, quantity }) => {
          console.log('Updating cart:', item, quantity);
          return { success: true };
        }
      }
    },

    // Event handlers
    onEvent: (event) => {
      if (event.type === 'transcript') console.log('User:', event.data.text);
      if (event.type === 'agent_response') console.log('Agent:', event.data.text);
    },

    // Regional compliance
    serverLocation: 'us' // 'us' | 'global' | 'eu-residency' | 'in-residency'
  });

  return (
    <div>
      <button onClick={startConversation}>Start Conversation</button>
      <button onClick={stopConversation}>Stop</button>
      <p>Status: {status}</p>
    </div>
  );
}

完全なテンプレート： templates/basic-react-agent.tsx を参照してください。

パス B：CLI（「エージェントをコードで管理」）

バージョン管理や CI/CD を利用して、コード経由でエージェントを管理する場合に使用します。CLI のワークフローでは references/cli-commands.md を読み込んでください。

クイックワークフロー：

bun add -g @elevenlabs/agents-cli
elevenlabs auth login
elevenlabs agents init
elevenlabs agents add "Support Agent" --template customer-service
# Edit agent_configs/support-agent.json
elevenlabs agents push --env dev
elevenlabs agents test "Support Agent"

参照先： CLI の完全なリファレンスとワークフローについては、references/cli-commands.md を参照してください。

パス C：API（プログラムによるエージェント管理）

エージェントを動的に作成する場合（マルチテナント、SaaS プラットフォーム）に使用します。API を直接使用する場合は references/api-reference.md を読み込んでください。

簡単な例：

import { ElevenLabsClient } from 'elevenlabs';

const client = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY
});

const agent = await client.agents.create({
  name: 'Support Bot',
  conversation_config: {
    agent: {
      prompt: { prompt: "You are a helpful support agent.", llm: "gpt-4o" },
      first_message: "Hello! How can I help you today?"
    },
    tts: { model_id: "eleven_turbo_v2_5", voice_id: "your-voice-id" }
  }
});

参照先： API の完全なリファレンスについては、references/api-reference.md を参照してください。

---

エージェントの設定

システムプロンプトのフレームワーク

ElevenLabs では、人格（アイデンティティ／役割）、環境（コミュニケーションの文脈）、トーン（形式や話し方のパターン）、目標（目的／成功基準）、ガードレール（境界／倫理）、ツール（利用可能な関数）の 6 つの要素で構成されるプロンプト構造を推奨しています。

構成例：

Personality: You are Alex, a friendly customer support specialist at TechCorp.
Environment: Phone communication, voice-only, potential background noise.
Tone: Professional yet warm. Use contractions. Keep responses to 2-3 sentences.
Goal: Resolve issues on first call. Success = customer confirms resolution.
Guardrails: Never give medical/legal advice. Escalate if customer becomes abusive.
Tools: lookup_order(id), transfer_to_supervisor(), send_password_reset(email)

完全なガイド： エージェントのプロンプトを設定したり、会話の品質を高めたりする場合は、references/system-prompt-guide.md を読み込んでください。

ターンテイキングモード

モード	動作	最適な用途
積極的	素早く応答し、早めに話し始めます	迅速なサポート、手早い注文
標準	バランスよく、自然な切れ目を待ちます	一般的なカスタマーサービス（デフォルト）
慎重	詳細な応答を待ちます	情報収集、チュータリング

設定：conversation_config 内の "turn": { "mode": "patient" }

---

主な機能の概要

音声と言語

• マルチボイス： 音声を動的に切り替えます（切り替えごとに約 200 ms の遅延が追加されます）
• 発音辞書： カスタム発音には IPA、CMU、または単語の置換を使用します
• 速度制御： 0.7x～1.2x（1.0x＝標準）
• 言語： 32 以上の言語に対応し、自動検出と複数言語のプリセットを利用できます

ナレッジベース（RAG）

会話中のセマンティック検索に使用するドキュメント（PDF/TXT/DOCX）をアップロードできます。エージェントは関連するチャンクを自動的に取得します。クエリごとに約 500 ms の遅延が追加されます。ドキュメントは使用前にインデックス化する必要があります。

参照先： ナレッジベースの API と設定については、references/api-reference.md を参照してください。

ツール（4 種類）

1. クライアントツール - ブラウザー内で実行します（UI の更新、ナビゲーション、ローカルストレージ）
2. サーバーツール（Webhook） - バックエンドで実行します（データベース、決済、CRM）
3. MCP ツール - Model Context Protocol サーバーに接続します（エンタープライズ API）
4. システムツール - プラットフォームに組み込まれたツールです（end_conversation、transfer_call、mute_microphone、press_digit）

参照先： ツールを実装する場合は references/tool-examples.md を読み込んでください。Webhook ツールの作成 API については references/api-reference.md を読み込んでください。

---

特に重要なエラー 3 件

エラー 1：パッケージの非推奨（@11labs/*）

症状： インポートエラー、「module not found」

解決策：

npm uninstall @11labs/react @11labs/client
bun add @elevenlabs/[email protected] @elevenlabs/[email protected]

# Update imports:
import { useConversation } from '@elevenlabs/react';  // Not @11labs/react

エラー 2：Android で音声が途切れる（最初のメッセージ）

症状： Android でのみエージェントの最初のメッセージが途中で途切れます（iOS とウェブでは正常に動作します）

解決策：

const { startConversation } = useConversation({
  agentId: 'your-agent-id',
  connectionDelay: {
    android: 3_000,  // 3 seconds for Android audio mode switch
    ios: 0,
    default: 0
  }
});

エラー 3：CSP（コンテンツセキュリティポリシー）違反

症状：「Refused to load the script...」エラーが発生し、CSP により blob URL がブロックされます

解決策 - worklet ファイルをセルフホストします：

cp node_modules/@elevenlabs/client/dist/worklets/*.js public/elevenlabs/

const { startConversation } = useConversation({
  agentId: 'your-agent-id',
  workletPaths: {
    'rawAudioProcessor': '/elevenlabs/rawAudioProcessor.worklet.js',
    'audioConcatProcessor': '/elevenlabs/audioConcatProcessor.worklet.js',
  }
});

**17 件のエラーすべてを確認する：**エラーのトラブルシューティング、Webhook の失敗のデバッグ、RAG の問題、またはプラットフォーム固有の問題への対処時に、references/error-catalog.md を読み込みます。

---

参照ファイルを読み込むタイミング

現在のタスクに応じて、該当する参照ファイルを読み込みます。

references/api-reference.md

読み込むタイミング：API 経由でエージェントを作成するとき、プログラムからエージェントを管理するとき、マルチテナントシステムを構築するとき、ナレッジベースを実装するとき、Webhook ツールを作成するとき、API エラーに対処するとき、または API のレート制限を確認するとき。

references/cli-commands.md

読み込むタイミング：エージェント管理に CLI を使用するとき、CI/CD パイプラインを設定するとき、複数環境へのデプロイ（dev/staging/prod）を管理するとき、エージェント設定をバージョン管理するとき、または CLI の問題をトラブルシューティングするとき。

references/compliance-guide.md

読み込むタイミング：GDPR への準拠を実装するとき、HIPAA の要件（医療）に対処するとき、SOC 2 の統制を設定するとき、データ保持ポリシーを設定するとき、地域別のデータレジデンシー（EU/IN）を実装するとき、または PCI DSS（決済）に対処するとき。

references/cost-optimization.md

読み込むタイミング：LLM のコストを最適化するとき、キャッシュ戦略を実装するとき、モデル（GPT/Claude/Gemini）を選ぶとき、トラフィックの急増（バースト料金）に対処するとき、トークン使用量を削減するとき、または予算上限を設定するとき。

references/error-catalog.md

読み込むタイミング：エラーをトラブルシューティングするとき、Webhook の失敗をデバッグするとき、音声の一貫性の問題を修正するとき、認証の問題を解決するとき、RAG インデックスの問題に対処するとき、またはプラットフォーム固有のバグを診断するとき。

references/system-prompt-guide.md

読み込むタイミング：エージェントのシステムプロンプトを書くとき、会話の品質を向上させるとき、6 コンポーネントのフレームワークを実装するとき、プロンプトを反復改善するとき、プロンプトの有効性をテストするとき、またはエージェントの性格・目標・ガードレールを定義するとき。

references/testing-guide.md

読み込むタイミング：自動テストを設定するとき、シナリオテストを実装するとき、エージェントの負荷テストを行うとき、実際の会話をテストに変換するとき、CI/CD と統合するとき、または失敗したテストをデバッグするとき。

references/tool-examples.md

読み込むタイミング：クライアントツール（ブラウザー関数）を実装するとき、サーバーツール（Webhook）を作成するとき、MCP サーバーに接続するとき、システムツールを使用するとき、またはツール実行の問題をデバッグするとき。

references/workflow-examples.md

読み込むタイミング：マルチエージェントのワークフローを構築するとき、通話ルーティングを実装するとき、エスカレーションフローを作成するとき、多言語サポートを設計するとき、またはワークフローの遷移をデバッグするとき。

---

SDK 統合

React SDK（@elevenlabs/react）

主なフック：useConversation()。機能：クライアントツール、イベントストリーミング、接続管理、地域コンプライアンス。上記のクイックスタートパス A を参照してください。

その他の SDK

• JavaScript SDK（@elevenlabs/client）- Vanilla JS/Node.js
• React Native SDK（@elevenlabs/react-native）- モバイルアプリ（Expo）
• Swift SDK - iOS/macOS ネイティブアプリ
• Widget - 埋め込み可能な Web コンポーネント（コード不要）

**テンプレート：**React の完全な実装については、templates/basic-react-agent.tsx を参照してください。

---

その他のプラットフォーム機能

**テストと評価：**シナリオテスト（LLM ベース）、ツール呼び出しのテスト、負荷テスト、シミュレーション API。references/testing-guide.md を参照してください。

**分析：**会話分析、成功評価、データ収集、分析ダッシュボード。

**プライバシーとコンプライアンス：**データ保持、暗号化、ゼロ保持モード、GDPR/HIPAA/SOC 2。references/compliance-guide.md を参照してください。

**コスト最適化：**LLM キャッシュ（90% のコスト削減）、モデルの切り替え、バースト料金。references/cost-optimization.md を参照してください。

**高度な機能：**カスタムモデル（独自の LLM を使用）、通話後の Webhook、チャットモード（テキストのみ）、テレフォニー（Twilio/SIP）、ワークフロー（マルチエージェントのルーティング）。

---

他のスキルとの連携

組み合わせて使用できます：

• cloudflare-worker-base → エッジネットワークにエージェントをデプロイ
• cloudflare-workers-ai → Cloudflare LLM をカスタムモデルとして使用
• cloudflare-durable-objects → 会話状態を永続化
• nextjs → Next.js で React SDK を統合
• ai-sdk-core → Vercel AI SDK プロバイダー
• clerk-auth → 認証済み音声セッション
• hono-routing → Webhook 用 API ルート

---

安全なインストール

AI エージェント SDK パッケージをインストールする際は、サプライチェーンセキュリティのベストプラクティスに従ってください：

• インストール後スクリプトをブロック — npm config set ignore-scripts true（または Bun：デフォルトで無効）
• クールダウン期間 — 新しいパッケージバージョンがコミュニティによって審査されるまで、7 日間待機
• インストール前に監査 — socket package score npm <pkg> を実行するか、socket npm install <pkg> を使用してパッケージを確認

Socket CLI の統合、クールダウンの設定、ロックファイルの検証、CI による適用など、セキュリティ設定の全容については dependency-upgrade スキルを読み込んでください。

リソース

テンプレート（templates/）：

• basic-react-agent.tsx - クライアントツールとイベントを備えた React SDK
• basic-cli-agent.json - 6 コンポーネントのプロンプトを備えた CLI エージェント

リファレンス（references/）：

• api-reference.md - API リファレンス全編
• cli-commands.md - CLI コマンドとワークフロー
• compliance-guide.md - GDPR/HIPAA/SOC 2 への準拠
• cost-optimization.md - LLM のキャッシュとコスト削減
• error-catalog.md - 17 種類のエラーと解決策
• system-prompt-guide.md - 6 コンポーネントのフレームワークガイド
• testing-guide.md - テストと評価
• tool-examples.md - クライアント／サーバー／MCP ツールの例
• workflow-examples.md - マルチエージェントのワークフローパターン

公式ドキュメント：

• プラットフォーム：https://elevenlabs.io/docs/agents-platform/overview
• API：https://elevenlabs.io/docs/api-reference
• 例：https://github.com/elevenlabs/elevenlabs-examples
• Discord：https://discord.com/invite/elevenlabs

---

本番環境でのテスト済み： WordPress Auditor、Customer Support Agents 最終更新日： 2025-11-21 パッケージバージョン： 現行バージョンを確認済み（metadata を参照）