elevenlabs-agents

Name: elevenlabs-agents
Author: jackspace

github.com/jackspaceエージェントワークフロー1641 回インストール12 週間前に更新

elevenlabs-agents について

ElevenLabs Agents Platformは、本番向け音声対話エージェントを構築する開発者向けで、音声認識、LLM、音声合成、会話のターン制御を連携します。ビジュアルワークフロー、SDK、CLI、テスト、分析機能を備え、MCPサーバーの統合にも対応します。

主な機能

01音声認識・LLM・音声合成の連携
02分岐するビジュアル会話ワークフローの設定
03SDKとCLIによるエージェントの作成・管理
04動的変数を使った会話のパーソナライズ
05自動テストの実行と会話分析

活用シーン

01音声によるカスタマーサポートエージェントの構築
02ウェブやモバイルアプリへの音声チャット追加
03CLIによるバージョン管理された設定の運用
04エージェントへのMCPサーバー接続

MCP 対応

エージェントへのMCPサーバー統合に対応します。MCPサーバーへの接続・管理方法はREADMEに記載されていません。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/jackspace/claudeskillz --skill elevenlabs-agents

インストール後、Claude Code で/elevenlabs-agentsを入力して読み込まれたか確認します。

同梱ファイルREADME.mdSKILL.json

詳細

ElevenLabs Agents Platform

概要

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

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

🚨 パッケージの更新（2025 年 11 月）

ElevenLabs は 2025 年 8 月に新しいスコープ付きパッケージへ移行しました。

非推奨（使用しないでください）：

@11labs/react → 非推奨
@11labs/client → 非推奨

現在のパッケージ：

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

古いパッケージがインストールされている場合は、まずアンインストールしてください。

npm uninstall @11labs/react @11labs/client

このスキルを使用する場面

次のような場合に、このスキルを使用してください。

音声対応のカスタマーサポートエージェントを構築する
対話型音声応答（IVR）システムを作成する
会話型 AI アプリケーションを開発する
テレフォニー（Twilio、SIP トランキング）を統合する
Web／モバイルアプリに音声チャットを実装する
CLI でエージェントを設定する（「コードとしてのエージェント」）
エージェント向けに RAG／ナレッジベースを設定する
MCP（Model Context Protocol）サーバーを統合する
HIPAA／GDPR に準拠した音声システムを構築する
キャッシュ戦略によって LLM のコストを最適化する

プラットフォームの機能

設計と設定：

ビジュアルビルダーによる複数ステップのワークフロー
システムプロンプトの設計（6 コンポーネントのフレームワーク）
31 言語に対応した 5000 以上の音声
発音辞書（IPA／CMU 形式）
速度調整（0.7x～1.2x）
RAG を活用したナレッジベース
動的変数とパーソナライズ

接続とデプロイ：

React SDK（@elevenlabs/react）
JavaScript SDK（@elevenlabs/client）
React Native SDK（@elevenlabs/react-native）
Swift SDK（iOS／macOS）
埋め込み可能なウィジェット
テレフォニー統合（Twilio、SIP）
Scribe（リアルタイム音声テキスト変換）- ベータ版

運用と最適化：

自動テスト（シナリオ、ツール呼び出し、負荷）
会話の分析と評価
分析ダッシュボード（解決率、センチメント、コンプライアンス）
プライバシー制御（GDPR、HIPAA、SOC 2）
コスト最適化（LLM キャッシュ、モデル切り替え、バースト料金）
「コードとしてのエージェント」ワークフロー向け CLI

1. クイックスタート（3 つの統合方法）

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

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

インストール：

npm install @elevenlabs/react zod

基本的な例：

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

