Zmienne środowiskowe

Zmienne środowiskowe pozwalają definiować wartości dla poszczególnych środowisk: adresy URL narzędzi, sekrety, nagłówki i połączenia uwierzytelniania. Jedna konfiguracja agenta i narzędzi działa we wszystkich środowiskach — adresy URL, klucze API i uwierzytelnianie są dynamicznie rozwiązywane na podstawie środowiska wskazanego podczas rozmowy.

Przegląd

Bez zmiennych środowiskowych wdrożenie agenta w wielu środowiskach (deweloperskim, stagingowym, produkcyjnym) wymaga powielania agentów i narzędzi dla każdego środowiska, a następnie ręcznego utrzymywania synchronizacji ich konfiguracji. Prowadzi to do:

• Rozbieżności konfiguracji między środowiskami
• Podzielonej analityki między zduplikowane identyfikatory agentów
• Problemów z promocją przy przejściu ze środowiska stagingowego na produkcyjne

Zmienne środowiskowe rozwiązują ten problem, wprowadzając zasób wielokrotnego użytku o zakresie workspace, który przechowuje różne wartości dla każdego środowiska. Narzędzia i serwery MCP odwołują się do tych zmiennych za pomocą składni szablonów, a właściwa wartość jest rozwiązywana w czasie działania na podstawie środowiska rozmowy.

Kluczowe pojęcia

Zmienne środowiskowe

Zmienna środowiskowa to zasób o zakresie workspace z etykietą i zestawem wartości dla poszczególnych środowisk. Istnieją trzy typy:

Każda zmienna środowiskowa musi mieć wartość dla domyślnego środowiska production. Dodatkowe środowiska (np. staging, development) są opcjonalne.

Składnia szablonów

Odwołuj się do zmiennych środowiskowych w polach URL za pomocą składni {{system__env_<label>}}:

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

Dla zmiennej środowiskowej api_host z wartościami api (production) i staging.api (staging) zostanie to rozwiązane jako:

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

Ta składnia jest zgodna ze zmiennymi dynamicznymi i działa w polach URL narzędzi webhook oraz połączeń serwerów MCP.

Rozwiązywanie i fallback

Gdy rozmowa odbywa się w konkretnym środowisku, system rozwiązuje zmienne środowiskowe w następujący sposób:

1. Wyszukuje wartość dla żądanego środowiska (np. staging)
2. Jeśli dla tego środowiska nie ma wartości, używa wartości production jako fallbacku
3. Jeśli nie można rozwiązać zmiennej, wywołanie narzędzia kończy się błędem konfiguracji

To zachowanie fallbacku oznacza, że wystarczy zdefiniować wartości dla środowisk różniących się od produkcyjnego.

Tworzenie zmiennych środowiskowych

Korzystanie ze zmiennych środowiskowych

W adresach URL narzędzi webhook

Użyj składni szablonu w polu URL narzędzia webhook, aby adres bazowy był rozwiązywany dla danego środowiska.

Na przykład URL narzędzia skonfigurowany jako:

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

jest rozwiązywany jako https://api.example.com/v1/weather?lat=40.7&lon=-74.0 w produkcji i https://staging.api.example.com/v1/weather?lat=40.7&lon=-74.0 w stagingu.

W jednym URL możesz łączyć wiele zmiennych środowiskowych i fragmentów tekstu:

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

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

W nagłówkach narzędzi webhook

Tajnych zmiennych środowiskowych można używać w nagłówkach żądań. Zamiast wpisywać na stałe identyfikator sekretu, wskaż zmienną środowiskową, aby używać innych sekretów w poszczególnych środowiskach. Podczas konfiguracji nagłówka narzędzia w panelu wybierz zmienną środowiskową zamiast statycznego sekretu. W czasie działania wartość nagłówka jest rozwiązywana do sekretu zapisanego dla bieżącego środowiska.

Przykład API

Przekaż odwołanie do zmiennej środowiskowej w polu 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" }
    }
  }
}

W połączeniach autoryzacji narzędzi webhook

Połączenia autoryzacji (OAuth2, JWT, Basic Auth) można też rozwiązywać dla każdego środowiska. Jest to przydatne, gdy środowiska stagingowe i produkcyjne używają innych klientów OAuth lub endpointów tokenów.

