Variables de entorno

Las variables de entorno te permiten definir valores específicos para cada entorno en URL de herramientas, secretos, encabezados y conexiones de autenticación. Una única configuración de agente y herramientas funciona en todos tus entornos: las URL, claves de API y autenticación se resuelven dinámicamente según el entorno especificado al iniciar la conversación.

Resumen

Sin variables de entorno, implementar un agente en varios entornos (desarrollo, pruebas, producción) requiere duplicar agentes y herramientas para cada entorno y mantener sus configuraciones sincronizadas manualmente. Esto provoca:

• Desajustes de configuración entre entornos
• Analíticas fragmentadas entre ID de agente duplicados
• Dificultades de promoción al pasar de pruebas a producción

Las variables de entorno solucionan esto al incorporar un recurso reutilizable con alcance de espacio de trabajo que almacena valores distintos para cada entorno. Las herramientas y los servidores MCP hacen referencia a estas variables mediante sintaxis de plantilla, y el valor correcto se resuelve en tiempo de ejecución según el entorno de la conversación.

Conceptos básicos

Variables de entorno

Una variable de entorno es un recurso con alcance de espacio de trabajo que tiene una etiqueta y un conjunto de valores por entorno. Hay tres tipos:

Cada variable de entorno debe tener un valor para el entorno predeterminado production. Los entornos adicionales (por ejemplo, staging, development) son opcionales.

Sintaxis de plantilla

Haz referencia a variables de entorno en campos de URL mediante la sintaxis {{system__env_<label>}}:

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

Dada una variable de entorno api_host con los valores api (producción) y staging.api (pruebas), se resuelve así:

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

Esta sintaxis es coherente con las variables dinámicas y funciona en campos de URL para herramientas de webhook y conexiones de servidores MCP.

Resolución y alternativa

Cuando una conversación se ejecuta en un entorno concreto, el sistema resuelve las variables de entorno de la siguiente manera:

1. Busca el valor del entorno solicitado (por ejemplo, staging)
2. Si no existe ningún valor para ese entorno, usa como alternativa el valor de production
3. Si no se puede resolver la variable, la llamada a la herramienta falla con un error de configuración

Este comportamiento alternativo significa que solo necesitas definir valores para los entornos que sean distintos de producción.

Crear variables de entorno

Usar variables de entorno

En las URL de herramientas webhook

Usa la sintaxis de plantilla en el campo URL de una herramienta webhook para que la URL base se resuelva según el entorno.

Por ejemplo, una URL de herramienta configurada como:

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

se resuelve como https://api.example.com/v1/weather?lat=40.7&lon=-74.0 en producción y como https://staging.api.example.com/v1/weather?lat=40.7&lon=-74.0 en staging.

Puedes combinar varias variables de entorno y segmentos literales en una sola URL:

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

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

En las cabeceras de herramientas webhook

Las variables de entorno de tipo secreto pueden usarse en las cabeceras de las solicitudes. En lugar de codificar un ID de secreto, referencia una variable de entorno para que se usen secretos distintos en cada entorno. Al configurar una cabecera de herramienta en el panel de control, selecciona una variable de entorno en lugar de un secreto estático. En tiempo de ejecución, el valor de la cabecera se resuelve con el secreto almacenado para el entorno actual.

Ejemplo de API

Pasa una referencia de variable de entorno en el 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" }
    }
  }
}

En las conexiones de autenticación de herramientas webhook

Las conexiones de autenticación (OAuth2, JWT, Basic Auth) también pueden resolverse según el entorno. Esto resulta útil cuando tus entornos de staging y producción usan distintos clientes OAuth o rutas de tokens.

En la configuración de la herramienta, selecciona una variable de entorno de tipo auth_connection en lugar de seleccionar directamente una conexión de autenticación. La conexión de autenticación correcta para el entorno actual se resuelve en tiempo de ejecución.

Ejemplo de API

Referencia una variable de entorno en el 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" }
  }
}

En las conexiones de servidores MCP

Las variables de entorno funcionan con las conexiones de servidor MCP del mismo modo que con las herramientas webhook. Puedes usarlas en:

• URL del servidor: Usa una plantilla para que la URL del servidor MCP apunte a distintos servidores según el entorno
• Cabeceras de solicitud: Usa variables de entorno de tipo secreto para las cabeceras de autenticación
• Conexiones de autenticación: Usa variables de entorno de conexiones de autenticación para servidores MCP basados en OAuth

Por ejemplo, una URL de servidor MCP configurada como:

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

se resuelve en distintas rutas de servidor MCP según el entorno.

En configuraciones de LLM personalizadas

Al usar un LLM personalizado, las variables de entorno pueden usarse como plantilla para la clave de API y las cabeceras de solicitud. Esto te permite usar distintas rutas de modelo y credenciales en los diferentes entornos.

El campo URL del LLM personalizado admite la misma sintaxis de plantilla {{system__env_<label>}}. El campo api_key acepta una referencia de variable de entorno para que se usen claves de API diferentes en cada entorno.

Ejemplo de 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" }
        }
      }
    }
  }
}

Especificar el entorno

El entorno se establece al iniciar la conversación y se mantiene durante toda ella. Si no se especifica ningún entorno, se usa production de forma predeterminada.

Al hacer pruebas en el panel de control, selecciona el entorno en el menú desplegable de la vista previa del agente:

WebSocket

Pasa el parámetro de consulta environment al conectarte al WebSocket de la conversación:

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

WebRTC (URL firmada / token)

Al usar WebRTC, pasa el parámetro environment al solicitar un token de conversación:

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

Telefonía (Twilio y troncal SIP)

Los números de teléfono pueden fijarse a un entorno específico y a una rama de agente concreta, lo que facilita dirigir un número de teléfono de prueba a una rama de desarrollo de un agente cuyas herramientas se ejecutan contra una API de desarrollo.

Para las llamadas entrantes, el entorno se resuelve en este orden:

1. El valor de environment devuelto por tu webhook de inicio de conversación, si tu servidor proporciona uno dinámicamente para cada llamada
2. El entorno almacenado en el propio número de teléfono
3. production como valor predeterminado

La misma prioridad se aplica a branch_id. Las URL y cabeceras de los webhooks previos a la llamada, así como las URL de los webhooks posteriores a la llamada, resuelven entonces las plantillas {{system__env_*}} con el entorno elegido.

Fija un número de teléfono a un entorno y una rama (requiere el SDK de 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",
)

Para las llamadas salientes, pasa el campo environment al iniciar la llamada mediante las rutas de llamadas salientes de Twilio o de la troncal SIP.

SDK de React

Pasa la opción environment en el hook useConversation o al iniciar una sesión:

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

Ejemplo: agente para varios entornos

Este ejemplo muestra una configuración completa con un único agente que utiliza distintos backends de API y credenciales en desarrollo, staging y producción.

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

Restricciones de nomenclatura

• Etiquetas: Solo caracteres alfanuméricos y guiones bajos (por ejemplo, base_url, api_key_v2)
• Nombres de entorno: Deben comenzar con una letra minúscula y solo pueden contener letras minúsculas, dígitos, guiones bajos y guiones, con un máximo de 64 caracteres (por ejemplo, production, staging, dev-us-east)
• Todas las variables de entorno deben tener un valor para production

Próximos pasos