export default function VoiceChat() {
  const { startConversation, stopConversation, status } = useConversation({
    // Public agent (no API key needed)
    agentId: 'your-agent-id',

    // OR private agent (requires API key)
    apiKey: process.env.NEXT_PUBLIC_ELEVENLABS_API_KEY,

    // OR signed URL (server-generated, most secure)
    signedUrl: '/api/elevenlabs/auth',

    // Client-side tools (browser functions)
    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
    onConnect: () => console.log('Connected'),
    onDisconnect: () => console.log('Disconnected'),
    onEvent: (event) => {
      switch (event.type) {
        case 'transcript':
          console.log('User said:', event.data.text);
          break;
        case 'agent_response':
          console.log('Agent replied:', event.data.text);
          break;
      }
    },

    // Regional compliance (GDPR, data residency)
    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>
  );
}

方法 B：CLI（「コードとしてのエージェント」）

バージョン管理と CI/CD を利用して、コードからエージェントを管理する場合に使用します。

インストール：

npm install -g @elevenlabs/agents-cli
# or
pnpm install -g @elevenlabs/agents-cli

ワークフロー：

# 1. Authenticate
elevenlabs auth login

# 2. Initialize project (creates agents.json, tools.json, tests.json)
elevenlabs agents init

# 3. Create agent from template
elevenlabs agents add "Support Agent" --template customer-service

# 4. Configure in agent_configs/support-agent.json

# 5. Push to platform
elevenlabs agents push --env dev

# 6. Test
elevenlabs agents test "Support Agent"

# 7. Deploy to production
elevenlabs agents push --env prod

作成されるプロジェクト構成：

your_project/
├── agents.json              # Agent registry
├── tools.json               # Tool configurations
├── tests.json               # Test configurations
├── agent_configs/           # Individual agent files
├── tool_configs/            # Tool configuration files
└── test_configs/            # Test configuration files

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

エージェントを動的に作成する場合（マルチテナント、SaaS プラットフォーム）に使用します。

インストール：

npm install elevenlabs

例：

import { ElevenLabsClient } from 'elevenlabs';

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

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

console.log('Agent created:', agent.agent_id);

2. エージェントの設定

システムプロンプトの構成（6 コンポーネント）

ElevenLabs は、次の 6 つのコンポーネントを使用してエージェントのプロンプトを構成することを推奨しています。

1. パーソナリティ

エージェントのアイデンティティ、役割、性格を定義します。

例：

You are Alex, a friendly and knowledgeable customer support specialist at TechCorp.
You have 5 years of experience helping customers solve technical issues.
You're patient, empathetic, and always maintain a positive attitude.

2. 環境

コミュニケーションの状況（電話、Web チャット、ビデオ通話）を説明します。

例：

You're speaking with customers over the phone. Communication is voice-only.
Customers may have background noise or poor connection quality.
Speak clearly and occasionally use thoughtful pauses for emphasis.

3. トーン

形式の度合い、話し方のパターン、ユーモア、冗長さを指定します。

例：

Tone: Professional yet warm. Use contractions ("I'm" instead of "I am") to sound natural.
Avoid jargon unless the customer uses it first. Keep responses concise (2-3 sentences max).
Use encouraging phrases like "I'll be happy to help with that" and "Let's get this sorted for you."

4. 目標

目的と成功基準を定義します。

例：

Primary Goal: Resolve customer technical issues on the first call.
Secondary Goals:
- Verify customer identity securely
- Document issue details accurately
- Offer proactive solutions
- End calls with confirmation that the issue is resolved

Success Criteria: Customer verbally confirms their issue is resolved.

5. ガードレール

境界、禁止事項、倫理上の制約を設定します。

例：

Guardrails:
- Never provide medical, legal, or financial advice
- Do not share confidential company information
- If asked about competitors, politely redirect to TechCorp's offerings
- Escalate to a human supervisor if customer becomes abusive
- Never make promises about refunds or credits without verification

6. ツール

利用可能な外部機能と、その使用タイミングを説明します。

例：

Available Tools:
1. lookup_order(order_id) - Fetch order details from database. Use when customer mentions an order number.
2. transfer_to_supervisor() - Escalate to human agent. Use when issue requires manager approval.
3. send_password_reset(email) - Trigger password reset email. Use when customer can't access account.

Always explain to the customer what you're doing before calling a tool.

完全なテンプレート：

{
  "agent": {
    "prompt": {
      "prompt": "Personality:\nYou are Alex, a friendly customer support specialist.\n\nEnvironment:\nYou're speaking with customers over the phone.\n\nTone:\nProfessional yet warm. Keep responses concise.\n\nGoal:\nResolve technical issues on the first call.\n\nGuardrails:\n- Never provide medical/legal/financial advice\n- Escalate abusive customers\n\nTools:\n- lookup_order(order_id) - Fetch order details\n- transfer_to_supervisor() - Escalate to human",
      "llm": "gpt-4o",
      "temperature": 0.7,
      "max_tokens": 500
    }
  }
}

ターンテイクモード

エージェントがいつ割り込むか、ユーザーが話し終えるまで待つかを制御します。

3 つのモード：

モード	動作	最適な用途
Eager	素早く応答し、可能な限り早いタイミングで発話します	テンポの速いサポート、迅速な注文
Normal	バランスが取れており、会話の自然な区切りを待ちます	一般的なカスタマーサービス（デフォルト）
Patient	より長く待ち、ユーザーが詳しく応答できるようにします	情報収集、セラピー、個別指導

設定：

{
  "conversation_config": {
    "turn": {
      "mode": "patient" // "eager" | "normal" | "patient"
    }
  }
}

ユースケース：

Eager：ファストフードの注文、簡単な FAQ、緊急通知
Normal：一般的なサポート、製品に関する問い合わせ、予約
Patient：詳細なフォームの入力、感情面のサポート、教育的な個別指導

注意点：

Eager モードは、一部のユーザーには割り込みが多いと感じられることがあります
Patient モードは、テンポの速い場面では遅く感じられることがあります
コンテキストに応じた動作を実現するため、ワークフロー内で動的に調整できます

ワークフロー（ビジュアルビルダー）

サブエージェントノードと条件付きルーティングを使って、分岐する会話フローを作成します。

ノードの種類：

サブエージェントノード - 基本エージェントの設定を上書きします（プロンプト、音声、ターンテイクを変更）
ツールノード - ツールの実行を保証します（サブエージェント内のツールとは異なります）

設定：

{
  "workflow": {
    "nodes": [
      {
        "id": "node_1",
        "type": "subagent",
        "config": {
          "system_prompt": "You are now a technical support specialist. Ask detailed diagnostic questions.",
          "turn_eagerness": "patient",
          "voice_id": "tech_support_voice_id"
        }
      },
      {
        "id": "node_2",
        "type": "tool",
        "tool_name": "transfer_to_human"
      }
    ],
    "edges": [
      {
        "from": "node_1",
        "to": "node_2",
        "condition": "user_requests_escalation"
      }
    ]
  }
}

ユースケース：

複数部門へのルーティング（営業 → サポート → 請求）
決定木（「営業は 1、サポートは 2 を押してください」）
ロールプレイのシナリオ（顧客とエージェントの声）
エスカレーション経路（ボット → 人間への引き継ぎ）

注意点：

ワークフローでは、ノードの遷移ごとに約 100～200 ms のレイテンシーが追加されます
ツールノードでは実行が保証されます（サブエージェントはツールをスキップすることがあります）
適切にテストしないと、エッジによって無限ループが発生する可能性があります

動的変数とパーソナライズ

{{var_name}} 構文を使って、実行時のデータをプロンプト、最初のメッセージ、ツールのパラメーターに挿入します。

システム変数（自動的に使用可能）：

{{system__agent_id}}         // Current agent ID
{{system__conversation_id}}  // Conversation ID
{{system__caller_id}}        // Phone number (telephony only)
{{system__called_number}}    // Called number (telephony only)
{{system__call_duration_secs}} // Call duration
{{system__time_utc}}         // Current UTC time
{{system__call_sid}}         // Twilio call SID (Twilio only)

カスタム変数：

// Provide when starting conversation
const conversation = await client.conversations.create({
  agent_id: "agent_123",
  dynamic_variables: {
    user_name: "John",
    account_tier: "premium",
    order_id: "ORD-12345"
  }
});

シークレット変数（API キー用）：

{{secret__stripe_api_key}}
{{secret__database_password}}

重要：シークレット変数はヘッダーでのみ使用され、LLM プロバイダーに送信されることはありません。

プロンプトでの使用方法：

{
  "agent": {
    "prompt": {
      "prompt": "You are helping {{user_name}}, a {{account_tier}} customer."
    },
    "first_message": "Hello {{user_name}}! I see you're calling about order {{order_id}}."
  }
}

注意点：変数が不足していると、「Missing required dynamic variables」エラーが発生します。会話を開始する際は、参照される変数をすべて指定してください。

認証パターン

オプション 1：パブリックエージェント（API キー不要）

const { startConversation } = useConversation({
  agentId: 'your-public-agent-id' // Anyone can use
});

オプション 2：API キーを使用するプライベートエージェント

const { startConversation } = useConversation({
  agentId: 'your-private-agent-id',
  apiKey: process.env.NEXT_PUBLIC_ELEVENLABS_API_KEY
});

⚠️ 警告：クライアント側のコードで API キーを公開しないでください。代わりに署名付き URL を使用してください。

オプション 3：署名付き URL（本番環境に推奨）

// Server-side (Next.js API route)
import { ElevenLabsClient } from 'elevenlabs';

export async function POST(req: Request) {
  const client = new ElevenLabsClient({
    apiKey: process.env.ELEVENLABS_API_KEY // Server-side only
  });

  const signedUrl = await client.convai.getSignedUrl({
    agent_id: 'your-agent-id'
  });

  return Response.json({ signedUrl });
}

// Client-side
const { startConversation } = useConversation({
  agentId: 'your-agent-id',
  signedUrl: await fetch('/api/elevenlabs/auth').then(r => r.json()).then(d => d.signedUrl)
});

3. 音声と言語の機能

複数音声のサポート

1 回の会話中に、異なる音声を動的に切り替えます。

ユースケース：

複数キャラクターの物語（キャラクターごとに異なる音声）
語学学習（各言語でネイティブスピーカーの音声を使用）
ロールプレイのシナリオ（顧客とエージェント）
感情表現を行うエージェント（気分に応じて異なる音声を使用）

設定：

{
  "agent": {
    "prompt": {
      "prompt": "When speaking as the customer, use voice_id 'customer_voice_abc123'. When speaking as the agent, use voice_id 'agent_voice_def456'."
    }
  }
}

注意点：

音声の切り替えごとに約 200 ms のレイテンシーが追加されます
正しく切り替えるには、慎重なプロンプトエンジニアリングが必要です
すべての音声があらゆるキャラクターに同じように適しているわけではありません

発音辞書

特定の単語やフレーズの発音をカスタマイズします。

対応フォーマット：

IPA（国際音声記号）
CMU（カーネギーメロン大学発音辞書）
単語の置換（TTS の前に単語を置き換えます）

設定：

{
  "pronunciation_dictionary": [
    {
      "word": "ElevenLabs",
      "pronunciation": "ɪˈlɛvənlæbz",
      "format": "ipa"
    },
    {
      "word": "API",
      "pronunciation": "ey-pee-ay",
      "format": "cmu"
    },
    {
      "word": "AI",
      "substitution": "artificial intelligence"
    }
  ]
}

ユースケース：

ブランド名（例：「IKEA」→「ee-KAY-uh」）
頭字語（例：「API」→「A-P-I」または「ay-pee-eye」）
専門用語
物語に登場するキャラクター名

注意点：音素ベースの発音に対応しているのは、Turbo v2/v2.5 モデルのみです。他のモデルでは音素エントリーは無視されますが、単語の置換は引き続き処理されます。

速度制御

話す速度を動的に調整します（0.7x～1.2x）。

設定：

{
  "voice_settings": {
    "speed": 1.0 // 0.7 = slow, 1.0 = normal, 1.2 = fast
  }
}

使用例：

ゆっくり（0.7x～0.9x）：アクセシビリティ、子ども、非ネイティブスピーカー向け
通常（1.0x）：ほとんどのユースケースでのデフォルト
速く（1.1x～1.2x）：緊急通知、上級ユーザー向け

ベストプラクティス：

自然に聞こえる調整には、0.9x～1.1xを使用します
極端な値（0.7未満または1.2超）では品質が低下します
速度は発話ごとではなく、エージェントごとに調整できます

音声の設計

ElevenLabs Voice Design ツールを使用してカスタム音声を作成します。

ワークフロー：

Voice Library → Create Voice に移動します
Voice Design（テキストから音声）または Voice Cloning（サンプル音声）を使用します
サンプルテキストで音声をテストします
音声をライブラリに保存します
エージェントの設定で voice_id を使用します

音声クローニングのベストプラクティス：

クリアな音声サンプルを使用します（背景ノイズ、音楽、ポップノイズがないもの）
マイクとの距離を一定に保ちます
極端な音量（ささやき声や叫び声）は避けます
1～2分の音声を推奨します

注意点：英語でトレーニングされた音声を英語以外の言語に使用すると、発音に問題が生じます。必ず言語に合った音声を使用してください。

言語設定

自動検出と会話中の切り替えにより、32以上の言語に対応します。

設定：

{
  "agent": {
    "language": "en" // ISO 639-1 code
  }
}

多言語プリセット（言語ごとに異なる音声）：

{
  "conversation_config": {
    "language_presets": [
      {
        "language": "en",
        "voice_id": "en_voice_id",
        "first_message": "Hello! How can I help you today?"
      },
      {
        "language": "es",
        "voice_id": "es_voice_id",
        "first_message": "¡Hola! ¿Cómo puedo ayudarte hoy?"
      },
      {
        "language": "fr",
        "voice_id": "fr_voice_id",
        "first_message": "Bonjour! Comment puis-je vous aider aujourd'hui?"
      }
    ]
  }
}

言語の自動検出：エージェントがユーザーの言語を検出し、自動的に切り替えます。

対応言語：英語、スペイン語、フランス語、ドイツ語、イタリア語、ポルトガル語、オランダ語、ポーランド語、アラビア語、中国語、日本語、韓国語、ヒンディー語など、さらに18以上の言語に対応しています。

4. ナレッジベースと RAG

RAG（検索拡張生成）

ドキュメント全体をコンテキストに読み込まずに、エージェントが大規模なナレッジベースにアクセスできるようにします。

仕組み：

ドキュメント（PDF、TXT、DOCX）をナレッジベースにアップロードします
ElevenLabs がベクトル埋め込みを自動的に計算します
会話中、意味的類似性に基づいて関連するチャンクが取得されます
LLM が取得したコンテキストを使用して応答を生成します

設定：

{
  "agent": {
    "prompt": {
      "knowledge_base": ["doc_id_1", "doc_id_2"]
    }
  }
}

API 経由でドキュメントをアップロード：

import { ElevenLabsClient } from 'elevenlabs';

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

// Upload document
const doc = await client.knowledgeBase.upload({
  file: fs.createReadStream('support_docs.pdf'),
  name: 'Support Documentation'
});

// Compute RAG index
await client.knowledgeBase.computeRagIndex({
  document_id: doc.id,
  embedding_model: 'e5_mistral_7b' // or 'multilingual_e5_large'
});

検索設定：

{
  "knowledge_base_config": {
    "max_chunks": 5,              // Number of chunks to retrieve
    "vector_distance_threshold": 0.8  // Similarity threshold
  }
}

使用例：

製品ドキュメントのエージェント
カスタマーサポート（FAQ、ヘルプセンター）
教育用チューター（教科書、講義ノート）
医療アシスタント（医療ガイドライン）

注意点：

RAG により、クエリごとに約500msのレイテンシーが追加されます
チャンクが増えるほどコストは高くなりますが、コンテキストは向上します
ベクトル距離が大きいほどコンテキストは増えますが、関連性が低くなる可能性があります
ドキュメントは使用前にインデックス化する必要があります（大きなドキュメントでは数分かかる場合があります）

5. ツール（4種類）

ElevenLabs は、実行パターンの異なる4種類のツールに対応しています。

A. クライアントツール

クライアント側（ブラウザーまたはモバイルアプリ）で操作を実行します。

使用例：

UI 要素を更新する（ショッピングカート、通知）
ナビゲーションを開始する（ユーザーをページにリダイレクトする）
ローカルストレージにアクセスする
メディア再生を制御する

React の例：

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

const { startConversation } = useConversation({
  clientTools: {
    updateCart: {
      description: "Update the shopping cart with new items",
      parameters: z.object({
        item: z.string().describe("The item name"),
        quantity: z.number().describe("Quantity to add")
      }),
      handler: async ({ item, quantity }) => {
        // Client-side logic
        const cart = getCart();
        cart.add(item, quantity);
        updateUI(cart);
        return { success: true, total: cart.total };
      }
    },
    navigate: {
      description: "Navigate to a different page",
      parameters: z.object({
        url: z.string().describe("The URL to navigate to")
      }),
      handler: async ({ url }) => {
        window.location.href = url;
        return { success: true };
      }
    }
  }
});

注意点：

ツール名は大文字と小文字を区別します
値を返す必要があります（エージェントは戻り値を読み取ります）
ハンドラーは非同期にできます

B. サーバーツール（Webhook）

ElevenLabs サーバーから外部 API に HTTP リクエストを送信します。

使用例：

リアルタイムデータを取得する（天気、株価）
CRM システムを更新する（Salesforce、HubSpot）
支払いを処理する（Stripe、PayPal）
メール／SMS を送信する（SendGrid、Twilio）

CLI 経由で設定：

elevenlabs tools add-webhook "Get Weather" --config-path tool_configs/get-weather.json

tool_configs/get-weather.json：

{
  "name": "get_weather",
  "description": "Fetch current weather for a city",
  "url": "https://api.weather.com/v1/current",
  "method": "GET",
  "parameters": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "The city name (e.g., 'London', 'New York')"
      }
    },
    "required": ["city"]
  },
  "headers": {
    "Authorization": "Bearer {{secret__weather_api_key}}"
  }
}

