Variabili d'ambiente

Le variabili d’ambiente ti consentono di definire valori specifici per ambiente per URL degli strumenti, segreti, header e connessioni di autenticazione. Un’unica configurazione di agente e strumenti funziona in tutti i tuoi ambienti: URL, chiavi API e autenticazione vengono risolti dinamicamente in base all’ambiente specificato al momento della conversazione.

Panoramica

Senza variabili d’ambiente, distribuire un agente in più ambienti (sviluppo, staging, produzione) richiede di duplicare agenti e strumenti per ogni ambiente e poi mantenere manualmente sincronizzate le loro configurazioni. Ciò comporta:

• Deriva della configurazione tra gli ambienti
• Analytics frammentate tra ID agente duplicati
• Attrito nella promozione durante il passaggio dallo staging alla produzione

Le variabili d’ambiente risolvono questo problema introducendo una risorsa riutilizzabile a livello di workspace che archivia valori diversi per ambiente. Gli strumenti e i server MCP fanno riferimento a queste variabili usando la sintassi dei template e il valore corretto viene risolto in fase di runtime in base all’ambiente della conversazione.

Concetti principali

Variabili d’ambiente

Una variabile d’ambiente è una risorsa a livello di workspace con un’etichetta e un insieme di valori per ambiente. Esistono tre tipi:

Ogni variabile d’ambiente deve avere un valore per l’ambiente predefinito production. Gli ambienti aggiuntivi, come staging e development, sono facoltativi.

Sintassi dei template

Fai riferimento alle variabili d’ambiente nei campi URL usando la sintassi {{system__env_<label>}}:

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

Data una variabile d’ambiente api_host con i valori api (produzione) e staging.api (staging), viene risolta come segue:

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

Questa sintassi è coerente con le variabili dinamiche e funziona nei campi URL per gli strumenti webhook e le connessioni ai server MCP.

Risoluzione e fallback

Quando una conversazione viene eseguita in un ambiente specifico, il sistema risolve le variabili d’ambiente come segue:

1. Cerca il valore per l’ambiente richiesto, ad esempio staging
2. Se non esiste alcun valore per quell’ambiente, usa come fallback il valore production
3. Se la variabile non può essere risolta, la chiamata dello strumento non riesce con un errore di configurazione

Questo comportamento di fallback significa che devi definire valori solo per gli ambienti che differiscono dalla produzione.

Creazione di variabili d’ambiente

Utilizzo delle variabili d’ambiente

Negli URL degli strumenti webhook

Usa la sintassi dei template nel campo URL di uno strumento webhook per fare in modo che l’URL di base venga risolto in base all’ambiente.

Ad esempio, un URL dello strumento configurato come segue:

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

viene risolto in https://api.example.com/v1/weather?lat=40.7&lon=-74.0 in produzione e in https://staging.api.example.com/v1/weather?lat=40.7&lon=-74.0 in staging.

Puoi combinare più variabili d’ambiente e segmenti letterali in un unico URL:

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

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

Negli header degli strumenti webhook

Le variabili d’ambiente segrete possono essere usate negli header delle richieste. Anziché inserire direttamente un ID segreto, fai riferimento a una variabile d’ambiente per usare segreti diversi in base all’ambiente. Quando configuri un header dello strumento nella dashboard, seleziona una variabile d’ambiente anziché un segreto statico. In fase di runtime, il valore dell’header viene risolto nel segreto memorizzato per l’ambiente corrente.

Esempio API

Passa un riferimento a una variabile d’ambiente nel campo 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" }
    }
  }
}

Nelle connessioni di autenticazione degli strumenti webhook

Anche le connessioni di autenticazione (OAuth2, JWT, Basic Auth) possono essere risolte in base all’ambiente. È utile quando gli ambienti di staging e produzione usano client OAuth o endpoint token diversi.

Nella configurazione dello strumento, seleziona una variabile d’ambiente di tipo auth_connection anziché selezionare direttamente una connessione di autenticazione. La connessione di autenticazione corretta per l’ambiente corrente viene risolta in fase di runtime.

Esempio API

Fai riferimento a una variabile d’ambiente nel campo auth_connection:

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

Nelle connessioni ai server MCP

Le variabili d’ambiente funzionano con le connessioni ai server MCP allo stesso modo degli strumenti webhook. Puoi usarle in:

• URL del server: Usa un template per l’URL del server MCP in modo che punti a server diversi per ambiente
• Header delle richieste: Usa variabili d’ambiente segrete per gli header di autenticazione
• Connessioni di autenticazione: Usa variabili d’ambiente per connessioni di autenticazione con server MCP basati su OAuth

Ad esempio, un URL del server MCP configurato come segue:

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

viene risolto in endpoint del server MCP diversi a seconda dell’ambiente.

Nelle configurazioni LLM personalizzate

Quando usi un LLM personalizzato, le variabili d’ambiente possono creare template per la chiave API e gli header delle richieste. In questo modo puoi usare endpoint dei modelli e credenziali diversi nei vari ambienti.

Il campo URL dell’LLM personalizzato supporta la stessa sintassi di template {{system__env_<label>}}. Il campo api_key accetta un riferimento a una variabile d’ambiente, così da usare chiavi API diverse per ambiente.

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

Specificare l’ambiente

L’ambiente viene impostato all’avvio della conversazione e rimane invariato per l’intera conversazione. Se non viene specificato alcun ambiente, viene usato production per impostazione predefinita.

Durante i test nella dashboard, seleziona l’ambiente dal menu a discesa nell’anteprima dell’agente:

WebSocket

Passa il parametro query environment quando ti connetti al WebSocket della conversazione:

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

WebRTC (URL firmato / token)

Quando usi WebRTC, passa il parametro environment quando richiedi un token di conversazione:

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

Telefonia (Twilio e trunk SIP)

I numeri di telefono possono essere associati a un ambiente specifico e a uno specifico branch dell’agente, rendendo più semplice instradare un numero di telefono di test a un branch di sviluppo di un agente i cui strumenti vengono eseguiti su un’API di sviluppo.

Per le chiamate in entrata, l’ambiente viene risolto in questo ordine:

1. Il valore environment restituito dal tuo webhook di avvio della conversazione, se il tuo server ne fornisce uno dinamicamente per chiamata
2. L’ambiente memorizzato nel numero di telefono stesso
3. production come predefinito

La stessa precedenza si applica a branch_id. Gli URL e gli header del webhook pre-chiamata, nonché gli URL del webhook post-chiamata, risolvono quindi i template {{system__env_*}} usando l’ambiente scelto.

Associa un numero di telefono a un ambiente e a un branch (richiede l’SDK Python elevenlabs ≥ 2.47.0 o @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",
)

Per le chiamate in uscita, passa il campo environment quando avvii la chiamata tramite gli endpoint in uscita Twilio o trunk SIP.

SDK React

Passa l’opzione environment nell’hook useConversation o quando avvii una sessione:

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

Esempio: agente multi-ambiente

Questo esempio mostra una configurazione completa con un singolo agente che usa backend API e credenziali diversi tra sviluppo, staging e produzione.

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

Vincoli di denominazione

• Etichette: Solo caratteri alfanumerici e trattini bassi (ad es. base_url, api_key_v2)
• Nomi degli ambienti: Devono iniziare con una lettera minuscola e possono contenere solo lettere minuscole, cifre, trattini bassi e trattini, fino a 64 caratteri (ad es. production, staging, dev-us-east)
• Ogni variabile d’ambiente deve avere un valore production

Passaggi successivi