환경 변수

리소스를 복제하지 않고도 동일한 에이전트를 개발, 스테이징, 프로덕션 환경에 배포하세요.

환경 변수를 사용하면 도구 URL, 시크릿, 헤더, 인증 연결의 환경별 값을 정의할 수 있습니다. 단일 에이전트 및 도구 구성으로 모든 환경에서 작동하며, URL, API 키 및 인증은 대화 시 지정된 환경에 따라 동적으로 확인됩니다.

개요

환경 변수가 없으면 여러 환경(개발, 스테이징, 프로덕션)에 에이전트를 배포할 때 환경마다 에이전트와 도구를 복제하고 구성을 수동으로 동기화해야 합니다. 이로 인해 다음 문제가 발생합니다.

환경 간 구성 불일치
복제된 에이전트 ID 전반에 걸친 분산된 분석 데이터
스테이징에서 프로덕션으로 이동할 때의 승격 마찰

환경 변수는 환경마다 서로 다른 값을 저장하는 재사용 가능한 워크스페이스 범위 리소스를 제공하여 이 문제를 해결합니다. 도구와 MCP 서버는 템플릿 구문을 사용해 이 변수를 참조하며, 대화의 환경에 따라 런타임에 올바른 값이 확인됩니다.

핵심 개념

환경 변수

환경 변수는 레이블과 환경별 값 집합을 갖는 워크스페이스 범위 리소스입니다. 세 가지 유형이 있습니다.

유형	설명	사용 사례
문자열	환경마다 달라지는 일반 텍스트 값	기본 URL, 호스트 이름, 구성 값
시크릿	환경마다 확인되는 워크스페이스 시크릿 참조	API 키, Bearer 토큰, 웹훅 서명 시크릿
인증 연결	환경마다 확인되는 인증 연결 참조	OAuth2 자격 증명, JWT 구성

각 환경 변수에는 기본 production 환경의 값이 있어야 합니다. 추가 환경(예: staging, development)은 선택 사항입니다.

템플릿 구문

URL 필드에서 {{system__env_<label>}} 구문을 사용하여 환경 변수를 참조하세요.

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

값이 api(프로덕션) 및 staging.api(스테이징)인 환경 변수 api_host가 주어지면 다음과 같이 확인됩니다.

production에서: https://api.example.com/v1/text-to-speech
staging에서: https://staging.api.example.com/v1/text-to-speech

이 구문은 동적 변수와 일관되며 웹훅 도구 및 MCP 서버 연결의 URL 필드에서 작동합니다.

환경 변수는 사전 통화 웹훅 URL 및 헤더(Conversation Initiation Client Data Webhook), 그리고 Developers > Webhooks에서 구성한 사후 통화 웹훅 URL에서도 지원됩니다. 템플릿은 대화의 환경을 사용하여 확인되므로 동일한 웹훅 구성으로 환경별로 다른 엔드포인트를 대상으로 지정할 수 있습니다. 사전 통화 웹훅의 경우 전화번호에서 환경을 미리 설정하거나 웹훅 응답에서 동적으로 반환할 수 있습니다(아래 전화 통신 참조).

URL은 환경 변수 참조 전에 https://로 시작해야 합니다. 예를 들어 https:// {{ system__env_api_host }}.example.com/v1/data는 유효하지만 {{ system__env_api_host }}/v1/data는 유효하지 않습니다. 이는 유효성 검사와 보안을 위해 필요합니다. 환경 변수 값은 프로토콜을 제어할 수 없습니다.

확인 및 폴백

대화가 특정 환경에서 실행되면 시스템은 다음과 같이 환경 변수를 확인합니다.

요청된 환경의 값을 조회합니다(예: staging).
해당 환경에 값이 없으면 **production 값으로 폴백합니다 **.
변수를 확인할 수 없으면 도구 호출이 구성 오류와 함께 실패합니다.

이 폴백 동작은 프로덕션과 다른 환경에 대해서만 값을 정의하면 된다는 의미입니다.

환경 변수 만들기

환경 변수는 아직 ElevenLabs CLI에서 관리할 수 없습니다. 대시보드 또는 SDK를 사용하세요.

대시보드에서 만들기

API로 만들기

ElevenLabs 대시보드에서 Developers > Environment Variables로 이동하세요.

환경 만들기

배포 단계에 맞는 환경을 정의하세요(예: eu, india, staging). production 환경은 항상 기본으로 제공됩니다.

변수 만들기

Add variable을 클릭하고 변수 유형을 선택하세요.

문자열: 레이블을 입력하고 각 환경의 값을 설정합니다.
시크릿: 각 환경에 사용할 기존 워크스페이스 시크릿을 선택합니다.
인증 연결: 각 환경에 사용할 기존 인증 연결을 선택합니다.

환경 변수 사용

웹훅 도구 URL에서

웹훅 도구의 URL 필드에서 템플릿 구문을 사용하면 환경별로 기본 URL을 확인할 수 있습니다.

예를 들어, 다음과 같이 구성된 도구 URL은 다음과 같습니다.

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

프로덕션에서는 https://api.example.com/v1/weather?lat=40.7&lon=-74.0로, 스테이징에서는 https://staging.api.example.com/v1/weather?lat=40.7&lon=-74.0로 확인됩니다.

하나의 URL에 여러 환경 변수와 리터럴 세그먼트를 결합할 수 있습니다.

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

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

웹훅 도구 헤더에서

요청 헤더에 비밀 환경 변수를 사용할 수 있습니다. 비밀 ID를 하드코딩하는 대신 환경 변수를 참조하면 환경별로 서로 다른 비밀을 사용할 수 있습니다. 대시보드에서 도구 헤더를 구성할 때 정적 비밀 대신 환경 변수를 선택하세요. 런타임에는 헤더 값이 현재 환경에 저장된 비밀로 확인됩니다.

