ElevenLabs Agent Builder

本番環境対応の会話型AI音声エージェントを構築します。ツール、ナレッジベース、SDKインテグレーションが設定されたエージェントを成果物として提供します。

パッケージ

npm install @elevenlabs/react           # React SDK
npm install @elevenlabs/client          # JavaScript SDK (ブラウザ + サーバー)
npm install @elevenlabs/react-native    # React Native SDK
npm install @elevenlabs/elevenlabs-js   # 完全 API (サーバーのみ)
npm install -g @elevenlabs/agents-cli   # CLI ("Agents as Code")

非推奨: @11labs/react, @11labs/client -- インストール済みの場合はアンインストールしてください。

サーバーのみの警告: @elevenlabs/elevenlabs-js は Node.js の child_process を使用するため、ブラウザでは動作しません。ブラウザ環境では @elevenlabs/client を使用するか、プロキシサーバーを作成してください。

ワークフロー

ステップ 1: ダッシュボードまたはCLIでエージェントを作成

ダッシュボード: https://elevenlabs.io/app/conversational-ai -> Create Agent

CLI (Agents as Code):

elevenlabs agents init
elevenlabs agents add "Support Bot" --template customer-service
# agent_configs/support-bot.json を編集
elevenlabs agents push --env dev

テンプレート: default, minimal, voice-only, text-only, customer-service, assistant。

設定項目:

• Voice -- 5000以上の声から選択するか、クローン作成
• LLM -- GPT、Claude、Gemini、またはカスタムモデル
• System prompt -- 下記の6コンポーネントフレームワークを使用
• First message -- 会話開始時にエージェントが発話する内容

ステップ 2: システムプロンプトを作成

効果的なエージェントプロンプトには6コンポーネントフレームワークを使用:

1. Personality (人格) -- エージェントの正体:

You are [NAME], a [ROLE] at [COMPANY].
You have [EXPERIENCE]. Your traits: [LIST TRAITS].

2. Environment (環境) -- 通信の文脈:

You're communicating via [phone/chat/video].
Consider [environmental factors]. Adapt to [context].

3. Tone (トーン) -- 音声パターンと丁寧さ:

Tone: Professional yet warm. Use contractions for natural speech.
Avoid jargon. Keep responses to 2-3 sentences. Ask one question at a time.

4. Goal (目標) -- 目的と成功基準:

Primary Goal: Resolve customer issues on the first call.
Success: Customer verbally confirms issue is resolved.

5. Guardrails (ガイドライン) -- 境界と倫理:

Never: provide medical/legal/financial advice, share confidential info.
Always: verify identity before account access, document interactions.
Escalation: customer requests manager, issue beyond knowledge base.

6. Tools (ツール) -- 利用可能な機能と使用タイミング:

1. lookup_order(order_id) -- 顧客が注文に言及したときに使用
2. transfer_to_supervisor() -- 問題がマネージャー承認を要するときに使用
Always explain what you're doing before calling a tool.

ステップ 3: ツールを追加

クライアント側ツール (ブラウザで実行):

const clientTools = {
  updateCart: {
    description: "ショッピングカートの商品を追加または削除",
    parameters: z.object({
      action: z.enum(['add', 'remove']),
      item: z.string(),
      quantity: z.number().min(1)
    }),
    handler: async ({ action, item, quantity }) => {
      const cart = getCart();
      action === 'add' ? cart.add(item, quantity) : cart.remove(item, quantity);
      return { success: true, total: cart.total, items: cart.items.length };
    }
  },
  navigate: {
    description: "ユーザーを別のページにナビゲート",
    parameters: z.object({ url: z.string().url() }),
    handler: async ({ url }) => { window.location.href = url; return { success: true }; }
  }
};

サーバー側ツール (Webhook):

{
  "name": "get_weather",
  "description": "都市の現在の天気を取得",
  "url": "https://api.weather.com/v1/current",
  "method": "GET",
  "parameters": {
    "type": "object",
    "properties": {
      "city": { "type": "string", "description": "都市名" }
    },
    "required": ["city"]
  },
  "headers": {
    "Authorization": "Bearer {{secret__weather_api_key}}"
  }
}

WebhookヘッダーのAPIキーには {{secret__key_name}} を使用してください -- ハードコーディングしないでください。

MCPツール -- 重要な互換性に関する注記:

ElevenLabsは彼らのMCPインテグレーションを「Streamable HTTP」と呼んでいますが、実際のMCP 2025-03-26 Streamable HTTPスペック (SSEレスポンス) には対応していません。ElevenLabsが期待するのは:

