elevenlabs-agents

ElevenLabs エージェントビルダー

本番環境に対応した会話型 AI 音声エージェントを構築します。ツール、ナレッジベース、SDK 統合を設定したエージェントを生成します。

パッケージ

npm install @elevenlabs/react           # React SDK
npm install @elevenlabs/client          # JavaScript SDK (browser + server)
npm install @elevenlabs/react-native    # React Native SDK
npm install @elevenlabs/elevenlabs-js   # Full API (server only)
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 -> エージェントを作成

CLI（Agents as Code）：

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

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

設定項目：

• 音声 — 5000 種類以上の音声から選択するか、クローンを作成します
• LLM — GPT、Claude、Gemini、またはカスタム
• システムプロンプト — 以下の 6 要素フレームワークを使用します
• 最初のメッセージ — 会話開始時にエージェントが話す内容

ステップ 2：システムプロンプトを作成する

効果的なエージェントプロンプトには、6 要素フレームワークを使用します。

1. パーソナリティ — エージェントの人物像：

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

2. 環境 — コミュニケーションの文脈：

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

3. トーン — 話し方とフォーマルさ：

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

4. 目標 — 目的と成功基準：

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

5. ガードレール — 境界と倫理：

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. ツール — 利用可能な関数とその使用タイミング：

1. lookup_order(order_id) -- Use when customer mentions an order.
2. transfer_to_supervisor() -- Use when issue requires manager approval.
Always explain what you're doing before calling a tool.

ステップ 3：ツールを追加する

クライアント側ツール（ブラウザーで実行）：

const clientTools = {
  updateCart: {
    description: "Add or remove items from the shopping cart",
    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: "Navigate user to a different page",
    parameters: z.object({ url: z.string().url() }),
    handler: async ({ url }) => { window.location.href = url; return { success: true }; }
  }
};

サーバー側ツール（Webhook）：

{
  "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": "City name" }
    },
    "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 ではありません
• HTTP 経由のシンプルな JSON-RPC と、直接返される JSON 応答

動作しないもの：

• 公式 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: "Tool description",
  inputSchema: {
    type: "object",
    properties: { param1: { type: "string", description: "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',  // MUST be 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));  // Plain JSON, NOT SSE
});
export default app;

ステップ 4：ナレッジベースを追加する（RAG）

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

• PDF、テキストファイル、Web URL
• ダッシュボードで設定：エージェント -> ナレッジベース -> アップロード
• または 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 でのテスト：

# Run all tests for an agent
elevenlabs agents test "Support Agent"

# Add a test scenario
elevenlabs tests add "Refund Request" --template basic-llm

設定のテスト：

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

ツール呼び出しのテスト：

{
  "name": "Order Lookup Test",
  "scenario": "Customer asks about order status",
  "user_input": "What's the status of order 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: 'Customer requests refund',
  user_messages: [
    "I want a refund for order #12345",
    "It arrived broken",
    "Yes, process the refund"
  ],
  success_criteria: [
    "Agent shows empathy",
    "Agent verifies order",
    "Agent provides timeline"
  ]
});
console.log('Passed:', 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：デプロイする

# Dry run first (always)
elevenlabs agents push --env prod --dry-run

# Deploy to production
elevenlabs agents push --env prod

複数環境のワークフロー：

elevenlabs agents push --env dev       # Development
elevenlabs agents push --env staging   # Staging
elevenlabs agents test "Agent Name"    # Test in staging
elevenlabs agents push --env prod      # Production

---

重要なパターン

署名付き 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 テスト）

ダッシュボード：エージェント -> バージョン -> ブランチを作成。指標を比較し、優れた方を昇格させます。

通話後の 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 */ }

---

コストの最適化

モデルのラインアップや料金は頻繁に変わるため、選択する前に ElevenLabs ダッシュボード（Agent → LLM ドロップダウン）またはドキュメントで最新の一覧を確認し、このセッションで確認していないモデル ID をハードコードしないでください。長期的に有効な選択肢は、ほとんどのエージェントで現在の低コストかつ高速なモデルを使い（品質が必要な場合にのみアップグレードする）、ナレッジベースが大きい場合は長いコンテキストに対応するモデルを使うことです。

主なコスト削減策：

• LLM キャッシュ：繰り返しのプロンプトで最大 90％削減できます（設定で有効にします）
• プロンプトの長さ：同じ指示なら、500 トークンより 150 トークンにします
• コンテキストより RAG：システムプロンプトに詰め込む代わりに、ナレッジベースを使います
• 時間制限：max_duration_seconds を設定して、会話が際限なく続くのを防ぎます
• ターンモード：「patient」モードでは LLM の呼び出し回数が減り、コストを抑えられます

---

CLI クイックリファレンス

elevenlabs auth login                              # Authenticate
elevenlabs agents init                             # Init project
elevenlabs agents add "Name" --template default    # Add agent
elevenlabs agents push --env dev                   # Deploy to dev
elevenlabs agents push --env prod --dry-run        # Preview prod deploy
elevenlabs agents push --env prod                  # Deploy to prod
elevenlabs agents pull                             # Pull from platform
elevenlabs agents test "Name"                      # Run tests
elevenlabs agents list                             # List agents
elevenlabs agents status                           # Check sync status
elevenlabs agents widget "Name"                    # Generate widget
elevenlabs tools add-webhook "Name" --config-path tool.json  # Add tool
elevenlabs tests add "Name" --template basic-llm   # Add test

環境変数：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 パイプラインテンプレート