> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# 環境変数

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

## 概要

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

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

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

![環境変数の概要](/docs/_fern-img/75bbfad6349ff43d078f62e75f7d3549858897158e55ada3dcdbf261a963b055.webp)

## 基本概念

### 環境変数

環境変数は、ラベルと環境ごとの値のセットを持つワークスペーススコープのリソースです。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`

この構文は[動的変数](/docs/ja/eleven-agents/customization/personalization/dynamic-variables)と一貫しており、WebhookツールおよびMCPサーバー接続のURLフィールドで使用できます。

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

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

### 解決とフォールバック

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

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

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

## 環境変数を作成する

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

#### ダッシュボードで作成

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

#### 環境を作成

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

#### 変数を作成

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

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

![変数を作成](/docs/_fern-img/8ab18d57956167aaa152e10b4d2890b208c8ba826ef0cbbf9082c8e1602f5246.webp)

#### APIで作成

#### 文字列

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.environment_variables.create(
    label="api_host",
    type="string",
    values={
        "production": "api",
        "staging": "staging.api",
        "development": "dev.api",
    },
)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.environmentVariables.create({
  label: "api_host",
  type: "string",
  values: {
    production: "api",
    staging: "staging.api",
    development: "dev.api",
  },
});
```

#### シークレット

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.environment_variables.create(
    label="my_api_key",
    type="secret",
    values={
        "production": {"secret_id": "your-production-secret-id"},
        "staging": {"secret_id": "your-staging-secret-id"},
    },
)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.environmentVariables.create({
  label: "my_api_key",
  type: "secret",
  values: {
    production: { secretId: "your-production-secret-id" },
    staging: { secretId: "your-staging-secret-id" },
  },
});
```

#### 認証接続

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.environment_variables.create(
    label="my_oauth_connection",
    type="auth_connection",
    values={
        "production": {"auth_connection_id": "your-production-auth-connection-id"},
        "staging": {"auth_connection_id": "your-staging-auth-connection-id"},
    },
)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.environmentVariables.create({
  label: "my_oauth_connection",
  type: "auth_connection",
  values: {
    production: { authConnectionId: "your-production-auth-connection-id" },
    staging: { authConnectionId: "your-staging-auth-connection-id" },
  },
});
```

## 環境変数を使用する

### WebhookツールのURLで使用する

[Webhookツール](/docs/ja/eleven-agents/customization/tools/webhook-tools)のURLフィールドでテンプレート構文を使用すると、環境ごとにベースURLを解決できます。

![ツールURL内の環境変数](/docs/_fern-img/8a9d4a7fbd589565c57f52aa82200c28fe7fcfcc80ff9a3ec41a99ca315a9f50.webp)

たとえば、次のように設定したツール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の例

**`Python`**

```python title="Python"

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",
                },
            }
        ],
    },
)
```

**`JavaScript`**

```javascript title="JavaScript"
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const client = new ElevenLabsClient({ apiKey: "your-api-key" });

const agent = await client.conversationalAi.agents.create({
  conversationConfig: {
    agent: {
      firstMessage: "Hello! How can I help?",
      prompt: { prompt: "You are a helpful assistant." },
    },
    tools: [
      {
        type: "webhook",
        name: "get_data",
        description: "Fetches data from the API",
        apiSchema: {
          url: "https://{{system__env_api_host}}.example.com/v1/data",
          method: "GET",
        },
      },
    ],
  },
});
```

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

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

#### APIの例

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