• プレーンJSONレスポンス (application/json)、SSEではない (text/event-stream)
• プロトコルバージョン 2024-11-05、2025-03-26 ではない
• ダイレクトJSONレスポンスによるシンプルなJSON-RPCオーバーHTTP

機能しないもの:

• 公式MCP SDKの createMcpHandler (SSEを返す)
• Cloudflare Agents SDK McpServer.serve() (SSEを返す)
• Content-Type: text/event-stream を返すサーバー

ElevenLabsで機能するMCPサーバーパターン:

import { Hono } from 'hono';
import { cors } from 'hono/cors';

const tools = [{
  name: "my_tool",
  description: "ツールの説明",
  inputSchema: {
    type: "object",
    properties: { param1: { type: "string", description: "説明" } },
    required: ["param1"]
  }
}];

async function handleMCPRequest(request, env) {
  const { id, method, params } = request;
  switch (method) {
    case 'initialize':
      return {
        jsonrpc: '2.0', id,
        result: {
          protocolVersion: '2024-11-05',  // 2024-11-05 である必要がある
          serverInfo: { name: 'my-mcp', version: '1.0.0' },
          capabilities: { tools: {} }
        }
      };
    case 'tools/list':
      return { jsonrpc: '2.0', id, result: { tools } };
    case 'tools/call':
      const result = await handleTool(params.name, params.arguments, env);
      return { jsonrpc: '2.0', id, result };
    default:
      return { jsonrpc: '2.0', id, error: { code: -32601, message: `Unknown: ${method}` } };
  }
}

const app = new Hono();
app.use('/*', cors({ origin: '*', allowMethods: ['GET', 'POST', 'OPTIONS'] }));
app.post('/mcp', async (c) => {
  const body = await c.req.json();
  return c.json(await handleMCPRequest(body, c.env));  // プレーンJSON、SSEではない
});
export default app;

ステップ 4: ナレッジベースを追加 (RAG)

エージェントが参照するドキュメントをアップロード:

• PDF、テキストファイル、Web URL
• ダッシュボードで設定: Agent -> Knowledge Base -> Upload
• または API: POST /v1/convai/knowledge-base/upload (multipart/form-data)
• エージェントが会話中に自動的にナレッジベースを検索

ステップ 5: SDKをインテグレート

React -- assets/react-sdk-boilerplate.tsx をコピーしてカスタマイズ:

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

const { startConversation, stopConversation, status } = useConversation({
  agentId: 'your-agent-id',
  signedUrl: '/api/elevenlabs/auth',
  clientTools,
  dynamicVariables: {
    user_name: 'John',
    account_type: 'premium',
  },
  onEvent: (event) => { /* transcript, agent_response, tool_call */ },
});

システムプロンプトは動的変数を {{user_name}} として参照します。

React Native -- assets/react-native-boilerplate.tsx を参照 ウィジェット埋め込み -- assets/widget-embed-template.html を参照 Swift -- assets/swift-sdk-boilerplate.swift を参照

ステップ 6: テスト

CLI テスト:

# エージェントのすべてのテストを実行
elevenlabs agents test "Support Agent"

# テストシナリオを追加
elevenlabs tests add "Refund Request" --template basic-llm

テスト設定:

{
  "name": "返金リクエストテスト",
  "scenario": "顧客が不具合のある商品の返金をリクエスト",
  "user_input": "注文 #12345 の返金を希望します。商品は破損して到着しました。",
  "success_criteria": [
    "エージェントが共感的に問題を認識",
    "エージェントが注文番号をリクエストまたは使用",
    "エージェントが注文詳細を確認",
    "エージェントが明確な次のステップまたは返金タイムラインを提供"
  ],
  "evaluation_type": "llm"
}

ツール呼び出しテスト:

{
  "name": "注文検索テスト",
  "scenario": "顧客が注文ステータスについて質問",
  "user_input": "注文 ORD-12345 のステータスは?",
  "expected_tool_call": {
    "tool_name": "lookup_order",
    "parameters": { "order_id": "ORD-12345" }
  }
}

APIシミュレーション:

const simulation = await client.agents.simulate({
  agent_id: 'agent_123',
  scenario: '顧客が返金をリクエスト',
  user_messages: [
    "注文 #12345 の返金を希望します",
    "破損して到着しました",
    "はい、返金を処理してください"
  ],
  success_criteria: [
    "エージェントが同情を示す",
    "エージェントが注文を確認",
    "エージェントがタイムラインを提供"
  ]
});
console.log('成功:', simulation.passed);

CI/CD インテグレーション:

name: Test Agent
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm install -g @elevenlabs/cli
      - run: elevenlabs tests push
        env:
          ELEVENLABS_API_KEY: ${{ secrets.ELEVENLABS_API_KEY }}
      - run: elevenlabs agents test "Support Agent"
        env:
          ELEVENLABS_API_KEY: ${{ secrets.ELEVENLABS_API_KEY }}

