デプロイ

環境変数

リソースを複製せずに、同じエージェントを開発、ステージング、本番環境にデプロイできます。

環境変数を使用すると、ツールURL、シークレット、ヘッダー、認証接続について、環境ごとの値を定義できます。単一のエージェントおよびツール設定をすべての環境で使用でき、URL、APIキー、認証は会話時に指定された環境に応じて動的に解決されます。

概要

環境変数を使用せずに複数の環境（開発、ステージング、本番）にエージェントをデプロイするには、環境ごとにエージェントとツールを複製し、その設定を手動で同期し続ける必要があります。これにより、次の問題が生じます。

  • 環境間の設定の乖離
  • 複製されたエージェントIDにまたがる分析データの分散
  • ステージングから本番への移行時の昇格の手間

環境変数は、環境ごとに異なる値を格納する、再利用可能なワークスペーススコープのリソースを導入することでこれを解決します。ツールとMCPサーバーはテンプレート構文を使ってこれらの変数を参照し、会話の環境に基づいて実行時に正しい値が解決されます。

環境変数の概要

基本概念

環境変数

環境変数は、ラベルと環境ごとの値のセットを持つワークスペーススコープのリソースです。3つのタイプがあります。

タイプ説明使用例
文字列環境ごとに異なるプレーンテキスト値ベースURL、ホスト名、設定値
シークレット環境ごとに解決されるワークスペースシークレットへの参照APIキー、ベアラートークン、Webhook署名シークレット
認証接続環境ごとに解決される認証接続への参照OAuth2認証情報、JWT設定

各環境変数には、デフォルトのproduction環境の値が必要です。追加の環境（例：staging、development）は任意です。

テンプレート構文

URLフィールドでは、{{system__env_<label>}}構文を使用して環境変数を参照します。

https://{{system__env_api_host}}.example.com/v1/text-to-speech

api（本番）とstaging.api（ステージング）の値を持つ環境変数api_hostの場合、次のように解決されます。

  • productionの場合：https://api.example.com/v1/text-to-speech
  • stagingの場合：https://staging.api.example.com/v1/text-to-speech

この構文は動的変数と一貫しており、WebhookツールおよびMCPサーバー接続のURLフィールドで使用できます。

環境変数は、通話前WebhookのURLとヘッダー（Conversation Initiation Client Data Webhook）、および Developers > Webhooksで設定する通話後WebhookのURLでもサポートされています。テンプレートは会話の環境を使用して解決されるため、同じ Webhook設定で環境ごとに異なるエンドポイントを対象にできます。通話前Webhookでは、環境を電話番号で事前に設定することも、Webhookの レスポンスで動的に返すこともできます（以下のTelephonyを参照）。

URLは、環境変数参照より前にhttps://で始まる必要があります。たとえば、https:// {{ system__env_api_host }}.example.com/v1/dataは有効ですが、{{ system__env_api_host }}/v1/data は無効です。これは検証とセキュリティのために必要であり、環境変数の値でプロトコルを制御することはできません。

解決とフォールバック

会話が特定の環境で実行されると、システムは次のように環境変数を解決します。

  1. リクエストされた環境（例：staging）の値を検索します
  2. その環境の値がない場合、productionの値にフォールバックします
  3. 変数を解決できない場合、ツール呼び出しは設定エラーで失敗します

このフォールバック動作により、本番環境と異なる環境についてのみ値を定義すればよくなります。

環境変数を作成する

環境変数はまだElevenLabs CLIでは管理できません。ダッシュボードまたはSDKを使用してください。

ElevenLabsダッシュボードで、Developers > Environment Variablesに移動します。

1

環境を作成

デプロイステージに対応する環境（例：eu、india、staging）を定義します。production環境はデフォルトで常に利用できます。

2

変数を作成

Add variableをクリックし、変数タイプを選択します。

  • 文字列：ラベルを入力し、環境ごとに値を設定
  • シークレット：環境ごとに既存のワークスペースシークレットを選択
  • 認証接続：環境ごとに既存の認証接続を選択

変数を作成

環境変数を使用する

WebhookツールのURLで使用する

WebhookツールのURLフィールドでテンプレート構文を使用すると、環境ごとにベースURLを解決できます。

ツールURL内の環境変数

たとえば、次のように設定したツールURLは：

