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

# Variables d'environnement

Les variables d'environnement vous permettent de définir des valeurs propres à chaque environnement pour les URL d'outils, les secrets, les en-têtes et les connexions d'authentification. Une seule configuration d'agent et d'outil fonctionne dans tous vos environnements : les URL, clés API et authentifications sont résolues dynamiquement selon l'environnement spécifié au moment de la conversation.

## Vue d'ensemble

Sans variables d'environnement, déployer un agent dans plusieurs environnements (développement, préproduction, production) exige de dupliquer les agents et les outils pour chaque environnement, puis de maintenir manuellement leurs configurations synchronisées. Cela entraîne :

* Une **dérive de configuration** entre les environnements
* Des **analyses fragmentées** entre des ID d'agents dupliqués
* Des **frictions de promotion** lors du passage de la préproduction à la production

Les variables d'environnement résolvent ce problème en introduisant une ressource réutilisable à l'échelle du Workspace, qui stocke différentes valeurs pour chaque environnement. Les outils et serveurs MCP font référence à ces variables via une syntaxe de modèle, et la valeur correcte est résolue à l'exécution selon l'environnement de la conversation.

![Vue d'ensemble des variables d'environnement](/docs/_fern-img/75bbfad6349ff43d078f62e75f7d3549858897158e55ada3dcdbf261a963b055.webp)

## Concepts clés

### Variables d'environnement

Une variable d'environnement est une ressource à l'échelle du Workspace comprenant un libellé et un ensemble de valeurs propres à chaque environnement. Il existe trois types :

| Type                             | Description                                                                | Exemple de cas d'utilisation                             |
| -------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------- |
| **Chaîne**                       | Valeurs de texte brut variant selon l'environnement                        | URL de base, noms d'hôte, valeurs de configuration       |
| **Secret**                       | Références à des secrets du Workspace, résolues par environnement          | Clés API, jetons Bearer, secrets de signature de webhook |
| **Connexion d'authentification** | Références à des connexions d'authentification, résolues par environnement | Identifiants OAuth2, configurations JWT                  |

Chaque variable d'environnement doit avoir une valeur pour l'environnement `production` par défaut. Des environnements supplémentaires, tels que `staging` et `development`, sont facultatifs.

### Syntaxe de modèle

Faites référence aux variables d'environnement dans les champs URL à l'aide de la syntaxe `{{system__env_<label>}}` :

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

Pour une variable d'environnement `api_host` ayant les valeurs `api` (production) et `staging.api` (préproduction), cela donne :

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

Cette syntaxe est cohérente avec les [variables dynamiques](/docs/fr/eleven-agents/customization/personalization/dynamic-variables) et fonctionne dans les champs URL des outils webhook et des connexions aux serveurs MCP.