W konfiguracji narzędzia wybierz zmienną środowiskową typu auth_connection zamiast bezpośrednio wybierać połączenie autoryzacji. Właściwe połączenie autoryzacji dla bieżącego środowiska jest rozwiązywane w czasie działania.

Przykład API

Wskaż zmienną środowiskową w polu auth_connection:

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

W połączeniach serwerów MCP

Zmienne środowiskowe działają z połączeniami serwerów MCP tak samo jak z narzędziami webhook. Możesz ich używać w:

• URL serwera: Użyj szablonu URL serwera MCP, aby wskazywał inne serwery w zależności od środowiska
• Nagłówkach żądań: Użyj tajnych zmiennych środowiskowych w nagłówkach uwierzytelniania
• Połączeniach autoryzacji: Użyj zmiennych środowiskowych połączeń autoryzacji dla serwerów MCP opartych na OAuth

Na przykład URL serwera MCP skonfigurowany jako:

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

jest rozwiązywany do różnych endpointów serwera MCP zależnie od środowiska.

W konfiguracjach własnego LLM

Podczas używania własnego LLM zmienne środowiskowe mogą służyć jako szablony dla klucza API i nagłówków żądań. Pozwala to używać różnych endpointów modeli i danych uwierzytelniających w różnych środowiskach.

Pole URL własnego LLM obsługuje tę samą składnię szablonu {{system__env_<label>}}. Pole api_key przyjmuje odwołanie do zmiennej środowiskowej, więc w każdym środowisku używany jest inny klucz API.

Przykład 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" }
        }
      }
    }
  }
}

Określanie środowiska

Środowisko jest ustawiane przy rozpoczęciu rozmowy i pozostaje takie samo przez całą rozmowę. Jeśli nie podasz środowiska, domyślnie użyte zostanie production.

Podczas testowania w panelu wybierz środowisko z listy rozwijanej w podglądzie agenta:

WebSocket

Przekaż parametr zapytania environment podczas łączenia z WebSocketem rozmowy:

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

WebRTC (podpisany URL / token)

Podczas używania WebRTC przekaż parametr environment przy żądaniu tokenu rozmowy:

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 i trunk SIP)

Numery telefonów można przypiąć do konkretnego środowiska i gałęzi agenta, co ułatwia skierowanie testowego numeru telefonu do gałęzi deweloperskiej agenta, którego narzędzia działają na deweloperskim API.

W przypadku połączeń przychodzących środowisko jest rozwiązywane w tej kolejności:

1. Wartość environment zwrócona przez webhook inicjujący rozmowę, jeśli serwer dynamicznie podaje ją dla każdego połączenia
2. Środowisko zapisane dla samego numeru telefonu
3. Domyślne production

Ta sama kolejność obowiązuje dla branch_id. Adresy URL i nagłówki webhooków przed połączeniem oraz adresy URL webhooków po połączeniu rozwiązują następnie szablony {{system__env_*}} przy użyciu wybranego środowiska.

Przypnij numer telefonu do środowiska i gałęzi (wymaga Python SDK elevenlabs ≥ 2.47.0 lub @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",
)

W przypadku połączeń wychodzących przekaż pole environment podczas inicjowania połączenia przez endpointy wychodzące Twilio lub trunk SIP.

React SDK

Przekaż opcję environment w hooku useConversation lub podczas rozpoczynania sesji:

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

Przykład: agent dla wielu środowisk

Ten przykład pokazuje pełną konfigurację jednego agenta, który używa różnych backendów API i danych uwierzytelniających w środowiskach deweloperskim, stagingowym i produkcyjnym.

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

Ograniczenia nazewnictwa

• Etykiety: Tylko znaki alfanumeryczne i podkreślenia (np. base_url, api_key_v2)
• Nazwy środowisk: Muszą zaczynać się małą literą i mogą zawierać tylko małe litery, cyfry, podkreślenia oraz myślniki; maksymalnie 64 znaki (np. production, staging, dev-us-east)
• Każda zmienna środowiskowa musi mieć wartość production

Kolejne kroki