> 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.

# Umgebungsvariablen

Mit Umgebungsvariablen können Sie für jede Umgebung Werte für Tool-URLs, Secrets, Header und Auth-Verbindungen definieren. Eine einzelne Agenten- und Tool-Konfiguration funktioniert in all Ihren Umgebungen — URLs, API-Schlüssel und Authentifizierung werden dynamisch anhand der zur Gesprächszeit angegebenen Umgebung aufgelöst.

## Übersicht

Ohne Umgebungsvariablen müssen Sie beim Bereitstellen eines Agenten in mehreren Umgebungen (Entwicklung, Staging, Produktion) Agenten und Tools für jede Umgebung duplizieren und ihre Konfigurationen dann manuell synchron halten. Das führt zu:

* **Konfigurationsabweichungen** zwischen Umgebungen
* **Fragmentierten Analysen** über duplizierte Agenten-IDs hinweg
* **Reibung bei der Überführung** von Staging in die Produktion

Umgebungsvariablen lösen dieses Problem durch eine wiederverwendbare Ressource auf Workspace-Ebene, die unterschiedliche Werte pro Umgebung speichert. Tools und MCP-Server referenzieren diese Variablen mit Template-Syntax. Der korrekte Wert wird zur Laufzeit anhand der Gesprächsumgebung aufgelöst.

![Übersicht der Umgebungsvariablen](/docs/_fern-img/75bbfad6349ff43d078f62e75f7d3549858897158e55ada3dcdbf261a963b055.webp)

## Grundkonzepte

### Umgebungsvariablen

Eine Umgebungsvariable ist eine Ressource auf Workspace-Ebene mit einer Bezeichnung und einer Reihe von Werten pro Umgebung. Es gibt drei Typen:

| Typ                 | Beschreibung                                            | Beispielanwendung                                     |
| ------------------- | ------------------------------------------------------- | ----------------------------------------------------- |
| **String**          | Klartextwerte, die je nach Umgebung variieren           | Basis-URLs, Hostnamen, Konfigurationswerte            |
| **Secret**          | Referenzen auf Workspace-Secrets, je Umgebung aufgelöst | API-Schlüssel, Bearer-Token, Webhook-Signatur-Secrets |
| **Auth-Verbindung** | Referenzen auf Auth-Verbindungen, je Umgebung aufgelöst | OAuth2-Anmeldedaten, JWT-Konfigurationen              |

Jede Umgebungsvariable muss einen Wert für die Standardumgebung `production` haben. Zusätzliche Umgebungen (z. B. `staging`, `development`) sind optional.

### Template-Syntax

Referenzieren Sie Umgebungsvariablen in URL-Feldern mit der Syntax `{{system__env_<label>}}`:

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

Bei einer Umgebungsvariable `api_host` mit den Werten `api` (Produktion) und `staging.api` (Staging) wird dies aufgelöst zu:

* In `production`: `https://api.example.com/v1/text-to-speech`
* In `staging`: `https://staging.api.example.com/v1/text-to-speech`

Diese Syntax stimmt mit [dynamischen Variablen](/docs/de/eleven-agents/customization/personalization/dynamic-variables) überein und funktioniert in URL-Feldern für Webhook-Tools und MCP-Server-Verbindungen.