> **Note**
>
> Les variables d'environnement sont également prises en charge dans les URL et en-têtes de **webhook pré-appel** (le
> webhook Conversation Initiation Client Data) et dans les URL de **webhook post-appel** configurées sous
> **Developers > Webhooks**. Les modèles sont résolus à l'aide de l'environnement de la conversation ; la même
> configuration de webhook peut donc cibler différents points de terminaison selon l'environnement. Pour les webhooks pré-appel,
> l'environnement peut être défini à l'avance sur le numéro de téléphone ou renvoyé dynamiquement dans la réponse de votre webhook
> (voir [Téléphonie](#telephony-twilio-and-sip-trunk) ci-dessous).

> **Note**
>
> Les URL doivent commencer par `https://` avant toute référence à une variable d'environnement. Par exemple, `https://   {{ system__env_api_host }}.example.com/v1/data` est valide, mais `{{ system__env_api_host }}/v1/data`
> ne l'est pas. Cette règle est requise pour la validation et la sécurité : les valeurs des variables d'environnement ne peuvent pas contrôler
> le protocole.

### Résolution et repli

Lorsqu'une conversation s'exécute dans un environnement spécifique, le système résout les variables d'environnement comme suit :

1. Recherche la valeur correspondant à l'environnement demandé, par exemple `staging`
2. Si aucune valeur n'existe pour cet environnement, **utilise la valeur `production` comme repli**
3. Si la variable ne peut pas être résolue, l'appel d'outil échoue avec une erreur de configuration

Ce comportement de repli signifie que vous devez uniquement définir des valeurs pour les environnements qui diffèrent de la production.

## Créer des variables d'environnement

> **Note**
>
> Les variables d'environnement ne peuvent pas encore être gérées via l'interface de ligne de commande ElevenLabs : utilisez le Dashboard ou le SDK.

#### Créer via le Dashboard

Accédez à **Developers > Environment Variables** dans le Dashboard ElevenLabs.

#### Créer un environnement

Définissez les environnements qui correspondent à vos étapes de déploiement, par exemple `eu`, `india` et `staging`. L'environnement `production` est toujours disponible par défaut.

#### Créer une variable

Cliquez sur **Add variable** et choisissez le type de variable :

* **Chaîne** : saisissez un libellé et définissez une valeur pour chaque environnement
* **Secret** : sélectionnez un secret existant du Workspace pour chaque environnement
* **Connexion d'authentification** : sélectionnez une connexion d'authentification existante pour chaque environnement

![Créer une variable](/docs/_fern-img/8ab18d57956167aaa152e10b4d2890b208c8ba826ef0cbbf9082c8e1602f5246.webp)

#### Créer via l'API

#### Chaîne

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

#### Connexion d'authentification

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

## Utilisation des variables d’environnement

### Dans les URL des outils webhook

Utilisez la syntaxe de modèle dans le champ URL d’un [outil webhook](/docs/fr/eleven-agents/customization/tools/webhook-tools) afin que l’URL de base soit résolue selon l’environnement.

![Variable d’environnement dans l’URL de l’outil](/docs/_fern-img/8a9d4a7fbd589565c57f52aa82200c28fe7fcfcc80ff9a3ec41a99ca315a9f50.webp)

Par exemple, une URL d’outil configurée comme suit :

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

est résolue en `https://api.example.com/v1/weather?lat=40.7&lon=-74.0` en production et en `https://staging.api.example.com/v1/weather?lat=40.7&lon=-74.0` en préproduction.

Vous pouvez combiner plusieurs variables d’environnement et segments littéraux dans une même URL :

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

#### Exemple d’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",
        },
      },
    ],
  },
});
```

### Dans les en-têtes des outils webhook

Les variables d’environnement secrètes peuvent être utilisées dans les en-têtes de requête. Au lieu de coder en dur un ID secret, référencez une variable d’environnement afin d’utiliser des secrets différents selon l’environnement. Lors de la configuration d’un en-tête d’outil dans le Dashboard, sélectionnez une variable d’environnement plutôt qu’un secret statique. Lors de l’exécution, la valeur de l’en-tête est résolue vers le secret stocké pour l’environnement actuel.

#### Exemple d’API

Transmettez une référence de variable d’environnement dans le champ `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" }
    }
  }
}
```

### Dans les connexions d’authentification des outils webhook

Les connexions d’authentification (OAuth2, JWT, Basic Auth) peuvent également être résolues selon l’environnement. C’est utile lorsque vos environnements de préproduction et de production utilisent différents clients OAuth ou points de terminaison de jetons.

![Connexion d’authentification par variable d’environnement](/docs/_fern-img/41115e31cac8c55360cb4f5783a4d03cf63ea51a6f5baa2812993d70d7c4a4d5.webp)

Dans la configuration de l’outil, sélectionnez une variable d’environnement de type `auth_connection` au lieu de sélectionner directement une connexion d’authentification. La connexion d’authentification appropriée pour l’environnement actuel est résolue lors de l’exécution.

#### Exemple d’API

Référencez une variable d’environnement dans le champ `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" }
  }
}
```

### Dans les connexions aux serveurs MCP

Les variables d’environnement fonctionnent avec les connexions aux [serveurs MCP](/docs/fr/eleven-agents/customization/tools/mcp) de la même manière qu’avec les outils webhook. Vous pouvez les utiliser dans :

* **URL du serveur** : utilisez un modèle pour l’URL du serveur MCP afin de cibler différents serveurs selon l’environnement
* **En-têtes de requête** : utilisez des variables d’environnement secrètes pour les en-têtes d’authentification
* **Connexions d’authentification** : utilisez des variables d’environnement de connexion d’authentification pour les serveurs MCP basés sur OAuth

Par exemple, une URL de serveur MCP configurée comme suit :

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

est résolue vers différents points de terminaison de serveur MCP selon l’environnement.

### Dans les configurations LLM personnalisées

Lorsque vous utilisez un [LLM personnalisé](/docs/fr/eleven-agents/customization/llm/custom-llm), les variables d’environnement permettent de définir l’API key et les en-têtes de requête à l’aide de modèles. Vous pouvez ainsi utiliser différents points de terminaison de modèles et identifiants selon les environnements.

Le champ URL du LLM personnalisé prend en charge la même syntaxe de modèle `{{system__env_<label>}}`. Le champ `api_key` accepte une référence de variable d’environnement afin d’utiliser différentes API keys selon l’environnement.

#### Exemple d’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" }
        }
      }
    }
  }
}
```

## Spécifier l’environnement

L’environnement est défini au début de la conversation et reste le même pendant toute sa durée. Si aucun environnement n’est spécifié, la valeur par défaut est `production`.

Lors de vos tests dans le Dashboard, sélectionnez l’environnement dans le menu déroulant de l’aperçu de l’agent :

![Sélecteur d’environnement dans l’aperçu de l’agent](/docs/_fern-img/052880e903ac2dc3539a0ed84feef5a3d31cd28c9b1345705c9003796d382803.webp)

### WebSocket

Transmettez le paramètre de requête `environment` lors de la connexion au WebSocket de conversation :

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

