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.

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 :

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 et fonctionne dans les champs URL des outils webhook et des connexions aux serveurs MCP.

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

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 afin que l’URL de base soit résolue selon l’environnement.

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

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

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 :

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

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 :

{
  "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 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é, 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

{
  "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 :

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 :

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

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

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, 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) :

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

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 :

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.

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

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