ステップ 7: デプロイ

# ドライランを実行 (常に最初に)
elevenlabs agents push --env prod --dry-run

# 本番環境にデプロイ
elevenlabs agents push --env prod

マルチ環境ワークフロー:

elevenlabs agents push --env dev       # 開発環境
elevenlabs agents push --env staging   # ステージング環境
elevenlabs agents test "Agent Name"    # ステージングでテスト
elevenlabs agents push --env prod      # 本番環境

---

重要なパターン

署名付きURL (セキュリティ)

APIキーをクライアントコードに公開しないでください。サーバーエンドポイントを使用:

app.get('/api/elevenlabs/auth', async (req, res) => {
  const response = await fetch(
    'https://api.elevenlabs.io/v1/convai/conversation/get-signed-url',
    {
      headers: { 'xi-api-key': process.env.ELEVENLABS_API_KEY },
      body: JSON.stringify({ agent_id: 'your-agent-id' }),
      method: 'POST'
    }
  );
  const { signed_url } = await response.json();
  res.json({ signed_url });
});

エージェントバージョン管理 (A/Bテスト)

ダッシュボード: Agent -> Versions -> Create Branch。メトリクスを比較し、勝者を昇格させます。

通話後 Webhook

{
  "type": "post_call_transcription",
  "data": {
    "conversation_id": "conv_xyz789",
    "transcript": "...",
    "duration_seconds": 120,
    "analysis": { "sentiment": "positive", "resolution": true }
  }
}

HMAC SHA-256で検証:

const hmac = crypto.createHmac('sha256', process.env.WEBHOOK_SECRET)
  .update(JSON.stringify(request.body)).digest('hex');
if (signature !== hmac) { /* reject */ }

---

コスト最適化

モデル	コスト/100万トークン	速度	最適用途
GPT-4o	$5	中	複雑な推論
GPT-4o-mini	$0.15	高速	ほとんどのユースケース
Claude Sonnet 4.5	$3	中	長いコンテキスト
Gemini 2.5 Flash	$0.075	最速	シンプルなタスク

すべてのエージェントで gpt-4o-mini から開始してください。品質が必要な場合のみアップグレードしてください。

主な節約方法:

• LLM キャッシング: 繰り返されるプロンプトで最大90%削減 (設定で有効化)
• プロンプト長: 同じ指示で500トークンより150トークン
• RAG vs コンテキスト: システムプロンプトに詰め込むよりナレッジベースを使用
• 期間制限: max_duration_seconds を設定して無限会話を防止
• ターンモード: 「patient」モードで LLM呼び出しが少なくなり、コストが低下

---

CLI クイックリファレンス

elevenlabs auth login                              # 認証
elevenlabs agents init                             # プロジェクト初期化
elevenlabs agents add "Name" --template default    # エージェント追加
elevenlabs agents push --env dev                   # 開発環境にデプロイ
elevenlabs agents push --env prod --dry-run        # 本番環境デプロイプレビュー
elevenlabs agents push --env prod                  # 本番環境にデプロイ
elevenlabs agents pull                             # プラットフォームから取得
elevenlabs agents test "Name"                      # テストを実行
elevenlabs agents list                             # エージェント一覧
elevenlabs agents status                           # 同期ステータスを確認
elevenlabs agents widget "Name"                    # ウィジェットを生成
elevenlabs tools add-webhook "Name" --config-path tool.json  # ツール追加
elevenlabs tests add "Name" --template basic-llm   # テスト追加

環境変数: CI/CDに ELEVENLABS_API_KEY。

---

オプショナルリファレンス

専門的なユースケースについては、以下を参照:

• references/api-reference.md -- プログラムによるエージェント管理用の完全 REST API
• references/compliance-guide.md -- GDPR、HIPAA、PCI DSS、データレジデンシ
• references/workflow-examples.md -- マルチエージェントルーティング、エスカレーション、多言語対応

---

アセットファイル

• assets/react-sdk-boilerplate.tsx -- React インテグレーションテンプレート
• assets/react-native-boilerplate.tsx -- React Native テンプレート
• assets/swift-sdk-boilerplate.swift -- Swift/iOS テンプレート
• assets/javascript-sdk-boilerplate.js -- Vanilla JS テンプレート
• assets/widget-embed-template.html -- 埋め込み可能なウィジェット
• assets/system-prompt-template.md -- システムプロンプトガイド
• assets/agent-config-schema.json -- 設定スキーマリファレンス
• assets/ci-cd-example.yml -- CI/CD パイプラインテンプレート