Variáveis de ambiente

As variáveis de ambiente permitem definir valores por ambiente para URLs de ferramentas, segredos, cabeçalhos e conexões de autenticação. Uma única configuração de agente e ferramentas funciona em todos os seus ambientes — URLs, chaves de API e autenticação são resolvidas dinamicamente com base no ambiente especificado no momento da conversa.

Visão geral

Sem variáveis de ambiente, implantar um agente em vários ambientes (desenvolvimento, homologação, produção) exige duplicar agentes e ferramentas para cada ambiente e, depois, manter manualmente as configurações sincronizadas. Isso resulta em:

• Divergência de configuração entre ambientes
• Análises fragmentadas entre IDs de agentes duplicados
• Dificuldade de promoção ao passar de homologação para produção

As variáveis de ambiente resolvem isso ao introduzir um recurso reutilizável com escopo de espaço de trabalho, que armazena valores diferentes para cada ambiente. Ferramentas e servidores MCP fazem referência a essas variáveis usando sintaxe de modelo, e o valor correto é resolvido em tempo de execução com base no ambiente da conversa.

Conceitos principais

Variáveis de ambiente

Uma variável de ambiente é um recurso com escopo de espaço de trabalho, com um rótulo e um conjunto de valores por ambiente. Há três tipos:

Cada variável de ambiente precisa ter um valor para o ambiente production padrão. Ambientes adicionais (por exemplo, staging, development) são opcionais.

Sintaxe de modelo

Faça referência a variáveis de ambiente em campos de URL usando a sintaxe {{system__env_<label>}}:

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

Com uma variável de ambiente api_host que tenha os valores api (produção) e staging.api (homologação), isso é resolvido como:

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

Essa sintaxe é compatível com as variáveis dinâmicas e funciona em campos de URL para ferramentas de webhook e conexões de servidor MCP.

Resolução e fallback

Quando uma conversa é executada em um ambiente específico, o sistema resolve as variáveis de ambiente da seguinte forma:

1. Busca o valor para o ambiente solicitado (por exemplo, staging)
2. Se não houver valor para esse ambiente, usa o valor de production como fallback
3. Se a variável não puder ser resolvida, a chamada da ferramenta falhará com um erro de configuração

Esse comportamento de fallback significa que você só precisa definir valores para ambientes que diferem da produção.

Como criar variáveis de ambiente

Como usar variáveis de ambiente

Em URLs de ferramentas de webhook

Use a sintaxe de modelo no campo de URL de uma ferramenta de webhook para que a URL base seja resolvida por ambiente.

Por exemplo, uma URL de ferramenta configurada como:

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

é resolvida como https://api.example.com/v1/weather?lat=40.7&lon=-74.0 em produção e como https://staging.api.example.com/v1/weather?lat=40.7&lon=-74.0 em staging.

Você pode combinar várias variáveis de ambiente e segmentos literais em uma única URL:

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

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

Em cabeçalhos de ferramentas de webhook

Variáveis de ambiente secretas podem ser usadas em cabeçalhos de solicitação. Em vez de codificar um ID de segredo diretamente, faça referência a uma variável de ambiente para que segredos diferentes sejam usados em cada ambiente. Ao configurar um cabeçalho de ferramenta no dashboard, selecione uma variável de ambiente em vez de um segredo estático. Em tempo de execução, o valor do cabeçalho é resolvido para o segredo armazenado no ambiente atual.

Exemplo de API

Passe uma referência de variável de ambiente no 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" }
    }
  }
}

Em conexões de autenticação de ferramentas de webhook

As conexões de autenticação (OAuth2, JWT, Basic Auth) também podem ser resolvidas por ambiente. Isso é útil quando os ambientes de staging e produção usam clientes OAuth ou endpoints de token diferentes.

Na configuração da ferramenta, selecione uma variável de ambiente do tipo auth_connection em vez de selecionar diretamente uma conexão de autenticação. A conexão de autenticação correta para o ambiente atual é resolvida em tempo de execução.

Exemplo de API

Faça referência a uma variável de ambiente no 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" }
  }
}

Em conexões de servidor MCP

As variáveis de ambiente funcionam com conexões de servidor MCP da mesma forma que funcionam com ferramentas de webhook. Você pode usá-las em:

• URL do servidor: Use um modelo para que a URL do servidor MCP aponte para servidores diferentes em cada ambiente
• Cabeçalhos de solicitação: Use variáveis de ambiente secretas para cabeçalhos de autenticação
• Conexões de autenticação: Use variáveis de ambiente de conexão de autenticação para servidores MCP baseados em OAuth

Por exemplo, uma URL de servidor MCP configurada como:

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

é resolvida para endpoints de servidor MCP diferentes conforme o ambiente.

Em configurações de LLM personalizada

Ao usar uma LLM personalizada, as variáveis de ambiente podem criar modelos para a chave de API e os cabeçalhos de solicitação. Isso permite usar endpoints de modelo e credenciais diferentes entre ambientes.

O campo de URL da LLM personalizada oferece suporte à mesma sintaxe de modelo {{system__env_<label>}}. O campo api_key aceita uma referência de variável de ambiente para que chaves de API diferentes sejam usadas em cada ambiente.

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

Como especificar o ambiente

O ambiente é definido no início da conversa e permanece durante toda a conversa. Se nenhum ambiente for especificado, o padrão será production.

Ao testar no dashboard, selecione o ambiente no menu suspenso da prévia do agente:

WebSocket

Passe o parâmetro de consulta environment ao se conectar ao WebSocket da conversa:

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

WebRTC (URL assinada / token)

Ao usar WebRTC, passe o parâmetro environment ao solicitar um token de conversa:

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 tronco SIP)

Os números de telefone podem ser fixados a um ambiente específico e a uma ramificação do agente específica, facilitando o roteamento de um número de telefone de teste para uma ramificação de desenvolvimento de um agente cujas ferramentas são executadas em uma API de desenvolvimento.

Para chamadas recebidas, o ambiente é resolvido nesta ordem:

1. O valor de environment retornado pelo seu webhook de início de conversa, se o servidor fornecer um dinamicamente para cada chamada
2. O ambiente armazenado no próprio número de telefone
3. production como padrão

A mesma precedência se aplica a branch_id. As URLs e os cabeçalhos de webhook pré-chamada e as URLs de webhook pós-chamada resolvem então os modelos {{system__env_*}} usando o ambiente escolhido.

Fixe um número de telefone a um ambiente e uma ramificação (requer o SDK Python elevenlabs ≥ 2.47.0 ou @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 chamadas realizadas, passe o campo environment ao iniciar a chamada pelos endpoints de saída do Twilio ou do tronco SIP.

SDK React

Passe a opção environment no hook useConversation ou ao iniciar uma sessão:

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

Exemplo: agente com vários ambientes

Este exemplo demonstra uma configuração completa com um único agente que usa diferentes back-ends de API e credenciais em desenvolvimento, staging e produção.

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

Restrições de nomenclatura

• Rótulos: Apenas caracteres alfanuméricos e sublinhados (por exemplo, base_url, api_key_v2)
• Nomes de ambiente: Devem começar com uma letra minúscula e podem conter apenas letras minúsculas, dígitos, sublinhados e hifens, com até 64 caracteres (por exemplo, production, staging, dev-us-east)
• Todas as variáveis de ambiente devem ter um valor para production

Próximas etapas