ツール内の動的変数：

{
  "url": "https://api.crm.com/customers/{{user_id}}",
  "headers": {
    "X-API-Key": "{{secret__crm_api_key}}"
  }
}

注意点：

シークレット変数はヘッダー内でのみ機能します（URL や本文では使用できません）
スキーマの説明は、ツールをいつ使用するかを LLM に示します

C. MCP ツール（Model Context Protocol）

外部の MCP サーバーに接続して、標準化されたツールアクセスを利用します。

ユースケース：

データベースにアクセスする（PostgreSQL、MongoDB）
ナレッジベースを検索する（Pinecone、Weaviate）
IDE と統合する（VS Code、Cursor）
データソースに接続する（Google Drive、Notion）

設定：

ダッシュボードで MCP サーバーの統合に移動します
「Add Custom MCP Server」をクリックします
次の項目を設定します：
- Name：サーバーの識別子
- Server URL：SSE または HTTP エンドポイント
- Secret Token：任意の認証ヘッダー
接続をテストしてツールを検出します
エージェントに追加します（公開または非公開）

承認モード：

Always Ask：最大限のセキュリティを確保できます。ツール呼び出しごとに許可が必要です
Fine-Grained：ツールごとに承認設定を行います
No Approval：すべてのツールを自動実行します

注意事項：

SSE および HTTP ストリーミング可能なトランスポートのみサポートされています
MCP サーバーは、一般にアクセス可能であるか、認証の背後にある必要があります
Zero Retention Mode では利用できません
HIPAA コンプライアンスとは互換性がありません

例：Claude Desktop で ElevenLabs MCP サーバーを使用する：

{
  "mcpServers": {
    "ElevenLabs": {
      "command": "uvx",
      "args": ["elevenlabs-mcp"],
      "env": {
        "ELEVENLABS_API_KEY": "<your-key>",
        "ELEVENLABS_MCP_OUTPUT_MODE": "files"
      }
    }
  }
}