### WebRTC (URL signée / jeton)

Lorsque vous utilisez WebRTC, transmettez le paramètre `environment` lors de la demande d’un jeton de conversation :

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

### Téléphonie (Twilio et trunk SIP)

Les numéros de téléphone peuvent être associés à un environnement spécifique et à une [branche d’agent](/docs/fr/eleven-agents/operate/versioning) spécifique, ce qui facilite le routage d’un numéro de téléphone de test vers une branche de développement d’un agent dont les outils s’exécutent sur une API de développement.

![Sélecteurs d’environnement et de branche du numéro de téléphone](/docs/_fern-img/ba83735f5cad2006555eb73a12a520c7c86fa3d576d8f69f481a8c75d315cf1d.webp)

Pour les appels entrants, l’environnement est résolu dans cet ordre :

1. La valeur `environment` renvoyée par votre [webhook d’initialisation de conversation](/docs/fr/eleven-agents/customization/personalization#conversation-initiation-webhooks), si votre serveur en fournit une dynamiquement pour chaque appel
2. L’environnement stocké sur le **numéro de téléphone** lui-même
3. `production` par défaut

Le même ordre de priorité s’applique à `branch_id`. Les URL et en-têtes des webhooks avant appel, ainsi que les URL des webhooks après appel, résolvent ensuite les modèles `{{system__env_*}}` à l’aide de l’environnement sélectionné.

Associez un numéro de téléphone à un environnement et à une branche (nécessite le SDK Python `elevenlabs` ≥ 2.47.0 ou `@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"
  }'
```

Pour les appels sortants, transmettez le champ `environment` lorsque vous lancez l’appel via les points de terminaison sortants Twilio ou trunk SIP.

### SDK React

Transmettez l’option `environment` dans le hook `useConversation` ou lors du démarrage d’une session :

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

## Exemple : agent multi-environnements

Cet exemple présente une configuration complète avec un seul agent qui utilise différents backends d’API et identifiants en développement, en préproduction et en production.

#### Créer des variables d’environnement

Créez trois variables d’environnement dans le Dashboard ou via l’API :

| Libellé       | Type                         | Développement   | Préproduction       | Production       |
| ------------- | ---------------------------- | --------------- | ------------------- | ---------------- |
| `api_host`    | Chaîne                       | `dev.api`       | `staging.api`       | `api`            |
| `api_key`     | Secret                       | `dev-secret-id` | `staging-secret-id` | `prod-secret-id` |
| `oauth_creds` | Connexion d’authentification | `dev-oauth-id`  | `staging-oauth-id`  | `prod-oauth-id`  |

#### Configurer les outils avec des références de variables d’environnement

Configurez vos outils webhook à l’aide de la syntaxe de modèle :

* **URL** : `https://{{system__env_api_host}}.example.com/v1/orders`
* **En-têtes** : référencez la variable d’environnement `api_key` pour l’en-tête `X-Api-Key`
* **Authentification** : référencez la variable d’environnement `oauth_creds` pour l’authentification OAuth

#### Spécifier l’environnement au début de la conversation

Lorsque vous démarrez une conversation, transmettez l’environnement cible :

**`Développement`**

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

**`Préproduction`**

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

**`Production (par défaut)`**

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

#### Filtrer par environnement

L’environnement est suivi pour chaque conversation. Filtrez vos tableaux de bord analytiques et l’historique des conversations par environnement afin d’isoler les métriques de chaque étape de déploiement.

![Filtrer les analyses par environnement](/docs/_fern-img/640f45e330a6f58648bb79fb588b580bb1d938e20f46c453b6d0c0efdac04054.webp)

![Filtrer l’historique des conversations par environnement](/docs/_fern-img/de6cdcdad31761a4e94928ea125503a555635eaf579521096b5f38d5ef931cd0.webp)

### Contraintes de nommage

* **Libellés** : caractères alphanumériques et traits de soulignement uniquement (par exemple, `base_url`, `api_key_v2`)
* **Noms d’environnement** : doivent commencer par une lettre minuscule et ne peuvent contenir que des lettres minuscules, des chiffres, des traits de soulignement et des traits d’union, dans la limite de 64 caractères (par exemple, `production`, `staging`, `dev-us-east`)
* Chaque variable d’environnement doit avoir une valeur `production`

## Étapes suivantes

#### [Outils webhook](/docs/fr/eleven-agents/customization/tools/webhook-tools)

Configurez des outils webhook avec des URL et une authentification adaptées à l’environnement

#### [Serveurs MCP](/docs/fr/eleven-agents/customization/tools/mcp)

Connectez des serveurs MCP avec une configuration propre à chaque environnement

#### [LLM personnalisé](/docs/fr/eleven-agents/customization/llm/custom-llm)

Utilisez différents points de terminaison de modèles selon les environnements

#### [Gestion des versions](/docs/fr/eleven-agents/operate/versioning)

Combinez les variables d’environnement avec les branches et la répartition du trafic