API 예시

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

웹훅 도구 인증 연결에서

인증 연결(OAuth2, JWT, Basic Auth)도 환경별로 확인할 수 있습니다. 스테이징 및 프로덕션 환경에서 서로 다른 OAuth 클라이언트나 토큰 엔드포인트를 사용할 때 유용합니다.

도구 구성에서 인증 연결을 직접 선택하는 대신 auth_connection 유형의 환경 변수를 선택하세요. 현재 환경에 맞는 인증 연결이 런타임에 확인됩니다.

API 예시

auth_connection 필드에서 환경 변수를 참조합니다.

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

MCP 서버 연결에서

환경 변수는 웹훅 도구와 동일한 방식으로 MCP 서버 연결에서 작동합니다. 다음에서 사용할 수 있습니다.

서버 URL: 환경별로 서로 다른 서버를 가리키도록 MCP 서버 URL 템플릿 지정
요청 헤더: 인증 헤더에 비밀 환경 변수 사용
인증 연결: OAuth 기반 MCP 서버에 인증 연결 환경 변수 사용

예를 들어, 다음과 같이 구성된 MCP 서버 URL은 다음과 같습니다.

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

환경에 따라 서로 다른 MCP 서버 엔드포인트로 확인됩니다.

맞춤형 LLM 구성에서

맞춤형 LLM을 사용할 때 환경 변수로 API 키와 요청 헤더를 템플릿화할 수 있습니다. 이를 통해 환경마다 서로 다른 모델 엔드포인트와 자격 증명을 사용할 수 있습니다.

맞춤형 LLM URL 필드는 동일한 {{system__env_<label>}} 템플릿 구문을 지원합니다. api_key 필드는 환경 변수 참조를 허용하므로 환경별로 서로 다른 API 키를 사용할 수 있습니다.

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

환경 지정

환경은 대화 시작 시 설정되며 대화 전체에서 유지됩니다. 환경을 지정하지 않으면 기본값은 production입니다.

대시보드에서 테스트할 때 에이전트 미리보기의 드롭다운에서 환경을 선택하세요.

WebSocket

대화 WebSocket에 연결할 때 environment 쿼리 매개변수를 전달합니다.

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

WebRTC (서명된 URL / 토큰)

WebRTC를 사용할 때 대화 토큰을 요청하면서 environment 매개변수를 전달합니다.

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

전화 통신(Twilio 및 SIP 트렁크)

전화번호를 특정 환경과 특정 에이전트 브랜치에 고정할 수 있어, 도구가 개발 API에 대해 실행되는 에이전트의 개발 브랜치로 테스트 전화번호를 쉽게 라우팅할 수 있습니다.

수신 통화의 경우 환경은 다음 순서로 확인됩니다.

서버가 통화별로 동적으로 제공하는 경우, 대화 시작 웹훅에서 반환된 environment 값
전화번호 자체에 저장된 환경
기본값인 production

branch_id에도 동일한 우선순위가 적용됩니다. 통화 전 웹훅 URL 및 헤더와 통화 후 웹훅 URL은 선택된 환경을 사용하여 {{system__env_*}} 템플릿을 확인합니다.

전화번호를 환경 및 브랜치에 고정합니다(elevenlabs Python SDK ≥ 2.47.0 또는 @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",
)

발신 통화의 경우 Twilio 또는 SIP 트렁크 발신 엔드포인트를 통해 통화를 시작할 때 environment 필드를 전달합니다.

React SDK

useConversation 훅에서 또는 세션을 시작할 때 environment 옵션을 전달합니다.

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

예시: 다중 환경 에이전트

이 예시는 개발, 스테이징, 프로덕션 환경에서 서로 다른 API 백엔드와 자격 증명을 사용하는 단일 에이전트의 완전한 설정을 보여줍니다.

환경 변수 생성

대시보드 또는 API를 통해 환경 변수 3개를 생성합니다.

레이블	유형	개발	스테이징	프로덕션
`api_host`	문자열	`dev.api`	`staging.api`	`api`
`api_key`	비밀	`dev-secret-id`	`staging-secret-id`	`prod-secret-id`
`oauth_creds`	인증 연결	`dev-oauth-id`	`staging-oauth-id`	`prod-oauth-id`

환경 변수 참조로 도구 구성

템플릿 구문을 사용하여 웹훅 도구를 설정합니다.

URL: https://{{system__env_api_host}}.example.com/v1/orders
헤더: X-Api-Key 헤더에 api_key 환경 변수 참조
인증: OAuth 인증에 oauth_creds 환경 변수 참조

대화 시점에 환경 지정

대화를 시작할 때 대상 환경을 전달합니다.

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

환경별 필터링

모든 대화에서 환경이 추적됩니다. 환경별로 분석 대시보드와 대화 기록을 필터링하여 배포 단계별 지표를 분리하세요.

명명 제약 조건

레이블: 영숫자와 밑줄만 사용 가능(예: base_url, api_key_v2)
환경 이름: 소문자로 시작해야 하며, 최대 64자까지 소문자, 숫자, 밑줄, 하이픈만 포함할 수 있음(예: production, staging, dev-us-east)
모든 환경 변수에는 production 값이 있어야 함

다음 단계

웹훅 도구

환경을 인식하는 URL과 인증으로 웹훅 도구 구성

MCP 서버

환경별 구성으로 MCP 서버 연결

맞춤형 LLM

환경마다 서로 다른 모델 엔드포인트 사용

버전 관리

환경 변수를 브랜치 및 트래픽 분할과 결합