D. システムツール

外部呼び出しを行わずに、会話の内部状態を変更します。

ユースケース：

会話のコンテキストを更新する
ワークフローのノードを切り替える
会話中にエージェントの動作を変更する
会話の状態を追跡する

組み込みシステムツール：

end_call - 会話を終了します
detect_language - ユーザーの言語を検出します
transfer_agent - 別のエージェント／ワークフローノードに切り替えます
transfer_to_number - 外部の電話番号に転送します（テレフォニーのみ）
dtmf_playpad - DTMF キーパッドを表示します（テレフォニーのみ）
voicemail_detection - 留守番電話を検出します（テレフォニーのみ）

設定：

{
  "system_tools": [
    {
      "name": "update_conversation_state",
      "description": "Update the conversation context with new information",
      "parameters": {
        "key": { "type": "string" },
        "value": { "type": "string" }
      }
    }
  ]
}

注意事項：

システムツールは外部 API を呼び出しません
変更は一時的なものであり、会話の終了後に失われます
ワークフローと状態管理に役立ちます

6. SDK の統合

React SDK（`@elevenlabs/react`）

インストール：

npm install @elevenlabs/react zod

完全な例：

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

export default function VoiceAgent() {
  const [transcript, setTranscript] = useState<string[]>([]);

  const {
    startConversation,
    stopConversation,
    status,
    isSpeaking
  } = useConversation({
    agentId: 'your-agent-id',

    // Authentication (choose one)
    apiKey: process.env.NEXT_PUBLIC_ELEVENLABS_API_KEY,

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

    // Events
    onConnect: () => {
      console.log('Connected to agent');
      setTranscript([]);
    },
    onDisconnect: () => console.log('Disconnected'),
    onEvent: (event) => {
      if (event.type === 'transcript') {
        setTranscript(prev => [...prev, `User: ${event.data.text}`]);
      } else if (event.type === 'agent_response') {
        setTranscript(prev => [...prev, `Agent: ${event.data.text}`]);
      }
    },
    onError: (error) => console.error('Error:', error),

    // Regional compliance
    serverLocation: 'us'
  });

  return (
    <div>
      <div>
        <button onClick={startConversation} disabled={status === 'connected'}>
          Start Conversation
        </button>
        <button onClick={stopConversation} disabled={status !== 'connected'}>
          Stop
        </button>
      </div>

      <div>Status: {status}</div>
      <div>{isSpeaking && 'Agent is speaking...'}</div>

      <div>
        <h3>Transcript</h3>
        {transcript.map((line, i) => (
          <p key={i}>{line}</p>
        ))}
      </div>
    </div>
  );
}

JavaScript SDK（`@elevenlabs/client`）

React を使用しない標準の JavaScript プロジェクト向けです。

インストール：

npm install @elevenlabs/client

例：

import { Conversation } from '@elevenlabs/client';

const conversation = new Conversation({
  agentId: 'your-agent-id',
  apiKey: process.env.ELEVENLABS_API_KEY,

  onConnect: () => console.log('Connected'),
  onDisconnect: () => console.log('Disconnected'),

  onEvent: (event) => {
    switch (event.type) {
      case 'transcript':
        document.getElementById('user-text').textContent = event.data.text;
        break;
      case 'agent_response':
        document.getElementById('agent-text').textContent = event.data.text;
        break;
    }
  }
});

// Start conversation
document.getElementById('start-btn').addEventListener('click', async () => {
  await conversation.start();
});

// Stop conversation
document.getElementById('stop-btn').addEventListener('click', async () => {
  await conversation.stop();
});

接続タイプ：WebRTC と WebSocket

ElevenLabs SDK は、特性の異なる 2 種類の接続タイプをサポートしています。

比較表：

機能	WebSocket	WebRTC
認証	`signedUrl`	`conversationToken`
オーディオ形式	設定可能	PCM_48000（ハードコード）
サンプルレート	設定可能（16k、24k、48k）	48000（ハードコード）
レイテンシ	標準	低い
デバイスの切り替え	柔軟	制限あり（形式が固定）
最適な用途	一般用途、柔軟性	低レイテンシが必要な場合

WebSocket の設定（デフォルト）：

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

const { startConversation } = useConversation({
  agentId: 'your-agent-id',

  // WebSocket uses signed URL
  signedUrl: async () => {
    const response = await fetch('/api/elevenlabs/auth');
    const { signedUrl } = await response.json();
    return signedUrl;
  },

  // Connection type (optional, defaults to 'websocket')
  connectionType: 'websocket',

  // Audio config (flexible)
  audioConfig: {
    sampleRate: 24000, // 16000, 24000, or 48000
    format: 'PCM_24000'
  }
});

WebRTC の設定：

const { startConversation } = useConversation({
  agentId: 'your-agent-id',

  // WebRTC uses conversation token (different auth flow)
  conversationToken: async () => {
    const response = await fetch('/api/elevenlabs/token');
    const { token } = await response.json();
    return token;
  },

  // Connection type
  connectionType: 'webrtc',

  // Audio format is HARDCODED to PCM_48000 (not configurable)
  // audioConfig ignored for WebRTC
});

バックエンドのトークンエンドポイント：

// WebSocket signed URL (GET /v1/convai/conversation/get-signed-url)
app.get('/api/elevenlabs/auth', async (req, res) => {
  const response = await fetch(
    `https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=${AGENT_ID}`,
    { headers: { 'xi-api-key': ELEVENLABS_API_KEY } }
  );
  const { signed_url } = await response.json();
  res.json({ signedUrl: signed_url });
});

// WebRTC conversation token (GET /v1/convai/conversation/token)
app.get('/api/elevenlabs/token', async (req, res) => {
  const response = await fetch(
    `https://api.elevenlabs.io/v1/convai/conversation/token?agent_id=${AGENT_ID}`,
    { headers: { 'xi-api-key': ELEVENLABS_API_KEY } }
  );
  const { conversation_token } = await response.json();
  res.json({ token: conversation_token });
});

それぞれの使用場面：

WebSocket を使用する場合	WebRTC を使用する場合
柔軟なオーディオ形式が必要	可能な限り低いレイテンシが必要
オーディオデバイスを頻繁に切り替える	オーディオ形式を 48kHz に固定できる
標準的なレイテンシで問題ない	リアルタイムアプリケーションを構築する
最大限の設定制御が必要	パフォーマンスが重要

注意事項：

WebRTC は PCM_48000 にハードコードされており、形式を変更できません
WebRTC では形式が固定されているため、デバイスの切り替えに制限があります
認証方法が異なります（signedUrl と conversationToken）
WebRTC はパフォーマンスが優れている可能性がありますが、柔軟性は低くなります

React Native SDK（Expo）

インストール：

npx expo install @elevenlabs/react-native @livekit/react-native @livekit/react-native-webrtc livekit-client

要件：

Expo SDK 47 以降
iOS 14.0 以降／macOS 11.0 以降
カスタム開発ビルドが必要（Expo Go はサポートされていません）

例：

import { useConversation } from '@elevenlabs/react-native';
import { View, Button, Text } from 'react-native';
import { z } from 'zod';

export default function App() {
  const { startConversation, stopConversation, status } = useConversation({
    agentId: 'your-agent-id',
    signedUrl: 'https://api.elevenlabs.io/v1/convai/auth/...',

    clientTools: {
      updateProfile: {
        description: "Update user profile",
        parameters: z.object({
          name: z.string()
        }),
        handler: async ({ name }) => {
          console.log('Updating profile:', name);
          return { success: true };
        }
      }
    }
  });

  return (
    <View style={{ padding: 20 }}>
      <Button title="Start" onPress={startConversation} />
      <Button title="Stop" onPress={stopConversation} />
      <Text>Status: {status}</Text>
    </View>
  );
}

注意事項：

カスタム開発ビルドが必要です（Expo Go は使用できません）
iOS／macOS のみ対応しています（Android は Kotlin SDK でサポートされますが、まだ正式リリースされていません）