```json
{
  "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クライアントやトークンエンドポイントを使用する場合に便利です。

![環境変数の認証接続](/docs/_fern-img/41115e31cac8c55360cb4f5783a4d03cf63ea51a6f5baa2812993d70d7c4a4d5.webp)

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

#### APIの例

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

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

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

環境変数は、[MCPサーバー](/docs/ja/eleven-agents/customization/tools/mcp)接続でもWebhookツールと同様に使用できます。以下で利用できます。

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

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

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

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

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

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

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

#### APIの例

```json
{
  "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`になります。

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

![エージェントプレビューの環境
セレクター](/docs/_fern-img/052880e903ac2dc3539a0ed84feef5a3d31cd28c9b1345705c9003796d382803.webp)

### WebSocket

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

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

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

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

**`Python`**

```python title="Python"
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",
)

```

**`JavaScript`**

```javascript title="JavaScript"
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const client = new ElevenLabsClient({ apiKey: "your-api-key" });

const token = await client.conversationalAi.conversation.getToken({
    agentId: "your-agent-id",
    environment: "staging",
});
```

**`cURL`**

```bash title="cURL"
curl "https://api.elevenlabs.io/v1/convai/conversation/token?agent_id=<agent_id>&environment=staging" \
  -H "xi-api-key: $ELEVENLABS_API_KEY"
```

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

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

![電話番号の環境とブランチ
セレクター](/docs/_fern-img/ba83735f5cad2006555eb73a12a520c7c86fa3d576d8f69f481a8c75d315cf1d.webp)

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

1. サーバーが通話ごとに動的に指定する場合、[会話開始Webhook](/docs/ja/eleven-agents/customization/personalization#conversation-initiation-webhooks)が返す`environment`値
2. **電話番号**自体に保存されている環境
3. デフォルトの`production`

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

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

**`Python`**

```python title="Python"
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",
)
```

**`JavaScript`**

```typescript title="JavaScript"
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.phoneNumbers.update("phnum_8901k4t9z5defmb8vh3e9361y7nj", {
  environment: "staging",
  branchId: "agtbrch_8901k4t9z5defmb8vh3e9361y7nj",
});
```

**`cURL`**

```bash title="cURL"
curl -X PATCH "https://api.elevenlabs.io/v1/convai/phone-numbers/phnum_8901k4t9z5defmb8vh3e9361y7nj" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "staging",
    "branch_id": "agtbrch_8901k4t9z5defmb8vh3e9361y7nj"
  }'
```

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

### React SDK

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

```tsx
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バックエンドと認証情報を使用する、単一エージェントの完全なセットアップを紹介します。

#### 環境変数を作成

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

| ラベル           | タイプ    | 開発              | ステージング              | 本番               |
| ------------- | ------ | --------------- | ------------------- | ---------------- |
| `api_host`    | 文字列    | `dev.api`       | `staging.api`       | `api`            |
| `api_key`     | シークレット | `dev-secret-id` | `staging-secret-id` | `prod-secret-id` |
| `oauth_creds` | 認証接続   | `dev-oauth-id`  | `staging-oauth-id`  | `prod-oauth-id`  |

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

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

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

#### 会話時に環境を指定

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

**`Development`**

```python title="Development"
conversation = client.conversational_ai.conversation.get_signed_url(
    agent_id="your-agent-id",
    environment="development",
)
```

**`Staging`**

```python title="Staging"
conversation = client.conversational_ai.conversation.get_signed_url(
    agent_id="your-agent-id",
    environment="staging",
)
```

**`Production (default)`**

```python title="Production (default)"
# No environment parameter needed — defaults to production
conversation = client.conversational_ai.conversation.get_signed_url(
    agent_id="your-agent-id",
)
```

#### 環境でフィルタリング

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

![環境で分析をフィルタリング](/docs/_fern-img/640f45e330a6f58648bb79fb588b580bb1d938e20f46c453b6d0c0efdac04054.webp)

![環境で会話履歴をフィルタリング](/docs/_fern-img/de6cdcdad31761a4e94928ea125503a555635eaf579521096b5f38d5ef931cd0.webp)

### 命名の制約

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

## 次のステップ

#### [Webhookツール](/docs/ja/eleven-agents/customization/tools/webhook-tools)

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

#### [MCPサーバー](/docs/ja/eleven-agents/customization/tools/mcp)

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

#### [カスタムLLM](/docs/ja/eleven-agents/customization/llm/custom-llm)

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

#### [バージョン管理](/docs/ja/eleven-agents/operate/versioning)

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