Omgevingsvariabelen

Met omgevingsvariabelen kun je waarden per omgeving definiëren voor tool-URL’s, secrets, headers en authenticatieverbindingen. Eén configuratie voor agent en tools werkt in al je omgevingen — URL’s, API-sleutels en authenticatie worden dynamisch opgelost op basis van de omgeving die tijdens het gesprek is opgegeven.

Overzicht

Zonder omgevingsvariabelen vereist het implementeren van een agent in meerdere omgevingen (development, staging, productie) dat je agents en tools voor elke omgeving dupliceert en hun configuraties vervolgens handmatig gesynchroniseerd houdt. Dit leidt tot:

• Configuratieverschillen tussen omgevingen
• Versnipperde analytics over gedupliceerde agent-ID’s
• Fricite bij promotie bij de overgang van staging naar productie

Omgevingsvariabelen lossen dit op door een herbruikbare resource op workspace-niveau te introduceren die verschillende waarden per omgeving opslaat. Tools en MCP-servers verwijzen met templatesyntaxis naar deze variabelen en de juiste waarde wordt tijdens runtime opgelost op basis van de omgeving van het gesprek.

Kernconcepten

Omgevingsvariabelen

Een omgevingsvariabele is een resource op workspace-niveau met een label en een set waarden per omgeving. Er zijn drie typen:

Elke omgevingsvariabele moet een waarde hebben voor de standaardomgeving production. Extra omgevingen (bijvoorbeeld staging, development) zijn optioneel.

Templatesyntaxis

Verwijs in URL-velden naar omgevingsvariabelen met de syntaxis {{system__env_<label>}}:

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

Bij een omgevingsvariabele api_host met de waarden api (production) en staging.api (staging), wordt dit opgelost naar:

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

Deze syntaxis is consistent met dynamische variabelen en werkt in URL-velden voor webhooktools en MCP-serververbindingen.

Oplossing en fallback

Wanneer een gesprek in een specifieke omgeving plaatsvindt, lost het systeem omgevingsvariabelen als volgt op:

1. Zoek de waarde voor de aangevraagde omgeving op (bijvoorbeeld staging)
2. Als er geen waarde voor die omgeving bestaat, val dan terug op de waarde voor production
3. Als de variabele niet kan worden opgelost, mislukt de toolcall met een configuratiefout

Dit fallbackgedrag betekent dat je alleen waarden hoeft te definiëren voor omgevingen die afwijken van productie.

Omgevingsvariabelen maken

Omgevingsvariabelen gebruiken

In URL’s van webhooktools

Gebruik de templatesyntaxis in het URL-veld van een webhooktool om de basis-URL per omgeving te laten oplossen.

Een tool-URL die bijvoorbeeld als volgt is geconfigureerd:

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

wordt in productie omgezet naar https://api.example.com/v1/weather?lat=40.7&lon=-74.0 en in staging naar https://staging.api.example.com/v1/weather?lat=40.7&lon=-74.0.

Je kunt meerdere omgevingsvariabelen en letterlijke segmenten combineren in één URL:

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

API-voorbeeld

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

In headers van webhooktools

Geheime omgevingsvariabelen kunnen in requestheaders worden gebruikt. Verwijs in plaats van een geheime ID hard te coderen naar een omgevingsvariabele, zodat per omgeving verschillende geheimen worden gebruikt. Selecteer bij het configureren van een toolheader in het dashboard een omgevingsvariabele in plaats van een statisch geheim. Tijdens runtime wordt de headerwaarde omgezet naar het geheim dat voor de huidige omgeving is opgeslagen.

API-voorbeeld

Geef een verwijzing naar een omgevingsvariabele door in het veld 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" }
    }
  }
}

In authverbindingen van webhooktools

Authverbindingen (OAuth2, JWT, Basic Auth) kunnen ook per omgeving worden omgezet. Dit is handig wanneer je staging- en productieomgevingen verschillende OAuth-clients of tokenendpoints gebruiken.