Swift SDK（iOS/macOS）

インストール（Swift Package Manager）：

dependencies: [
  .package(url: "https://github.com/elevenlabs/elevenlabs-swift-sdk", from: "1.0.0")
]

要件：

iOS 14.0+ / macOS 11.0+
Swift 5.9+

ユースケース：

ネイティブ iOS アプリ
macOS アプリケーション
watchOS（制限あり）

ウィジェット（埋め込み可能な Web コンポーネント）

インストール：ダッシュボードから埋め込みコードをコピーするか、次のテンプレートを使用します。

<script src="https://elevenlabs.io/convai-widget/index.js"></script>
<script>
  ElevenLabsWidget.init({
    agentId: 'your-agent-id',

    // Theming
    theme: {
      primaryColor: '#3B82F6',
      backgroundColor: '#1F2937',
      textColor: '#F9FAFB'
    },

    // Position
    position: 'bottom-right', // 'bottom-left' | 'bottom-right'

    // Custom branding
    branding: {
      logo: 'https://example.com/logo.png',
      name: 'Support Agent'
    }
  });
</script>

ユースケース：

カスタマーサポートのチャットバブル
Web サイトのアシスタント
見込み顧客の獲得フォーム

Scribe（リアルタイム音声テキスト変換）

ステータス：クローズドベータ（営業への問い合わせが必要です） リリース：2025

Scribe は、低遅延の文字起こしを実現する ElevenLabs のリアルタイム音声テキスト変換サービスです。

機能：

マイク入力のストリーミング（リアルタイム文字起こし）
録音済み音声ファイルの文字起こし
部分的な（中間）文字起こしと最終文字起こし
単語レベルのタイムスタンプ
音声アクティビティ検出（VAD）
手動および自動の確定方式
言語検出
PCM_16000 および PCM_24000 の音声形式

認証：使い捨てトークンを使用します（API キーではありません）。

// Fetch token from backend
const response = await fetch('/api/scribe/token');
const { token } = await response.json();

// Backend endpoint
const token = await client.scribe.getToken();
return { token };

React フック（useScribe）：

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

export default function Transcription() {
  const {
    connect,
    disconnect,
    startRecording,
    stopRecording,
    status,
    transcript,
    partialTranscript
  } = useScribe({
    token: async () => {
      const response = await fetch('/api/scribe/token');
      const { token } = await response.json();
      return token;
    },

    // Commit strategy
    commitStrategy: 'vad', // 'vad' (automatic) or 'manual'

    // Audio format
    sampleRate: 16000, // 16000 or 24000

    // Events
    onConnect: () => console.log('Connected to Scribe'),
    onDisconnect: () => console.log('Disconnected'),

    onPartialTranscript: (text) => {
      console.log('Interim:', text);
    },

    onFinalTranscript: (text, timestamps) => {
      console.log('Final:', text);
      console.log('Timestamps:', timestamps); // Word-level timing
    },

    onError: (error) => console.error('Error:', error)
  });

  return (
    <div>
      <button onClick={connect}>Connect</button>
      <button onClick={startRecording}>Start Recording</button>
      <button onClick={stopRecording}>Stop Recording</button>
      <button onClick={disconnect}>Disconnect</button>

      <p>Status: {status}</p>
      <p>Partial: {partialTranscript}</p>
      <p>Final: {transcript}</p>
    </div>
  );
}

JavaScript SDK（Scribe.connect）：

import { Scribe } from '@elevenlabs/client';

const connection = await Scribe.connect({
  token: 'your-single-use-token',

  sampleRate: 16000,
  commitStrategy: 'vad',

  onPartialTranscript: (text) => {
    document.getElementById('interim').textContent = text;
  },

  onFinalTranscript: (text, timestamps) => {
    const finalDiv = document.getElementById('final');
    finalDiv.textContent += text + ' ';

    // timestamps: [{ word: 'hello', start: 0.5, end: 0.8 }, ...]
  },

  onError: (error) => {
    console.error('Scribe error:', error);
  }
});

// Start recording from microphone
await connection.startRecording();

// Stop recording
await connection.stopRecording();

// Manual commit (if commitStrategy: 'manual')
await connection.commit();

// Disconnect
await connection.disconnect();

録音済みファイルの文字起こし：

import { Scribe } from '@elevenlabs/client';

const connection = await Scribe.connect({ token });

// Send audio buffer
const audioBuffer = fs.readFileSync('recording.pcm');
await connection.sendAudioData(audioBuffer);

// Manually commit to get final transcript
await connection.commit();

// Wait for final transcript event

イベントの種類：

SESSION_STARTED：接続が確立されました
PARTIAL_TRANSCRIPT：中間の文字起こし（バッファリングなし）
FINAL_TRANSCRIPT：文またはフレーズの全文
FINAL_TRANSCRIPT_WITH_TIMESTAMPS：最終文字起こしと単語ごとのタイミング
ERROR：文字起こしエラー
AUTH_ERROR：認証に失敗しました
OPEN：WebSocket が開きました
CLOSE：WebSocket が閉じました

確定方式：

方式	説明	使用する場面
`vad`（自動）	無音を検出すると、音声アクティビティ検出が自動的に確定します	リアルタイム文字起こし
`manual`	`connection.commit()` を明示的に呼び出します	録音済みファイル、確定を制御する場合

音声形式：

PCM_16000（16kHz、16-bit PCM）
PCM_24000（24kHz、16-bit PCM）

注意点：

トークンは使い捨てです（接続後に有効期限が切れます）
クローズドベータのため、営業への問い合わせが必要です
言語は自動検出されます（手動での上書きはできません）
話者ダイアライゼーションにはまだ対応していません

Scribe を使用する場面：

カスタムの文字起こし UI の構築
リアルタイム字幕
ボイスメモアプリ
会議の文字起こし
アクセシビリティ機能

使用しない場面：以下が必要な場合は、代わりにAgents Platformを使用してください。

会話型 AI（LLM + TTS）
双方向の音声対話
エージェントの応答

7. テストと評価

シナリオテスト（LLM ベースの評価）

会話全体をシミュレートし、成功基準に照らして評価します。

CLI による設定：

elevenlabs tests add "Refund Request Test" --template basic-llm

test_configs/refund-request-test.json：

{
  "name": "Refund Request Test",
  "scenario": "Customer requests refund for defective product",
  "user_input": "I want a refund for order #12345. The product was broken when it arrived.",
  "success_criteria": [
    "Agent acknowledges the request empathetically",
    "Agent asks for order number (which was already provided)",
    "Agent verifies order details",
    "Agent provides refund timeline or next steps"
  ],
  "evaluation_type": "llm"
}

テストの実行：

elevenlabs agents test "Support Agent"

ツール呼び出しテスト

エージェントが適切なパラメーターでツールを正しく使用することを確認します。

設定：

{
  "name": "Account Balance Test",
  "scenario": "Customer requests account balance",
  "expected_tool_call": {
    "tool_name": "get_account_balance",
    "parameters": {
      "account_id": "ACC-12345"
    }
  }
}

負荷テスト

高い同時実行数におけるエージェントの処理能力をテストします。

設定：

# Spawn 100 users, 1 per second, test for 10 minutes
elevenlabs test load \
  --users 100 \
  --spawn-rate 1 \
  --duration 600

注意点：

負荷テストでは実際の API クレジットを消費します
想定されるトラフィックの急増には、バースト料金を使用してください
レート制限に達しないよう、慎重な計画が必要です

シミュレーション API（プログラムによるテスト）

API エンドポイント：

POST /v1/convai/agents/:agent_id/simulate

例：

const simulation = await client.agents.simulate({
  agent_id: 'agent_123',
  scenario: 'Customer requests refund',
  user_messages: [
    "I want a refund for order #12345",
    "I ordered it last week",
    "Yes, please process it"
  ],
  success_criteria: [
    "Agent acknowledges request",
    "Agent asks for order details",
    "Agent provides refund timeline"
  ]
});

