ElevenLabs Agents Platform

自然な会話、複数のLLMプロバイダー、カスタムツール、簡単なウェブ埋め込みで音声AIエージェントを構築します。

セットアップ: CLI とSDKセットアップについては Installation Guide を参照してください。

CLIを使用したクイックスタート

ElevenLabs CLIはエージェントを作成・管理するための推奨方法です:

# CLIをインストール認証
npm install -g @elevenlabs/cli
elevenlabs auth login

# プロジェクトを初期化してエージェントを作成
elevenlabs agents init
elevenlabs agents add "My Assistant" --template complete

# ElevenLabsプラットフォームにプッシュ
elevenlabs agents push

利用可能なテンプレート: complete, minimal, voice-only, text-only, customer-service, assistant

Python

from elevenlabs import ElevenLabs

client = ElevenLabs()

agent = client.conversational_ai.agents.create(
    name="My Assistant",
    enable_versioning=True,
    conversation_config={
        "agent": {
            "first_message": "Hello! How can I help?",
            "language": "en",
            "prompt": {
                "prompt": "You are a helpful assistant. Be concise and friendly.",
                "llm": "gemini-2.0-flash",
                "temperature": 0.7
            }
        },
        "tts": {"voice_id": "JBFqnCBsd6RMkjVDRZzb"}
    }
)

JavaScript

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
const client = new ElevenLabsClient();

const agent = await client.conversationalAi.agents.create({
  name: "My Assistant",
  enableVersioning: true,
  conversationConfig: {
    agent: {
      firstMessage: "Hello! How can I help?",
      language: "en",
      prompt: {
        prompt: "You are a helpful assistant.",
        llm: "gemini-2.0-flash",
        temperature: 0.7
      }
    },
    tts: { voiceId: "JBFqnCBsd6RMkjVDRZzb" }
  }
});

cURL

curl -X POST "https://api.elevenlabs.io/v1/convai/agents/create?enable_versioning=true" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "My Assistant", "conversation_config": {"agent": {"first_message": "Hello!", "language": "en", "prompt": {"prompt": "You are helpful.", "llm": "gemini-2.0-flash"}}, "tts": {"voice_id": "JBFqnCBsd6RMkjVDRZzb"}}}'

会話の開始

一時的なLiveKit WebSocketピン

ElevenLabs LiveKitサーバーが /rtc/v1 をサポートするまで、WebRTCを使用するブラウザクライアントは、livekit-client バージョン 2.16.1 より新しいバージョンで、基盤となるLiveKit WebSocketハンドシェイク中に失敗またはスタールすることがあります。React、Next.js、Electron、または @elevenlabs/client / @elevenlabs/react を使用する他の統合で、connectionType: "webrtc" を使用するか、wss://livekit.rtc.elevenlabs.io/rtc/v1 にアクセスする場合は、package.json に次の一時ピンを追加してください:

{
  "overrides": {
    "livekit-client": "2.16.1"
  }
}

アプリが /rtc/v1 404s、v1 RTC path not found、またはセッション起動時に could not establish pc connection をログに出力するときにピンを使用してください。これはWebRTCセッション用のLiveKitサーバー互換性回避策であり、ElevenLabs connectionType: "websocket" トランスポートではありません。アップストリームのLiveKitサーバーまたはSDKの問題が修正されたら削除してください。

サーバー側(Python): クライアント接続用の署名付きURLを取得:

signed_url = client.conversational_ai.conversations.get_signed_url(
    agent_id="your-agent-id",
    environment="staging",
)

クライアント側(JavaScript):

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

const conversation = await Conversation.startSession({
  agentId: "your-agent-id",
  environment: "staging",
  onMessage: (msg) => console.log("Agent:", msg.message),
  onUserTranscript: (t) => console.log("User:", t.message),
  onError: (e) => console.error(e)
});

React Hook: フック使用者を ConversationProvider で囲みます。セッション制御とUIの状態については、useConversationControls や useConversationStatus などの細粒度フックを優先します。useConversation は依然として利用可能な便宜的なオールインワンフックです。Reactが会話エラーを1か所で処理するようにする場合は、onError などのプロバイダーレベルのコールバックを渡します。

import {
  ConversationProvider,
  useConversationControls,
  useConversationStatus,
} from "@elevenlabs/react";

function Agent({ signedUrl }: { signedUrl: string }) {
  const { startSession, endSession } = useConversationControls();
  const { status } = useConversationStatus();

  if (status === "connected") {
    return <button onClick={endSession}>End conversation</button>;
  }

  return (
    <button onClick={() => startSession({ signedUrl })}>
      Start conversation
    </button>
  );
}