https://{{system__env_api_host}}.example.com/v1/weather?lat={latitude}&lon={longitude}

本番環境ではhttps://api.example.com/v1/weather?lat=40.7&lon=-74.0に、ステージング環境ではhttps://staging.api.example.com/v1/weather?lat=40.7&lon=-74.0に解決されます。

1つのURLで複数の環境変数とリテラルセグメントを組み合わせることもできます。

https://{{system__env_api_host}}.example.com/{{system__env_api_version}}/weather

APIの例

from elevenlabs.client import ElevenLabs
client = ElevenLabs(api_key="your-api-key")
agent = client.conversational_ai.agents.create(
    conversation_config={
        "agent": {
            "first_message": "Hello! How can I help?",
            "prompt": {"prompt": "You are a helpful assistant."},
        },
        "tools": [
            {
                "type": "webhook",
                "name": "get_data",
                "description": "Fetches data from the API",
                "api_schema": {
                    "url": "https://{{system__env_api_host}}.example.com/v1/data",
                    "method": "GET",
                },
            }
        ],
    },
)

Webhookツールのヘッダーで使用する

シークレット環境変数はリクエストヘッダーで使用できます。シークレットIDをハードコードする代わりに環境変数を参照すると、環境ごとに異なるシークレットを使用できます。ダッシュボードでツールヘッダーを設定する際は、静的なシークレットではなく環境変数を選択してください。実行時に、ヘッダー値は現在の環境に保存されているシークレットに解決されます。

APIの例

request_headersフィールドに環境変数の参照を渡します。

{
  "api_schema": {
    "url": "https://{{system__env_api_host}}.example.com/v1/data",
    "method": "GET",
    "request_headers": {
      "X-Api-Key": { "env_var_label": "my_api_key" }
    }
  }
}

Webhookツールの認証接続で使用する

認証接続（OAuth2、JWT、Basic Auth）も環境ごとに解決できます。これは、ステージング環境と本番環境で異なるOAuthクライアントやトークンエンドポイントを使用する場合に便利です。

環境変数の認証接続

ツール設定では、認証接続を直接選択する代わりに、auth_connectionタイプの環境変数を選択します。現在の環境に対応する認証接続が実行時に解決されます。

APIの例

auth_connectionフィールドで環境変数を参照します。

{
  "api_schema": {
    "url": "https://{{system__env_api_host}}.example.com/v1/data",
    "method": "GET",
    "auth_connection": { "env_var_label": "my_oauth_connection" }
  }
}

MCPサーバー接続で使用する

環境変数は、MCPサーバー接続でもWebhookツールと同様に使用できます。以下で利用できます。

  • サーバーURL：MCPサーバーURLをテンプレート化し、環境ごとに異なるサーバーを指定
  • リクエストヘッダー：認証ヘッダーにシークレット環境変数を使用
  • 認証接続：OAuthベースのMCPサーバーに認証接続環境変数を使用

たとえば、次のように設定したMCPサーバーURLは：

https://{{system__env_mcp_host}}.example.com/mcp

環境に応じて異なるMCPサーバーエンドポイントに解決されます。

カスタムLLM設定で使用する

カスタムLLMを使用する場合、環境変数でAPIキーとリクエストヘッダーをテンプレート化できます。これにより、環境ごとに異なるモデルエンドポイントと認証情報を使用できます。

カスタムLLMのURLフィールドでは、同じ{{system__env_<label>}}テンプレート構文をサポートしています。api_keyフィールドは環境変数参照を受け付けるため、環境ごとに異なるAPIキーを使用できます。

APIの例

{
  "conversation_config": {
    "agent": {
      "prompt": { "prompt": "You are a helpful assistant." },
      "llm": {
        "custom_llm": {
          "url": "https://{{system__env_llm_host}}.example.com/v1/chat/completions",
          "model_id": "my-model",
          "api_key": { "env_var_label": "llm_api_key" }
        }
      }
    }
  }
}

環境を指定する

環境は会話の開始時に設定され、会話全体を通じて維持されます。環境を指定しない場合、デフォルトでproductionになります。

ダッシュボードでテストする際は、エージェントプレビューのドロップダウンから環境を選択します。

エージェントプレビューの環境 セレクター

WebSocket

