> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

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

![Resumen de variables de entorno](/docs/_fern-img/75bbfad6349ff43d078f62e75f7d3549858897158e55ada3dcdbf261a963b055.webp)

## 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:

| Tipo                          | Descripción                                                          | Caso de uso de ejemplo                                     |
| ----------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------- |
| **Cadena**                    | Valores de texto sin formato que varían según el entorno             | URL base, nombres de host, valores de configuración        |
| **Secreto**                   | Referencias a secretos del espacio de trabajo, resueltas por entorno | Claves de API, tokens bearer, secretos de firma de webhook |
| **Conexión de autenticación** | Referencias a conexiones de autenticación, resueltas por entorno     | Credenciales OAuth2, configuraciones JWT                   |

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](/docs/es/eleven-agents/customization/personalization/dynamic-variables) y funciona en campos de URL para herramientas de webhook y conexiones de servidores MCP.

> **Note**
>
> Las variables de entorno también se admiten en las URL y los encabezados de webhooks **previamente a la llamada** (el webhook de datos de cliente de inicio de conversación) y en las URL de webhooks **posteriores a la llamada** configuradas en **Desarrolladores > Webhooks**. Las plantillas se resuelven mediante el entorno de la conversación, por lo que la misma configuración de webhook puede dirigirse a rutas de API diferentes según el entorno. En el caso de los webhooks previos a la llamada, el entorno se puede establecer de antemano en el número de teléfono o devolver dinámicamente en la respuesta de tu webhook (consulta [Telefonía](#telephony-twilio-and-sip-trunk) más abajo).

> **Note**
>
> Las URL deben comenzar por `https://` antes de cualquier referencia a una variable de entorno. Por ejemplo, `https://   {{ system__env_api_host }}.example.com/v1/data` es válido, pero `{{ system__env_api_host }}/v1/data`
> no lo es. Esto es necesario para la validación y la seguridad: los valores de las variables de entorno no pueden controlar el protocolo.

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

> **Note**
>
> Las variables de entorno aún no se pueden gestionar mediante la CLI de ElevenLabs; usa el panel de control o el SDK.

#### Crear desde el panel de control

Ve a **Developers > Environment Variables** en el panel de control de ElevenLabs.

#### Crear un entorno

Define entornos que se ajusten a tus fases de despliegue (por ejemplo, `eu`, `india`, `staging`). El entorno `production` siempre está disponible de forma predeterminada.

#### Crear una variable

Haz clic en **Add variable** y elige el tipo de variable:

* **String**: Introduce una etiqueta y establece un valor para cada entorno
* **Secret**: Selecciona un secreto existente del espacio de trabajo para cada entorno
* **Auth connection**: Selecciona una conexión de autenticación existente para cada entorno

![Crear variable](/docs/_fern-img/8ab18d57956167aaa152e10b4d2890b208c8ba826ef0cbbf9082c8e1602f5246.webp)

#### Crear mediante la API

#### String

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.environment_variables.create(
    label="api_host",
    type="string",
    values={
        "production": "api",
        "staging": "staging.api",
        "development": "dev.api",
    },
)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.environmentVariables.create({
  label: "api_host",
  type: "string",
  values: {
    production: "api",
    staging: "staging.api",
    development: "dev.api",
  },
});
```

#### Secret

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.environment_variables.create(
    label="my_api_key",
    type="secret",
    values={
        "production": {"secret_id": "your-production-secret-id"},
        "staging": {"secret_id": "your-staging-secret-id"},
    },
)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.environmentVariables.create({
  label: "my_api_key",
  type: "secret",
  values: {
    production: { secretId: "your-production-secret-id" },
    staging: { secretId: "your-staging-secret-id" },
  },
});
```

#### Conexión de autenticación

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.environment_variables.create(
    label="my_oauth_connection",
    type="auth_connection",
    values={
        "production": {"auth_connection_id": "your-production-auth-connection-id"},
        "staging": {"auth_connection_id": "your-staging-auth-connection-id"},
    },
)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.environmentVariables.create({
  label: "my_oauth_connection",
  type: "auth_connection",
  values: {
    production: { authConnectionId: "your-production-auth-connection-id" },
    staging: { authConnectionId: "your-staging-auth-connection-id" },
  },
});
```

## Usar variables de entorno

### En las URL de herramientas webhook

Usa la sintaxis de plantilla en el campo URL de una [herramienta webhook](/docs/es/eleven-agents/customization/tools/webhook-tools) para que la URL base se resuelva según el entorno.

![Variable de entorno en la URL de la herramienta](/docs/_fern-img/8a9d4a7fbd589565c57f52aa82200c28fe7fcfcc80ff9a3ec41a99ca315a9f50.webp)

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

**`Python`**

```python title="Python"

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

**`JavaScript`**

```javascript title="JavaScript"
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const client = new ElevenLabsClient({ apiKey: "your-api-key" });

const agent = await client.conversationalAi.agents.create({
  conversationConfig: {
    agent: {
      firstMessage: "Hello! How can I help?",
      prompt: { prompt: "You are a helpful assistant." },
    },
    tools: [
      {
        type: "webhook",
        name: "get_data",
        description: "Fetches data from the API",
        apiSchema: {
          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`:

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

![Conexión de autenticación con variable de entorno](/docs/_fern-img/41115e31cac8c55360cb4f5783a4d03cf63ea51a6f5baa2812993d70d7c4a4d5.webp)

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`:

```json
{
  "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](/docs/es/eleven-agents/customization/tools/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](/docs/es/eleven-agents/customization/llm/custom-llm), 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

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

![Selector de entorno de la vista previa
del agente](/docs/_fern-img/052880e903ac2dc3539a0ed84feef5a3d31cd28c9b1345705c9003796d382803.webp)

### 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:

**`Python`**

```python title="Python"
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",
)

```

**`JavaScript`**

```javascript title="JavaScript"
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const client = new ElevenLabsClient({ apiKey: "your-api-key" });

const token = await client.conversationalAi.conversation.getToken({
    agentId: "your-agent-id",
    environment: "staging",
});
```

**`cURL`**

```bash title="cURL"
curl "https://api.elevenlabs.io/v1/convai/conversation/token?agent_id=<agent_id>&environment=staging" \
  -H "xi-api-key: $ELEVENLABS_API_KEY"
```

### 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](/docs/es/eleven-agents/operate/versioning) 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.

![Selectores de entorno y rama
del número de teléfono](/docs/_fern-img/ba83735f5cad2006555eb73a12a520c7c86fa3d576d8f69f481a8c75d315cf1d.webp)

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](/docs/es/eleven-agents/customization/personalization#conversation-initiation-webhooks), 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):

**`Python`**

```python title="Python"
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",
)
```

**`JavaScript`**

```typescript title="JavaScript"
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.phoneNumbers.update("phnum_8901k4t9z5defmb8vh3e9361y7nj", {
  environment: "staging",
  branchId: "agtbrch_8901k4t9z5defmb8vh3e9361y7nj",
});
```

**`cURL`**

```bash title="cURL"
curl -X PATCH "https://api.elevenlabs.io/v1/convai/phone-numbers/phnum_8901k4t9z5defmb8vh3e9361y7nj" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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:

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

#### Crear variables de entorno

Crea tres variables de entorno en el panel de control o mediante la API:

| Etiqueta      | Tipo                      | Desarrollo      | Staging             | Producción       |
| ------------- | ------------------------- | --------------- | ------------------- | ---------------- |
| `api_host`    | String                    | `dev.api`       | `staging.api`       | `api`            |
| `api_key`     | Secret                    | `dev-secret-id` | `staging-secret-id` | `prod-secret-id` |
| `oauth_creds` | Conexión de autenticación | `dev-oauth-id`  | `staging-oauth-id`  | `prod-oauth-id`  |

#### Configurar herramientas con referencias a variables de entorno

Configura tus herramientas webhook con sintaxis de plantilla:

* **URL**: `https://{{system__env_api_host}}.example.com/v1/orders`
* **Cabeceras**: Referencia la variable de entorno `api_key` para la cabecera `X-Api-Key`
* **Autenticación**: Referencia la variable de entorno `oauth_creds` para la autenticación OAuth

#### Especificar el entorno al iniciar la conversación

Al iniciar una conversación, pasa el entorno de destino:

**`Desarrollo`**

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

**`Staging`**

```python title="Staging"
conversation = client.conversational_ai.conversation.get_signed_url(
    agent_id="your-agent-id",
    environment="staging",
)
```

**`Producción (predeterminado)`**

```python title="Producción (predeterminado)"
# No environment parameter needed — defaults to production
conversation = client.conversational_ai.conversation.get_signed_url(
    agent_id="your-agent-id",
)
```

#### Filtrar por entorno

El entorno se registra para cada conversación. Filtra tus paneles de analítica y el historial de conversaciones por entorno para aislar las métricas de cada fase de despliegue.

![Filtrar la analítica por entorno](/docs/_fern-img/640f45e330a6f58648bb79fb588b580bb1d938e20f46c453b6d0c0efdac04054.webp)

![Filtrar el historial de conversaciones por entorno](/docs/_fern-img/de6cdcdad31761a4e94928ea125503a555635eaf579521096b5f38d5ef931cd0.webp)

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

#### [Herramientas webhook](/docs/es/eleven-agents/customization/tools/webhook-tools)

Configura herramientas webhook con URL y autenticación adaptadas al entorno

#### [Servidores MCP](/docs/es/eleven-agents/customization/tools/mcp)

Conecta servidores MCP con configuración para cada entorno

#### [LLM personalizado](/docs/es/eleven-agents/customization/llm/custom-llm)

Usa distintas rutas de modelo según el entorno

#### [Control de versiones](/docs/es/eleven-agents/operate/versioning)

Combina variables de entorno con ramas y división de tráfico