console.log('Test passed:', simulation.passed);
console.log('Criteria met:', simulation.evaluation.criteria_met);

ユースケース：

CI/CD との統合（デプロイ前のテスト）
リグレッションテスト
負荷テストの準備

8. 分析とモニタリング

会話の分析

会話の文字起こしから構造化データを抽出します。

機能：

成功の評価（LLM ベース）

{
  "evaluation_criteria": {
    "resolution": "Was the customer's issue resolved?",
    "sentiment": "Was the conversation tone positive?",
    "compliance": "Did the agent follow company policies?"
  }
}

データ収集

{
  "data_collection": {
    "fields": [
      { "name": "customer_name", "type": "string" },
      { "name": "issue_type", "type": "enum", "values": ["billing", "technical", "other"] },
      { "name": "satisfaction", "type": "number", "range": [1, 5] }
    ]
  }
}

利用方法：

Post-call Webhook 経由（リアルタイム）
Analytics Dashboard 経由（一括）
API 経由（オンデマンド）

Analytics Dashboard

指標：

解決率：解決済みの問題の割合
CX 指標：センチメント、満足度、CSAT
コンプライアンス：ポリシーの遵守、ガードレール違反
パフォーマンス：応答時間、通話時間、同時実行数
ツールの使用状況：ツール呼び出し頻度、成功率
LLM コスト：エージェント／会話ごとのコストを追跡

アクセス方法：ダッシュボード → Analytics タブ

9. プライバシーとコンプライアンス

データ保持

デフォルト：2 年（GDPR 準拠）

設定：

{
  "privacy": {
    "transcripts": {
      "retention_days": 730  // 2 years (GDPR)
    },
    "audio": {
      "retention_days": 2190  // 6 years (HIPAA)
    }
  }
}

コンプライアンスに関する推奨事項：

GDPR：データ処理の目的に合わせます（通常 1～2 年）
HIPAA：医療記録は最低 6 年間保持します
SOC 2：転送中および保存時の暗号化（自動）

暗号化

転送中：TLS 1.3
保存時：AES-256
地域コンプライアンス：データの保存場所（米国、EU、インド）

地域の設定：

const { startConversation } = useConversation({
  serverLocation: 'eu-residency' // 'us' | 'global' | 'eu-residency' | 'in-residency'
});

ゼロ保持モード

プライバシーを最大限に保護するには、ゼロ保持を有効にして、すべての会話データを直ちに削除します。

制限事項：

会話履歴なし
分析なし
通話後の Webhook なし
MCP ツール連携なし

10. コストの最適化

LLM キャッシュ

繰り返し送信される入力をキャッシュして、コストを削減します。

仕組み：

初回リクエスト：全額（input_cache_write）
2 回目以降のリクエスト：割引料金（input_cache_read）
TTL 経過後にキャッシュを自動的に無効化

設定：

{
  "llm_config": {
    "caching": {
      "enabled": true,
      "ttl_seconds": 3600  // 1 hour
    }
  }
}

ユースケース：

繰り返し使うシステムプロンプト
大規模なナレッジベース
頻繁に使用するツール定義

削減額：キャッシュされた入力で最大 90％

モデルの切り替え

コストとパフォーマンスのニーズに応じてモデルを切り替えます。

利用可能なモデル：

GPT-4o（高コスト、高品質）
GPT-4o-mini（中コスト、良質）
Claude Sonnet 4.5（高コスト、最高の推論能力）
Gemini 2.5 Flash（低コスト、高速）

設定：

{
  "llm_config": {
    "model": "gpt-4o-mini"  // Swap anytime via dashboard or API
  }
}

バースト料金

需要の高い期間中に、一時的に同時実行数の上限を超過できます。

仕組み：

通常：サブスクリプションの同時実行数上限（例：同時通話 10 件）
バースト：上限の最大 3 倍（例：同時通話 30 件）
コスト：バースト通話には標準料金の 2 倍がかかります

設定：

{
  "call_limits": {
    "burst_pricing_enabled": true
  }
}

ユースケース：

ブラックフライデーのトラフィック急増
製品の発売
季節的な需要（祝日）

注意事項：

バースト通話の料金は 2 倍です（計画的に利用してください）
無制限ではありません（上限は 3 倍）

11. 高度な機能

イベント（WebSocket/SSE）

ライブ文字起こし、エージェントの応答、ツール呼び出しのリアルタイムイベントストリーミングです。

イベントの種類：

audio - 音声ストリームのチャンク
transcript - リアルタイム文字起こし
agent_response - エージェントのテキスト応答
tool_call - ツールの実行ステータス
conversation_state - 状態の更新

例：

const { startConversation } = useConversation({
  onEvent: (event) => {
    switch (event.type) {
      case 'transcript':
        console.log('User said:', event.data.text);
        break;
      case 'agent_response':
        console.log('Agent replied:', event.data.text);
        break;
      case 'tool_call':
        console.log('Tool called:', event.data.tool_name);
        break;
    }
  }
});

カスタムモデル（独自の LLM を使用）

独自の OpenAI API キーまたはカスタム LLM サーバーを使用します。

設定：

{
  "llm_config": {
    "custom": {
      "endpoint": "https://api.openai.com/v1/chat/completions",
      "api_key": "{{secret__openai_api_key}}",
      "model": "gpt-4"
    }
  }
}

ユースケース：

カスタムのファインチューニング済みモデル
プライベートな LLM のデプロイ（Ollama、LocalAI）
コスト管理（独自のクレジットを使用）
コンプライアンス（オンプレミスのモデル）

注意事項：

エンドポイントは OpenAI 互換である必要があります
OpenAI 互換ではないモデルは公式サポート対象外です

通話後の Webhook

通話が終了し、分析が完了した際に通知を受け取ります。

設定：

{
  "webhooks": {
    "post_call": {
      "url": "https://api.example.com/webhook",
      "headers": {
        "Authorization": "Bearer {{secret__webhook_auth_token}}"
      }
    }
  }
}

ペイロード：

{
  "conversation_id": "conv_123",
  "agent_id": "agent_456",
  "transcript": "...",
  "duration_seconds": 120,
  "analysis": {
    "sentiment": "positive",
    "resolution": true,
    "extracted_data": {
      "customer_name": "John Doe",
      "issue_type": "billing"
    }
  }
}

セキュリティ（HMAC 検証）：

import crypto from 'crypto';

export async function POST(req: Request) {
  const signature = req.headers.get('elevenlabs-signature');
  const payload = await req.text();

  const hmac = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET!)
    .update(payload)
    .digest('hex');

  if (signature !== hmac) {
    return new Response('Invalid signature', { status: 401 });
  }

  // Process webhook
  const data = JSON.parse(payload);
  console.log('Conversation ended:', data.conversation_id);

  // MUST return 200
  return new Response('OK', { status: 200 });
}

注意事項：

200 ステータスコードを返す必要があります
10 回連続で失敗すると自動的に無効になります（最後の成功から 7 日以上経過した場合）
再試行ロジック：指数バックオフで 3 回試行

チャットモード（テキストのみ）

音声を無効にして、テキストのみの会話を使用します。

設定：

{
  "conversation_config": {
    "chat_mode": true  // Disables audio input/output
  }
}

メリット：

応答時間の短縮（約 200 ms）
コストの削減（ASR/TTS の料金なし）
テストが容易（マイク不要）

ユースケース：

音声なしでエージェントをテストする
テキストチャットインターフェースを構築する
アクセシビリティ（テキストのみを利用するユーザー）

テレフォニー連携

SIP トランキング：

SIP Endpoint: sip-static.rtc.elevenlabs.io
TLS Transport: Recommended for production
SRTP Encryption: Supported

対応プロバイダー：Twilio、Vonage、RingCentral、Sinch、Infobip、Telnyx、Exotel、Plivo、Bandwidth

Twilio ネイティブ連携：