function App({ signedUrl }: { signedUrl: string }) {
  return (
    <ConversationProvider
      onError={(error) => console.error("Conversation error:", error)}
    >
      <Agent signedUrl={signedUrl} />
    </ConversationProvider>
  );
}

設定

プロバイダー	モデル
OpenAI	gpt-5.5, gpt-5.5-2026-04-23, gpt-5.4, gpt-5.4-mini, gpt-5.4-nano, gpt-5.4-2026-03-05, gpt-5.4-mini-2026-03-17, gpt-5.4-nano-2026-03-17, gpt-5, gpt-5-mini, gpt-5-nano, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, gpt-4o, gpt-4o-mini, gpt-4-turbo
Anthropic	claude-opus-4-7, claude-sonnet-4-6, claude-sonnet-4-5, claude-sonnet-4, claude-haiku-4-5, claude-3-7-sonnet, claude-3-5-sonnet, claude-3-haiku
Google	gemini-3.1-flash-lite-preview, gemini-3.1-pro-preview, gemini-3-pro-preview, gemini-3-flash-preview, gemini-2.5-flash, gemini-2.5-flash-lite, gemini-2.0-flash, gemini-2.0-flash-lite
ElevenLabs	glm-45-air-fp8, qwen3-30b-a3b, qwen36-35b-a3b, qwen35-35b-a3b, qwen35-397b-a17b, gpt-oss-120b
カスタム	custom-llm (独自エンドポイントを持ち込み)

GET /v1/convai/llm/list を使用して現在のモデルカタログを検査してください。非推奨状態、トークン/コンテキスト制限、画像入力サポートなどの機能フラグ、モデル固有の推論努力サポートを含みます。

人気のある音声: JBFqnCBsd6RMkjVDRZzb (George), EXAVITQu4vr4xnSDxMaL (Sarah), onwK4e9ZLuTAKqWW03F9 (Daniel), XB0fDUnXU5powFXDhCwa (Charlotte)

ターン熱心さ: patient (ユーザーが終了するのを待つ), normal, または eager (素早く応答)

すべてのオプションについては Agent Configuration を参照してください。

システムプロンプト構造

プロンプトをMarkdownの見出しでセクション化してください。モデルはより確実に指示を優先して解釈します(プロンプティングガイド):

# Personality   – 名前付きキャラクター、2-3の特性
# Environment   – 働く場所、話しかける人
# Tone          – 4-5個の項目として示した音声スタイル
# Goal          – 成功がどのようなものかを表示(マルチステップフロー用に番号付け)

指示は短く、アクション指向に保ちます。重要なステップに「This step is important.」というマークを付けます。重要な拒否/安全ルールについては、プロンプトに簡潔な指示を含め、platform_settings.guardrails で独立したカスタムガードレールも設定します(Guardrailsを参照)。

ツール

Webhook、クライアント、または組み込みシステムツールでエージェントを拡張します。ツールは conversation_config.agent.prompt 内で定義されます:

ワークスペース環境変数は環境ごとのサーバーツールURL、ヘッダー、認証接続を解決できます。実行時システム変数(例:{{system__conversation_history}})は必要に応じて完全な会話コンテキストをツール呼び出しに渡すことができます。

"prompt": {
    "prompt": "You are a helpful assistant that can check the weather.",
    "llm": "gemini-2.0-flash",
    "tools": [
        # Webhook: サーバー側APIコール
        {"type": "webhook", "name": "get_weather", "description": "Get weather",
         "api_schema": {"url": "https://api.example.com/weather", "method": "POST",
             "request_body_schema": {"type": "object", "properties": {"location": {"type": "string"}}, "required": ["location"]}}},
        # Client: ブラウザで実行
        {"type": "client", "name": "show_product", "description": "Display a product",
         "parameters": {"type": "object", "properties": {"productId": {"type": "string"}}, "required": ["productId"]}}
    ],
    "built_in_tools": {
        "end_call": {},
        "transfer_to_number": {"transfers": [{"transfer_destination": {"type": "phone", "phone_number": "+1234567890"}, "condition": "User asks for human support"}]}
    }
}

クライアントツールはブラウザで実行されます:

clientTools: {
  show_product: async ({ productId }) => {
    document.getElementById("product").src = `/products/${productId}`;
    return { success: true };
  }
}

完全なドキュメントについては Client Tools Reference を参照してください。

組み込みシステムツール

conversation_config.agent.prompt.built_in_tools の下に設定します。{} はデフォルトを有効にします。description を指定してカスタマイズします。省略して無効にします。