会話WebSocketへの接続時に、environmentクエリパラメータを渡します。

wss://api.elevenlabs.io/v1/convai/conversation?agent_id=<agent_id>&environment=staging

WebRTC（署名付きURL／トークン）

WebRTCを使用する場合は、会話トークンをリクエストするときにenvironmentパラメータを渡します。

from elevenlabs.client import ElevenLabs
client = ElevenLabs(api_key="your-api-key")
token = client.conversational_ai.conversation.get_token(
agent_id="your-agent-id",
environment="staging",
)

電話（TwilioおよびSIPトランク）

電話番号は特定の環境および特定のエージェントブランチに固定できます。これにより、ツールが開発用APIに対して実行されるエージェントの開発ブランチへ、テスト用電話番号を簡単にルーティングできます。

電話番号の環境とブランチ セレクター

着信通話では、環境は次の順序で解決されます。

  1. サーバーが通話ごとに動的に指定する場合、会話開始Webhookが返すenvironment値
  2. 電話番号自体に保存されている環境
  3. デフォルトのproduction

同じ優先順位がbranch_idにも適用されます。その後、通話前WebhookのURLとヘッダー、および通話後WebhookのURLは、選択された環境を使用して{{system__env_*}}テンプレートを解決します。

電話番号を環境とブランチに固定します（elevenlabs Python SDK ≥ 2.47.0または@elevenlabs/elevenlabs-js ≥ 2.47.0が必要です）。

import os
from dotenv import load_dotenv
from elevenlabs import ElevenLabs
load_dotenv()
elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY"))
elevenlabs.conversational_ai.phone_numbers.update(
    phone_number_id="phnum_8901k4t9z5defmb8vh3e9361y7nj",
    environment="staging",
    branch_id="agtbrch_8901k4t9z5defmb8vh3e9361y7nj",
)

発信通話では、TwilioまたはSIPトランクの発信エンドポイントを介して通話を開始するときに、environmentフィールドを渡します。

React SDK

useConversationフック、またはセッション開始時にenvironmentオプションを渡します。

import { useConversation } from "@11labs/react";
function Agent() {
  const conversation = useConversation();
  const connect = async () => {
    await conversation.startSession({
      agentId: "your-agent-id",
      environment: "staging",
    });
  };
  return <button onClick={connect}>Start conversation</button>;
}

例：マルチ環境エージェント

この例では、開発、ステージング、本番の各環境で異なるAPIバックエンドと認証情報を使用する、単一エージェントの完全なセットアップを紹介します。

1

環境変数を作成

ダッシュボードまたはAPIで、3つの環境変数を作成します。

ラベルタイプ開発ステージング本番
api_host文字列dev.apistaging.apiapi
api_keyシークレットdev-secret-idstaging-secret-idprod-secret-id
oauth_creds認証接続dev-oauth-idstaging-oauth-idprod-oauth-id
2

環境変数参照でツールを設定

テンプレート構文を使用してWebhookツールを設定します。

  • URL：https://{{system__env_api_host}}.example.com/v1/orders
  • ヘッダー：X-Api-Keyヘッダーにapi_key環境変数を参照
  • 認証：OAuth認証にoauth_creds環境変数を参照
3

会話時に環境を指定

会話を開始するときに、対象の環境を渡します。

conversation = client.conversational_ai.conversation.get_signed_url(
    agent_id="your-agent-id",
    environment="development",
)
4

環境でフィルタリング

環境はすべての会話で追跡されます。デプロイステージごとの指標を切り分けるために、分析ダッシュボードと会話履歴を環境でフィルタリングしてください。

環境で分析をフィルタリング

環境で会話履歴をフィルタリング

命名の制約

  • ラベル：英数字とアンダースコアのみ（例：base_url、api_key_v2）
  • 環境名：小文字で始める必要があり、小文字、数字、アンダースコア、ハイフンのみを使用できます。最大64文字です（例：production、staging、dev-us-east）
  • すべての環境変数にはproduction値が必要です

次のステップ

Webhookツール

環境に応じたURLと認証でWebhookツールを設定

MCPサーバー

環境ごとの設定でMCPサーバーを接続

カスタムLLM

環境ごとに異なるモデルエンドポイントを使用

バージョン管理

環境変数をブランチとトラフィック分割と組み合わせる