{
  "telephony": {
    "provider": "twilio",
    "phone_number": "+1234567890",
    "account_sid": "{{secret__twilio_account_sid}}",
    "auth_token": "{{secret__twilio_auth_token}}"
  }
}

ユースケース：

カスタマーサポートのホットライン
予約のスケジュール設定
注文状況の問い合わせ
IVR システム

12. CLI と DevOps（「エージェントをコードとして管理」）

インストールと認証

# Install globally
npm install -g @elevenlabs/cli

# Authenticate
elevenlabs auth login

# Set residency (for GDPR compliance)
elevenlabs auth residency eu-residency  # or 'in-residency' | 'global'

# Check current user
elevenlabs auth whoami

環境変数（CI/CD 用）：

export ELEVENLABS_API_KEY=your-api-key

プロジェクト構造

プロジェクトの初期化：

elevenlabs agents init

作成されるディレクトリ構造：

your_project/
├── agents.json              # Agent registry
├── tools.json               # Tool configurations
├── tests.json               # Test configurations
├── agent_configs/           # Individual agent files (.json)
├── tool_configs/            # Tool configuration files
└── test_configs/            # Test configuration files

エージェント管理コマンド

# Create agent
elevenlabs agents add "Support Agent" --template customer-service

# Deploy to platform
elevenlabs agents push
elevenlabs agents push --agent "Support Agent"
elevenlabs agents push --env prod
elevenlabs agents push --dry-run  # Preview changes

# Import existing agents
elevenlabs agents pull

# List agents
elevenlabs agents list

# Check sync status
elevenlabs agents status

# Delete agent
elevenlabs agents delete <agent_id>

ツール管理コマンド

# Create webhook tool
elevenlabs tools add-webhook "Get Weather" --config-path tool_configs/get-weather.json

# Create client tool
elevenlabs tools add-client "Update Cart" --config-path tool_configs/update-cart.json

# Deploy tools
elevenlabs tools push

# Import existing tools
elevenlabs tools pull

# Delete tools
elevenlabs tools delete <tool_id>
elevenlabs tools delete --all

テストコマンド

# Create test
elevenlabs tests add "Refund Test" --template basic-llm

# Deploy tests
elevenlabs tests push

# Import tests
elevenlabs tests pull

# Run test
elevenlabs agents test "Support Agent"

複数環境へのデプロイ

パターン：

# Development
elevenlabs agents push --env dev

# Staging
elevenlabs agents push --env staging

# Production (with confirmation)
elevenlabs agents push --env prod --dry-run
# Review changes...
elevenlabs agents push --env prod

環境別の設定：

agent_configs/
├── support-bot.json          # Base config
├── support-bot.dev.json      # Dev overrides
├── support-bot.staging.json  # Staging overrides
└── support-bot.prod.json     # Prod overrides

CI/CD 統合

GitHub Actions の例：

name: Deploy Agent
on:
  push:
    branches: [main]
    paths:
      - 'agent_configs/**'
      - 'tool_configs/**'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install CLI
        run: npm install -g @elevenlabs/cli

      - name: Test Configs
        run: elevenlabs agents push --dry-run --env prod
        env:
          ELEVENLABS_API_KEY: ${{ secrets.ELEVENLABS_API_KEY_PROD }}

      - name: Deploy
        run: elevenlabs agents push --env prod
        env:
          ELEVENLABS_API_KEY: ${{ secrets.ELEVENLABS_API_KEY_PROD }}

バージョン管理のベストプラクティス

コミット対象：