ツール	対象
end_call	すべてのエージェント
language_detection	多言語エージェント
transfer_to_number	電話ベースの人間へのエスカレーション
transfer_to_agent	マルチエージェントワークフロー
skip_turn	チュータリング/コーチング(静かなリスニング)
voicemail_detection	発信呼び出し
play_keypad_touch_tone	IVRナビゲーション

統合ツール

プラットフォームが管理する事前構築されたコネクター。認証情報を使用して接続を作成し、tool_ids で接続します:

統合	ユースケース
calcom	予定のスケジュール設定
salesforce	CRM検索、ケース作成
hubspot	CRM、マーケティング、連絡先
zendesk	サポートチケット処理

3ステップフロー: POST /v1/convai/api-integrations/{id}/connections → GET /v1/convai/api-integrations/{id}/tools → POST /v1/convai/tools に api_integration_id と api_integration_connection_id を使用します。"prompt": {"tool_ids": ["tool_xxxx"]} でエージェントに接続します。インラインの tools と tool_ids は共存できます。重複するカスタムWebhookよりも統合を優先します。

パブリックAPI Webhookの例

プロトタイプに役立つ認証不要のAPI(URLはHTTPSである必要があります):

ツール	URL	目的
get_weather	https://wttr.in/{location}?format=j1	現在の天気
search_wikipedia	https://en.wikipedia.org/api/rest_v1/page/summary/{topic}	トピックの概要
get_exchange_rate	https://open.er-api.com/v6/latest/{base_currency}	為替レート

ワークフロー

分散ステップを通じて会話をルーティングし、分岐ロジックを使用します。エージェントのトップレベル workflow フィールドの下に定義します。参照: Agent Workflows

ノードタイプ: start (IDは "start_node" である必要があります), end, override_agent (サブエージェントステップ、label + additional_prompt 付き), dispatch_tool (成功/失敗ルーティング付きでツールを実行), agent_transfer, transfer_to_number

エッジタイプ: unconditional, llm (自然言語条件), expression (決定的データチェック)。ツールノードには個別の成功/失敗エッジがあります。

ノード上の additional_tool_ids でツール範囲を設定 - 誤ったツールが誤ったステップで発火するのを防ぎます。グリーティングや classify_intent などの会話ルーティングノードで additional_tool_ids: [] を設定して、会話のみを実行:

{
  "type": "override_agent",
  "label": "Book Appointment",
  "additional_prompt": "Discuss preferred dates and doctors. Show the booking form once agreed.",
  "additional_tool_ids": ["show_booking_form", "display_appointment_card"],
  "position": {"x": 0, "y": 400}
}

すべてのノードに position ({x, y}) を含める - エディタがクリーンにレンダリングされます。y=0 で開始して、下部に end を配置し、ブランチを水平方向に x=-150 と x=150 で配置します。推奨される間隔はレベル間で200px垂直、ブランチ間で300px水平です。ワークフローを4-7ノードに保ち、常に end へのパスを作成します。

ガードレール

LLMから独立して動作する階層化されたセーフティ実装 - platform_settings.guardrails の下で設定されます。システムプロンプトではありません。参照: Guardrails

"platform_settings": {
  "guardrails": {
    "version": "1",
    "focus": {"is_enabled": true},
    "prompt_injection": {"is_enabled": true},
    "content": {"config": {"harassment": {"is_enabled": true, "threshold": 0.5}}},
    "custom": {
      "config": {
        "configs": [{
          "is_enabled": true,
          "name": "No medical diagnoses",
          "prompt": "Block the agent from providing medical diagnoses or treatment advice.",
          "execution_mode": "blocking",
          "trigger_action": {"type": "retry", "feedback": "Reason: {{trigger_reason}}"}
        }]
      }
    }
  }
}

タイプ: focus (トピックに関連), prompt_injection (操作防御), content (カテゴリフィルター), custom (LLM評価ドメインルール)。コンテンツカテゴリは harassment, profanity, sexual, violence, self_harm, medical_and_legal_information を含みます - 閾値範囲は 0.0–1.0 (デフォルト 0.3)。カスタムルールは execution_mode: "blocking" を trigger_action (例:retry とフィードバック付き)で使用します。カスタムガードレールは並行して評価されフェイルオープンします。

産業別: ヘルスケア/金融/法律 → medical_and_legal_information を有効にする; 教育/ユース → sexual/violence/self_harm/profanity; サポート/営業 → harassment/profanity。すべてのエージェントは focus + prompt_injection + 2-4個のカスタムルールから利益を得ます。

エージェントのテスト

POST /v1/convai/agent-testing/create 経由の3つのテストタイプ。その後、エージェントでPATCHで添付されます。参照: Agent Testing