Selecteer in de toolconfiguratie een omgevingsvariabele van het type auth_connection in plaats van rechtstreeks een authverbinding te selecteren. Tijdens runtime wordt de juiste authverbinding voor de huidige omgeving omgezet.

API-voorbeeld

Verwijs naar een omgevingsvariabele in het veld auth_connection:

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

In MCP-serververbindingen

Omgevingsvariabelen werken met verbindingen van MCP-servers op dezelfde manier als met webhooktools. Je kunt ze gebruiken in:

• Server-URL: Gebruik een template voor de MCP-server-URL om per omgeving naar verschillende servers te verwijzen
• Requestheaders: Gebruik geheime omgevingsvariabelen voor authenticatieheaders
• Authverbindingen: Gebruik omgevingsvariabelen voor authverbindingen voor OAuth-gebaseerde MCP-servers

Een MCP-server-URL die bijvoorbeeld als volgt is geconfigureerd:

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

wordt afhankelijk van de omgeving omgezet naar verschillende MCP-serverendpoints.

In aangepaste LLM-configuraties

Wanneer je een aangepaste LLM gebruikt, kunnen omgevingsvariabelen een template bieden voor de API-sleutel en requestheaders. Zo kun je verschillende modelendpoints en inloggegevens gebruiken in verschillende omgevingen.

Het URL-veld voor de aangepaste LLM ondersteunt dezelfde templatesyntaxis {{system__env_<label>}}. Het veld api_key accepteert een verwijzing naar een omgevingsvariabele, zodat per omgeving verschillende API-sleutels worden gebruikt.

API-voorbeeld

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

De omgeving opgeven

De omgeving wordt ingesteld bij het starten van een gesprek en blijft gedurende het hele gesprek behouden. Als er geen omgeving is opgegeven, is de standaardwaarde production.

Selecteer bij het testen in het dashboard de omgeving in de dropdown in het agentvoorbeeld:

WebSocket

Geef de queryparameter environment door wanneer je verbinding maakt met de WebSocket voor gesprekken:

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

WebRTC (ondertekende URL / token)

Geef bij gebruik van WebRTC de parameter environment door wanneer je een gesprekstoken aanvraagt:

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

Telefonie (Twilio en SIP-trunk)

Telefoonnummers kunnen worden vastgezet op een specifieke omgeving en een specifieke agentbranch, zodat je een testtelefoonnummer eenvoudig kunt doorsturen naar een dev-branch van een agent waarvan de tools op een dev-API worden uitgevoerd.

Voor inkomende gesprekken wordt de omgeving in deze volgorde omgezet:

1. De waarde environment die wordt teruggestuurd door je webhook voor gespreksinitiatie, als je server er dynamisch één per gesprek levert
2. De omgeving die op het telefoonnummer zelf is opgeslagen
3. production als standaard

Dezelfde prioriteit geldt voor branch_id. URL’s en headers van webhooks vóór het gesprek, en URL’s van webhooks na het gesprek, zetten vervolgens de templates {{system__env_*}} om met de gekozen omgeving.

Zet een telefoonnummer vast op een omgeving en branch (vereist elevenlabs Python SDK ≥ 2.47.0 of @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",
)

Geef voor uitgaande gesprekken het veld environment door wanneer je het gesprek start via de uitgaande endpoints voor Twilio of SIP-trunk.

React SDK

Geef de optie environment door in de hook useConversation of wanneer je een sessie start:

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

Voorbeeld: agent voor meerdere omgevingen

Dit voorbeeld toont een volledige configuratie met één agent die verschillende API-backends en inloggegevens gebruikt voor ontwikkeling, staging en productie.

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

Naamgevingsbeperkingen

• Labels: Alleen alfanumerieke tekens en underscores (bijv. base_url, api_key_v2)
• Omgevingsnamen: Moeten met een kleine letter beginnen en mogen alleen kleine letters, cijfers, underscores en koppeltekens bevatten, met een maximum van 64 tekens (bijv. production, staging, dev-us-east)
• Elke omgevingsvariabele moet een waarde voor production hebben

Volgende stappen