agent_configs/*.json
tool_configs/*.json
test_configs/*.json
agents.json、tools.json、tests.json

無視対象：

# .gitignore
.env
.elevenlabs/
*.secret.json

13. よくあるエラーと解決策

エラー 1：必須の動的変数が不足している

症状："Missing required dynamic variables" エラーが発生し、トランスクリプトが生成されない

原因：プロンプトやメッセージ内で参照されている動的変数が、会話の開始時に指定されていません

解決策：

const conversation = await client.conversations.create({
  agent_id: "agent_123",
  dynamic_variables: {
    user_name: "John",
    account_tier: "premium",
    // Provide ALL variables referenced in prompts
  }
});

エラー 2：ツール名の大文字と小文字が区別される

症状：ツールが実行されず、エージェントが「ツールが見つかりません」と応答する

原因：設定内のツール名が登録名と一致していません（大文字と小文字が区別されます）

解決策：

// agent_configs/bot.json
{
  "agent": {
    "prompt": {
      "tool_ids": ["orderLookup"]  // Must match exactly
    }
  }
}

// tool_configs/order-lookup.json
{
  "name": "orderLookup"  // Match case exactly
}

エラー 3：Webhook 認証の失敗

症状：失敗が続いた後、Webhook が自動的に無効になる

原因：

HMAC 署名の検証が正しくありません
200 ステータスコードを返していません
10 回以上連続して失敗しています

解決策：

// Always verify HMAC signature
import crypto from 'crypto';

const signature = req.headers['elevenlabs-signature'];
const payload = JSON.stringify(req.body);

const hmac = crypto
  .createHmac('sha256', process.env.WEBHOOK_SECRET)
  .update(payload)
  .digest('hex');

if (signature !== hmac) {
  return res.status(401).json({ error: 'Invalid signature' });
}

// Process webhook
// ...

// MUST return 200
res.status(200).json({ success: true });

エラー 4：音声の一貫性に関する問題

症状：生成される音声の音量やトーンにばらつきがある

原因：

音声クローンのトレーニングデータに背景ノイズが含まれています
マイクとの距離が一定ではありません
サンプルにささやき声や大声が含まれています

解決策：

ノイズやポップノイズ、音楽がない、クリアな音声サンプルを使用します
マイクとの距離を一定に保ちます
極端な音量は避けます
デプロイ前に音声設定をテストします

エラー 5：音声の言語が違う

症状：発音が不安定で、アクセントに問題がある

原因：英語でトレーニングされた音声を英語以外の言語に使用しています

解決策：

{
  "language_presets": [
    {
      "language": "es",
      "voice_id": "spanish_trained_voice_id"  // Must be Spanish-trained
    }
  ]
}

エラー 6：制限付き API キーがサポートされない（CLI）

症状：CLI の認証に失敗する

原因：制限付き API キーを使用しています（現在はサポートされていません）

解決策：CLI 操作には制限のない API キーを使用します

エラー 7：エージェント設定のプッシュ時に競合が発生する

症状：プッシュ後も変更が反映されない

原因：ハッシュベースの変更検出で変更が検出されませんでした

解決策：

# Force re-sync
elevenlabs agents init --override
elevenlabs agents pull  # Re-import from platform
# Make changes
elevenlabs agents push

エラー 8：ツールのパラメーターとスキーマが一致しない

症状：ツールは呼び出されるものの、パラメーターが空、または正しくない

原因：スキーマの定義が実際の使用方法と一致していません

解決策：

// tool_configs/order-lookup.json
{
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "The order ID to look up (format: ORD-12345)"  // Clear description
      }
    },
    "required": ["order_id"]
  }
}

エラー 9：RAG インデックスの準備ができていない

症状：エージェントがナレッジベースを使用しない

原因：RAG インデックスの計算中です（大きなドキュメントでは数分かかる場合があります）

解決策：

// Check index status before using
const index = await client.knowledgeBase.getRagIndex({
  document_id: 'doc_123'
});

if (index.status !== 'ready') {
  console.log('Index still computing...');
}

エラー 10：WebSocket プロトコルエラー（1002）

症状：WebSocket 接続の使用中に「プロトコルエラー」が断続的に発生する

原因：ネットワークが不安定、またはブラウザーに互換性がありません

解決策：

WebSocket の代わりに WebRTC を使用します（より安定しています）
再接続ロジックを実装します
ブラウザーの互換性を確認します

エラー 11：本番環境で 401 Unauthorized が発生する

症状：ローカルでは動作するものの、本番環境では失敗する

原因：エージェントの公開設定、または API キーの設定に問題があります

解決策：

エージェントの公開設定（公開または非公開）を確認します
本番環境に API キーが設定されていることを確認します
有効になっている場合は、許可リストの設定を確認します

エラー 12：許可リストの接続エラー

症状：「Host elevenlabs.io is not allowed to connect to this agent」

原因：エージェントで許可リストが有効になっているものの、共有リンクを使用しています

解決策：

エージェントの許可リストに正しいドメインを設定します
または、テスト時には許可リストを無効にします

エラー 13：ワークフローが無限ループする

症状：エージェントがワークフローで停止し、完了しない

原因：エッジ条件によってループが発生しています

解決策：

最大反復回数を設定します
すべてのエッジパスをテストします
明示的な終了条件を追加します

エラー 14：バースト料金が有効になっていない

症状：トラフィック急増時に通話が拒否される

原因：エージェント設定でバースト料金が有効になっていません

解決策：

{
  "call_limits": {
    "burst_pricing_enabled": true
  }
}

エラー 15：MCP サーバーのタイムアウト

症状：MCP ツールが応答しない

原因：MCP サーバーの動作が遅い、または到達できない

解決策：

MCP サーバーの URL にアクセスできることを確認します
トランスポートの種類（SSE または HTTP）を確認します
認証トークンを確認します
MCP サーバーのログを監視します

エラー 16：Android で最初のメッセージが途切れる

症状：Android デバイスでエージェントからの最初のメッセージが途切れます（iOS／Web では正常に動作します）

原因：Android デバイスでは、接続後に正しいオーディオモードへ切り替えるための時間が必要です

解決策：

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

const { startConversation } = useConversation({
  agentId: 'your-agent-id',

  // Add connection delay for Android
  connectionDelay: {
    android: 3_000,  // 3 seconds (default)
    ios: 0,          // No delay needed
    default: 0       // Other platforms
  },

  // Rest of config...
});

説明：

Android ではオーディオのルーティングモードの切り替えに 3 秒かかります
遅延がないと、最初のオーディオチャンクが失われます
iOS と Web ではこの問題は発生しません
3 秒では不十分な場合は、遅延を調整します

テスト：

# Test on Android device
npm run android

# First message should now be complete

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

症状：ブラウザーのコンソールに「Refused to load the script because it violates the following Content Security Policy directive」エラーが表示されます

原因：厳格なコンテンツセキュリティポリシーを適用しているアプリケーションでは、script-src ディレクティブで data: または blob: URL が許可されていません。ElevenLabs SDK は、デフォルトで blob として読み込まれる Audio Worklets を使用します。

解決策 - Worklet ファイルをセルフホストする：

手順 1：Worklet ファイルを公開ディレクトリにコピーします。

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

手順 2：セルフホストされた Worklet を使用するよう SDK を設定します。

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

const { startConversation } = useConversation({
  agentId: 'your-agent-id',

  // Point to self-hosted worklet files
  workletPaths: {
    'rawAudioProcessor': '/elevenlabs/rawAudioProcessor.worklet.js',
    'audioConcatProcessor': '/elevenlabs/audioConcatProcessor.worklet.js',
  },

  // Rest of config...
});

手順 3：セルフホストされたスクリプトを許可するよう CSP ヘッダーを更新します。

# nginx example
add_header Content-Security-Policy "
  default-src 'self';
  script-src 'self' https://elevenlabs.io;
  connect-src 'self' https://api.elevenlabs.io wss://api.elevenlabs.io;
  worker-src 'self';
" always;

Worklet ファイルの場所：

node_modules/@elevenlabs/client/dist/worklets/
├── rawAudioProcessor.worklet.js
└── audioConcatProcessor.worklet.js

注意点：

Worklet ファイルは同一オリジンから配信する必要があります（CORS の制限）
@elevenlabs/client のアップグレード時に Worklet ファイルを更新してください
パスは完全に一致させる必要があります（大文字と小文字を区別します）

必要となるケース：

CSP が厳格なエンタープライズアプリケーション
政府機関／金融関連のアプリ
セキュリティ監査を受けるアプリ
blob: URL をブロックするすべてのアプリ

既存のスキルとの連携

このスキルは、以下のスキルとうまく連携します。

cloudflare-worker-base → Cloudflare Workers のエッジネットワークにエージェントをデプロイします
cloudflare-workers-ai → Cloudflare LLM をエージェントのカスタムモデルとして使用します
cloudflare-durable-objects → 会話状態とセッション管理を永続化します
cloudflare-kv → エージェントの設定とユーザー設定をキャッシュします
nextjs → Next.js アプリケーションに React SDK を統合します
ai-sdk-core → Vercel AI SDK プロバイダーで統一された AI インターフェイスを実現します
clerk-auth → ユーザー ID を用いた認証済み音声セッションを実現します
hono-routing → Webhook とサーバーツール用の API ルートを設定します

追加リソース

公式ドキュメント：

プラットフォームの概要：https://elevenlabs.io/docs/agents-platform/overview
API リファレンス：https://elevenlabs.io/docs/api-reference
CLI GitHub：https://github.com/elevenlabs/cli

例：

公式サンプル：https://github.com/elevenlabs/elevenlabs-examples
MCP サーバー：https://github.com/elevenlabs/elevenlabs-mcp

コミュニティ：

Discord：https://discord.com/invite/elevenlabs
Twitter：@elevenlabsio

本番環境でのテスト済み：WordPress Auditor、Customer Support Agents 最終更新日：2025-11-03 パッケージのバージョン：[email protected]、@elevenlabs/[email protected]

Markdown 対応

ログインしてコメント

基本情報

作者: jackspace
リポジトリ: jackspace/claudeskillz
カテゴリ: エージェントワークフロー
インストール数: 41
GitHub スター: 16

問題を報告

elevenlabs-agents

elevenlabs-agents について

主な機能

活用シーン

MCP 対応

インストール

詳細

ElevenLabs Agents Platform

概要

🚨 パッケージの更新（2025 年 11 月）

このスキルを使用する場面

プラットフォームの機能

1. クイックスタート（3 つの統合方法）

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

方法 B：CLI（「コードとしてのエージェント」）

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

2. エージェントの設定

システムプロンプトの構成（6 コンポーネント）

1. パーソナリティ

2. 環境

3. トーン

4. 目標

5. ガードレール

6. ツール

ターンテイクモード

ワークフロー（ビジュアルビルダー）

動的変数とパーソナライズ

認証パターン

3. 音声と言語の機能

複数音声のサポート

発音辞書

速度制御

音声の設計

言語設定

4. ナレッジベースと RAG

RAG（検索拡張生成）

5. ツール（4種類）

A. クライアントツール

B. サーバーツール（Webhook）

C. MCP ツール（Model Context Protocol）

D. システムツール

6. SDK の統合

React SDK（@elevenlabs/react）

JavaScript SDK（@elevenlabs/client）

接続タイプ：WebRTC と WebSocket

React Native SDK（Expo）

Swift SDK（iOS/macOS）

ウィジェット（埋め込み可能な Web コンポーネント）

Scribe（リアルタイム音声テキスト変換）

7. テストと評価

シナリオテスト（LLM ベースの評価）

ツール呼び出しテスト

負荷テスト

シミュレーション API（プログラムによるテスト）

8. 分析とモニタリング

会話の分析

成功の評価（LLM ベース）

データ収集

Analytics Dashboard

9. プライバシーとコンプライアンス

データ保持

暗号化

ゼロ保持モード

10. コストの最適化

LLM キャッシュ

モデルの切り替え

バースト料金

11. 高度な機能

イベント（WebSocket/SSE）

カスタムモデル（独自の LLM を使用）

通話後の Webhook

チャットモード（テキストのみ）

テレフォニー連携

12. CLI と DevOps（「エージェントをコードとして管理」）

インストールと認証

プロジェクト構造

エージェント管理コマンド

ツール管理コマンド

テストコマンド

複数環境へのデプロイ

React SDK（`@elevenlabs/react`）

JavaScript SDK（`@elevenlabs/client`）