タイプ	目的
llm	シナリオテスト - エージェントはメッセージに適切に応答しますか?
tool	ツール呼び出しテスト - 正しいツール、正しいパラメータ?
simulation	シミュレートされたユーザーペルソナを持つマルチターンフロー

// ツール呼び出しテスト(全体でsnake_case; chat_history ロールは"user"または"agent")
{
  "name": "Books with correct doctor and date",
  "type": "tool",
  "chat_history": [
    {"role": "user", "message": "Dr. Smith on March 5 at 2pm", "time_in_call_secs": 10}
  ],
  "tool_call_parameters": {
    "referenced_tool": {"id": "show_booking_form", "type": "client"},
    "parameters": [
      {"path": "doctor_name", "eval": {"type": "llm", "description": "Should reference Dr. Smith"}},
      {"path": "date", "eval": {"type": "regex", "pattern": "2025-03-05|March 5"}}
    ]
  }
}

評価戦略: exact, regex, llm。PATCHで添付:

curl -s -X PATCH "https://api.elevenlabs.io/v1/convai/agents/{agent_id}" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
  -d '{"platform_settings": {"testing": {"attached_tests": [{"test_id": "test_xxxx"}]}}}'

ウィジェット埋め込み

<elevenlabs-convai agent-id="your-agent-id"></elevenlabs-convai>
<script src="https://unpkg.com/@elevenlabs/convai-widget-embed" async type="text/javascript"></script>

属性でカスタマイズ: avatar-image-url, action-text, start-call-text, end-call-text

すべてのオプションについては Widget Embedding Reference を参照してください。

発信通話

Twilio統合を使用してエージェント経由で発信電話通話を行います:

Python

response = client.conversational_ai.twilio.outbound_call(
    agent_id="your-agent-id",
    agent_phone_number_id="your-phone-number-id",
    to_number="+1234567890",
    call_recording_enabled=True
)
print(f"Call initiated: {response.conversation_id}")

JavaScript

const response = await client.conversationalAi.twilio.outboundCall({
  agentId: "your-agent-id",
  agentPhoneNumberId: "your-phone-number-id",
  toNumber: "+1234567890",
  callRecordingEnabled: true,
});

cURL

curl -X POST "https://api.elevenlabs.io/v1/convai/twilio/outbound-call" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
  -d '{"agent_id": "your-agent-id", "agent_phone_number_id": "your-phone-number-id", "to_number": "+1234567890", "call_recording_enabled": true}'

設定オーバーライドと動的変数については Outbound Calls Reference を参照してください。

エージェントの管理

CLIの使用(推奨)

# エージェントをリストしてステータスを確認
elevenlabs agents list
elevenlabs agents status

# プラットフォームからエージェントをローカル設定にインポート
elevenlabs agents pull                      # すべてのエージェントをインポート
elevenlabs agents pull --agent <agent-id>   # 特定のエージェントをインポート

# ローカル変更をプラットフォームにプッシュ
elevenlabs agents push              # 設定をアップロード
elevenlabs agents push --dry-run    # まず変更をプレビュー

# ツールを追加
elevenlabs tools add-webhook "Weather API"
elevenlabs tools add-client "UI Tool"

プロジェクト構造

CLIはエージェントを管理するためのプロジェクト構造を作成します:

your_project/
├── agents.json       # エージェント定義
├── tools.json        # ツール設定
├── tests.json        # テスト設定
├── agent_configs/    # 個別エージェント設定
├── tool_configs/     # 個別ツール設定
└── test_configs/     # 個別テスト設定

SDKの例

# リスト
agents = client.conversational_ai.agents.list()

# 取得
agent = client.conversational_ai.agents.get(agent_id="your-agent-id")

# 更新(部分的 - 変更するフィールドのみ含める)
client.conversational_ai.agents.update(agent_id="your-agent-id", name="New Name")
client.conversational_ai.agents.update(agent_id="your-agent-id",
    conversation_config={
        "agent": {"prompt": {"prompt": "New instructions", "llm": "claude-sonnet-4"}}
    })

# 削除
client.conversational_ai.agents.delete(agent_id="your-agent-id")

すべての設定オプションとSDKの例については Agent Configuration を参照してください。

エラーハンドリング

try:
    agent = client.conversational_ai.agents.create(...)
except Exception as e:
    print(f"API error: {e}")

一般的なエラー: 401 (無効なキー), 404 (見つかりません), 422 (無効な設定), 429 (レート制限)

参照

• Installation Guide - SDKセットアップとマイグレーション
• Agent Configuration - すべての設定オプションとCRUDの例
• Client Tools - Webhook、クライアント、システムツール
• Widget Embedding - Webサイト統合
• Outbound Calls - Twilio電話通話統合