> **Note**
>
> Umgebungsvariablen werden auch in URLs und Headern für **Pre-Call-Webhooks** (dem
> Conversation Initiation Client Data Webhook) sowie in URLs für **Post-Call-Webhooks** unterstützt,
> die unter **Developers > Webhooks** konfiguriert werden. Templates werden anhand der Gesprächsumgebung
> aufgelöst, sodass dieselbe Webhook-Konfiguration je Umgebung unterschiedliche Endpunkte ansprechen
> kann. Für Pre-Call-Webhooks kann die Umgebung vorab für die Telefonnummer festgelegt oder dynamisch
> in Ihrer Webhook-Antwort zurückgegeben werden (siehe [Telefonie](#telephony-twilio-and-sip-trunk)
> unten).

> **Note**
>
> URLs müssen vor allen Referenzen auf Umgebungsvariablen mit `https://` beginnen. Zum Beispiel ist `https://   {{ system__env_api_host }}.example.com/v1/data` gültig, `{{ system__env_api_host }}/v1/data`
> dagegen nicht. Dies ist für Validierung und Sicherheit erforderlich — Werte von Umgebungsvariablen
> dürfen das Protokoll nicht steuern.

### Auflösung und Fallback

Wenn ein Gespräch in einer bestimmten Umgebung läuft, löst das System Umgebungsvariablen wie folgt auf:

1. Den Wert für die angeforderte Umgebung nachschlagen (z. B. `staging`)
2. Wenn für diese Umgebung kein Wert vorhanden ist, **auf den Wert von `production` zurückfallen**
3. Kann die Variable nicht aufgelöst werden, schlägt der Tool-Aufruf mit einem Konfigurationsfehler fehl

Durch dieses Fallback-Verhalten müssen Sie nur für Umgebungen Werte definieren, die sich von der Produktion unterscheiden.

## Umgebungsvariablen erstellen

> **Note**
>
> Umgebungsvariablen können noch nicht über die ElevenLabs CLI verwaltet werden — verwenden Sie das Dashboard oder SDK.

#### Über das Dashboard erstellen

Navigieren Sie im ElevenLabs-Dashboard zu **Developers > Environment Variables**.

#### Eine Umgebung erstellen

Definieren Sie Umgebungen, die Ihren Bereitstellungsstufen entsprechen (z. B. `eu`, `india`, `staging`). Die Umgebung `production` ist standardmäßig immer verfügbar.

#### Eine Variable erstellen

Klicken Sie auf **Add variable** und wählen Sie den Variablentyp:

* **String**: Geben Sie eine Bezeichnung ein und legen Sie für jede Umgebung einen Wert fest
* **Secret**: Wählen Sie für jede Umgebung ein vorhandenes Workspace-Secret aus
* **Auth-Verbindung**: Wählen Sie für jede Umgebung eine vorhandene Auth-Verbindung aus

![Variable erstellen](/docs/_fern-img/8ab18d57956167aaa152e10b4d2890b208c8ba826ef0cbbf9082c8e1602f5246.webp)

#### Über die API erstellen

#### String

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

#### Secret

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

#### Auth-Verbindung

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

## Umgebungsvariablen verwenden

### In Webhook-Tool-URLs

Verwenden Sie die Template-Syntax im URL-Feld eines [Webhook-Tools](/docs/de/eleven-agents/customization/tools/webhook-tools), damit die Basis-URL je Umgebung aufgelöst wird.

![Umgebungsvariable in Tool-URL](/docs/_fern-img/8a9d4a7fbd589565c57f52aa82200c28fe7fcfcc80ff9a3ec41a99ca315a9f50.webp)

Beispielsweise wird eine Tool-URL mit folgender Konfiguration:

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

in der Produktion zu `https://api.example.com/v1/weather?lat=40.7&lon=-74.0` und im Staging zu `https://staging.api.example.com/v1/weather?lat=40.7&lon=-74.0` aufgelöst.

Sie können mehrere Umgebungsvariablen und literale Segmente in einer einzelnen URL kombinieren:

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

#### API-Beispiel

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

### In Webhook-Tool-Headern

Secret-Umgebungsvariablen können in Request-Headern verwendet werden. Referenzieren Sie statt einer fest codierten Secret-ID eine Umgebungsvariable, damit je Umgebung unterschiedliche Secrets verwendet werden. Wählen Sie bei der Konfiguration eines Tool-Headers im Dashboard eine Umgebungsvariable statt eines statischen Secrets aus. Zur Laufzeit wird der Header-Wert in das für die aktuelle Umgebung gespeicherte Secret aufgelöst.

#### API-Beispiel

Übergeben Sie im Feld `request_headers` eine Referenz auf eine Umgebungsvariable:

```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" }
    }
  }
}
```

### In Webhook-Tool-Auth-Verbindungen

Auth-Verbindungen (OAuth2, JWT, Basic Auth) können ebenfalls je Umgebung aufgelöst werden. Das ist hilfreich, wenn Ihre Staging- und Produktionsumgebungen unterschiedliche OAuth-Clients oder Token-Endpunkte verwenden.

![Auth-Verbindung für Umgebungsvariable](/docs/_fern-img/41115e31cac8c55360cb4f5783a4d03cf63ea51a6f5baa2812993d70d7c4a4d5.webp)

Wählen Sie in der Tool-Konfiguration eine Umgebungsvariable vom Typ `auth_connection`, statt direkt eine Auth-Verbindung auszuwählen. Die korrekte Auth-Verbindung für die aktuelle Umgebung wird zur Laufzeit aufgelöst.

#### API-Beispiel

Referenzieren Sie im Feld `auth_connection` eine Umgebungsvariable:

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

### In MCP-Server-Verbindungen

Umgebungsvariablen funktionieren mit [MCP-Server](/docs/de/eleven-agents/customization/tools/mcp)-Verbindungen genauso wie mit Webhook-Tools. Sie können sie verwenden in:

* **Server-URL**: Erstellen Sie ein Template für die MCP-Server-URL, um je Umgebung auf unterschiedliche Server zu verweisen
* **Request-Headern**: Verwenden Sie Secret-Umgebungsvariablen für Authentifizierungs-Header
* **Auth-Verbindungen**: Verwenden Sie Auth-Verbindungs-Umgebungsvariablen für OAuth-basierte MCP-Server

Beispielsweise wird eine MCP-Server-URL mit folgender Konfiguration:

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

je nach Umgebung zu unterschiedlichen MCP-Server-Endpunkten aufgelöst.

### In benutzerdefinierten LLM-Konfigurationen

Bei Verwendung eines [benutzerdefinierten LLM](/docs/de/eleven-agents/customization/llm/custom-llm) können Umgebungsvariablen den API-Schlüssel und Request-Header als Template verwenden. So können Sie unterschiedliche Modell-Endpunkte und Anmeldedaten in verschiedenen Umgebungen nutzen.

Das URL-Feld für benutzerdefinierte LLMs unterstützt dieselbe Template-Syntax `{{system__env_<label>}}`. Das Feld `api_key` akzeptiert eine Referenz auf eine Umgebungsvariable, damit je Umgebung unterschiedliche API-Schlüssel verwendet werden.

#### API-Beispiel

```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" }
        }
      }
    }
  }
}
```

## Umgebung angeben

Die Umgebung wird beim Start eines Gesprächs festgelegt und bleibt für das gesamte Gespräch erhalten. Wenn keine Umgebung angegeben ist, wird standardmäßig `production` verwendet.

Wählen Sie beim Testen im Dashboard die Umgebung im Dropdown-Menü der Agentenvorschau aus:

![Umgebungsauswahl in der
Agentenvorschau](/docs/_fern-img/052880e903ac2dc3539a0ed84feef5a3d31cd28c9b1345705c9003796d382803.webp)

### WebSocket

Übergeben Sie beim Herstellen einer Verbindung zum Gesprächs-WebSocket den Abfrageparameter `environment`:

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

### WebRTC (signierte URL / Token)

Bei Verwendung von WebRTC übergeben Sie beim Anfordern eines Gesprächstokens den Parameter `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"
```

### Telefonie (Twilio und SIP-Trunk)

Telefonnummern können an eine bestimmte Umgebung und einen bestimmten [Agenten-Branch](/docs/de/eleven-agents/operate/versioning) gebunden werden. So können Sie eine Testtelefonnummer einfach an einen Entwicklungs-Branch eines Agenten weiterleiten, dessen Tools eine Entwicklungs-API ausführen.

![Umgebungs- und Branch-Auswahl für
Telefonnummern](/docs/_fern-img/ba83735f5cad2006555eb73a12a520c7c86fa3d576d8f69f481a8c75d315cf1d.webp)

Bei eingehenden Anrufen wird die Umgebung in dieser Reihenfolge aufgelöst:

1. Der von Ihrem [Conversation-Initiation-Webhook](/docs/de/eleven-agents/customization/personalization#conversation-initiation-webhooks) zurückgegebene Wert `environment`, wenn Ihr Server ihn dynamisch pro Anruf bereitstellt
2. Die auf der **Telefonnummer** selbst gespeicherte Umgebung
3. Standardmäßig `production`

Dieselbe Priorität gilt für `branch_id`. URLs und Header für Pre-Call-Webhooks sowie URLs für Post-Call-Webhooks lösen dann `{{system__env_*}}`-Templates anhand der ausgewählten Umgebung auf.

Binden Sie eine Telefonnummer an eine Umgebung und einen Branch (erfordert Python SDK `elevenlabs` ≥ 2.47.0 oder `@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"
  }'
```

Übergeben Sie bei ausgehenden Anrufen das Feld `environment`, wenn Sie den Anruf über die ausgehenden Twilio- oder SIP-Trunk-Endpunkte starten.

### React SDK

Übergeben Sie die Option `environment` im Hook `useConversation` oder beim Starten einer Sitzung:

```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>;
}
```

## Beispiel: Agent für mehrere Umgebungen

Dieses Beispiel zeigt eine vollständige Einrichtung mit einem einzelnen Agenten, der für Entwicklung, Staging und Produktion unterschiedliche API-Backends und Anmeldedaten verwendet.

#### Umgebungsvariablen erstellen

Erstellen Sie im Dashboard oder per API drei Umgebungsvariablen:

| Bezeichnung   | Typ             | Entwicklung     | Staging             | Produktion       |
| ------------- | --------------- | --------------- | ------------------- | ---------------- |
| `api_host`    | String          | `dev.api`       | `staging.api`       | `api`            |
| `api_key`     | Geheimnis       | `dev-secret-id` | `staging-secret-id` | `prod-secret-id` |
| `oauth_creds` | Auth-Verbindung | `dev-oauth-id`  | `staging-oauth-id`  | `prod-oauth-id`  |

#### Tools mit Verweisen auf Umgebungsvariablen konfigurieren

Richten Sie Ihre Webhook-Tools mit Vorlagensyntax ein:

* **URL**: `https://{{system__env_api_host}}.example.com/v1/orders`
* **Header**: Verweisen Sie für den Header `X-Api-Key` auf die Umgebungsvariable `api_key`
* **Authentifizierung**: Verweisen Sie für die OAuth-Authentifizierung auf die Umgebungsvariable `oauth_creds`

#### Umgebung beim Start der Unterhaltung angeben

Übergeben Sie beim Start einer Unterhaltung die Zielumgebung:

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

#### Nach Umgebung filtern

Die Umgebung wird für jede Unterhaltung erfasst. Filtern Sie Ihre Analytics-Dashboards und den Unterhaltungsverlauf nach Umgebung, um Metriken je Bereitstellungsphase zu isolieren.

![Analytics nach Umgebung filtern](/docs/_fern-img/640f45e330a6f58648bb79fb588b580bb1d938e20f46c453b6d0c0efdac04054.webp)

![Unterhaltungsverlauf nach Umgebung filtern](/docs/_fern-img/de6cdcdad31761a4e94928ea125503a555635eaf579521096b5f38d5ef931cd0.webp)

### Namensvorgaben

* **Bezeichnungen**: Nur alphanumerische Zeichen und Unterstriche (z. B. `base_url`, `api_key_v2`)
* **Umgebungsnamen**: Müssen mit einem Kleinbuchstaben beginnen und dürfen nur Kleinbuchstaben, Ziffern, Unterstriche und Bindestriche enthalten, mit maximal 64 Zeichen (z. B. `production`, `staging`, `dev-us-east`)
* Jede Umgebungsvariable muss einen Wert für `production` haben

## Nächste Schritte

#### [Webhook-Tools](/docs/de/eleven-agents/customization/tools/webhook-tools)

Konfigurieren Sie Webhook-Tools mit umgebungsabhängigen URLs und Authentifizierung

#### [MCP-Server](/docs/de/eleven-agents/customization/tools/mcp)

Verbinden Sie MCP-Server mit Konfigurationen für jede Umgebung

#### [Benutzerdefiniertes LLM](/docs/de/eleven-agents/customization/llm/custom-llm)

Verwenden Sie unterschiedliche Modellendpunkte für verschiedene Umgebungen

#### [Versionierung](/docs/de/eleven-agents/operate/versioning)

Kombinieren Sie Umgebungsvariablen mit Branches und Traffic-Splitting