Miljövariabler

Med miljövariabler kan du definiera värden per miljö för verktygs-URL:er, hemligheter, rubriker och autentiseringsanslutningar. En enda agent- och verktygskonfiguration fungerar i alla dina miljöer – URL:er, API-nycklar och autentisering löses dynamiskt utifrån miljön som anges när samtalet startar.

Översikt

Utan miljövariabler kräver distribution av en agent i flera miljöer (utveckling, staging, produktion) att du duplicerar agenter och verktyg för varje miljö och sedan manuellt håller deras konfigurationer synkroniserade. Det leder till:

• Konfigurationsavvikelser mellan miljöer
• Fragmenterad analys över duplicerade agent-ID:n
• Friktion vid befordran när du flyttar från staging till produktion

Miljövariabler löser detta genom att införa en återanvändbar, workspaceomfattande resurs som lagrar olika värden per miljö. Verktyg och MCP-servrar refererar till dessa variabler med mallsyntax, och rätt värde löses vid körning utifrån samtalets miljö.

Grundläggande begrepp

Miljövariabler

En miljövariabel är en workspaceomfattande resurs med en etikett och en uppsättning värden per miljö. Det finns tre typer:

Varje miljövariabel måste ha ett värde för standardmiljön production. Ytterligare miljöer (t.ex. staging, development) är valfria.

Mallsyntax

Referera till miljövariabler i URL-fält med syntaxen {{system__env_<label>}}:

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

Med miljövariabeln api_host som har värdena api (produktion) och staging.api (staging) löses detta till:

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

Den här syntaxen är konsekvent med dynamiska variabler och fungerar i URL-fält för webhookverktyg och MCP-serveranslutningar.

Upplösning och återgång

När ett samtal körs i en specifik miljö löser systemet miljövariabler enligt följande:

1. Slå upp värdet för den begärda miljön (t.ex. staging)
2. Om inget värde finns för miljön återgå till värdet för production
3. Om variabeln inte kan lösas misslyckas verktygsanropet med ett konfigurationsfel

Detta återgångsbeteende innebär att du bara behöver definiera värden för miljöer som skiljer sig från produktion.

Skapa miljövariabler

Använda miljövariabler

I URL:er för webhook-verktyg

Använd mallsyntaxen i URL-fältet för ett webhook-verktyg för att låta bas-URL:en anpassas efter miljö.

Till exempel kan en verktygs-URL konfigurerad som:

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

översättas till https://api.example.com/v1/weather?lat=40.7&lon=-74.0 i produktion och https://staging.api.example.com/v1/weather?lat=40.7&lon=-74.0 i staging.

Du kan kombinera flera miljövariabler och bokstavliga segment i en enda URL:

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

API-exempel

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

I rubriker för webhook-verktyg

Hemliga miljövariabler kan användas i begäranderubriker. I stället för att hårdkoda ett hemligt ID kan du referera till en miljövariabel så att olika hemligheter används för varje miljö. När du konfigurerar en verktygsrubrik i dashboarden väljer du en miljövariabel i stället för en statisk hemlighet. Vid körning översätts rubrikvärdet till den hemlighet som lagras för den aktuella miljön.

API-exempel

Skicka en referens till en miljövariabel i fältet 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" }
    }
  }
}

I auth-anslutningar för webhook-verktyg

Auth-anslutningar (OAuth2, JWT, Basic Auth) kan också översättas per miljö. Det är användbart när dina staging- och produktionsmiljöer använder olika OAuth-klienter eller token-slutpunkter.

I verktygskonfigurationen väljer du en miljövariabel av typen auth_connection i stället för att välja en auth-anslutning direkt. Rätt auth-anslutning för den aktuella miljön översätts vid körning.

API-exempel

Referera till en miljövariabel i fältet auth_connection:

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

I MCP-serveranslutningar

Miljövariabler fungerar med anslutningar till MCP-servrar på samma sätt som med webhook-verktyg. Du kan använda dem i:

• Server-URL: Använd en mall för MCP-serverns URL för att peka på olika servrar per miljö
• Begäranderubriker: Använd hemliga miljövariabler för autentiseringsrubriker
• Auth-anslutningar: Använd miljövariabler för auth-anslutningar till OAuth-baserade MCP-servrar

Till exempel kan en MCP-server-URL konfigurerad som:

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

översättas till olika MCP-serverändpunkter beroende på miljön.

I anpassade LLM-konfigurationer

När du använder en anpassad LLM kan miljövariabler användas som mall för API-nyckeln och begäranderubriker. Det gör att du kan använda olika modelländpunkter och autentiseringsuppgifter i olika miljöer.

URL-fältet för anpassade LLM:er har stöd för samma mallsyntax, {{system__env_<label>}}. Fältet api_key accepterar en referens till en miljövariabel så att olika API-nycklar används per miljö.

API-exempel

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

Ange miljön

Miljön anges när konversationen startar och behålls under hela konversationen. Om ingen miljö anges används production som standard.

När du testar i dashboarden väljer du miljö i rullgardinsmenyn i agentförhandsvisningen:

WebSocket

Skicka frågeparametern environment när du ansluter till konversationens WebSocket:

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

WebRTC (signerad URL / token)

När du använder WebRTC skickar du parametern environment när du begär en konversationstoken:

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

Telefoni (Twilio och SIP-trunk)

Telefonnummer kan låsas till en specifik miljö och en specifik agentgren, vilket gör det enkelt att dirigera ett testtelefonnummer till en utvecklingsgren av en agent vars verktyg körs mot ett utvecklings-API.

För inkommande samtal fastställs miljön i följande ordning:

1. Värdet environment som returneras av din webhook för konversationsstart, om din server tillhandahåller ett dynamiskt för varje samtal
2. Miljön som lagras på själva telefonnumret
3. production som standard

Samma prioritet gäller för branch_id. URL:er och rubriker för webhookar före samtal samt URL:er för webhookar efter samtal översätter sedan mallarna {{system__env_*}} med den valda miljön.

Lås ett telefonnummer till en miljö och gren (kräver Python SDK:t elevenlabs ≥ 2.47.0 eller @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",
)

För utgående samtal skickar du fältet environment när du startar samtalet via slutpunkterna för utgående Twilio- eller SIP-trunksamtal.

React SDK

Skicka alternativet environment i hooken useConversation eller när du startar en 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>;
}

Exempel: agent för flera miljöer

Det här exemplet visar en komplett konfiguration med en enda agent som använder olika API-backends och autentiseringsuppgifter i utveckling, staging och produktion.

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

Namngivningsbegränsningar

• Etiketter: Endast alfanumeriska tecken och understreck (t.ex. base_url, api_key_v2)
• Miljönamn: Måste börja med en liten bokstav och får endast innehålla små bokstäver, siffror, understreck och bindestreck, upp till 64 tecken (t.ex. production, staging, dev-us-east)
• Varje miljövariabel måste ha ett production-värde

Nästa steg