एनवायरनमेंट वेरिएबल

एनवायरनमेंट वेरिएबल से आप टूल URL, सीक्रेट, हेडर और ऑथ कनेक्शन के लिए हर एनवायरनमेंट की वैल्यू तय कर सकते हैं। एक ही एजेंट और टूल कॉन्फ़िगरेशन आपके सभी एनवायरनमेंट में काम करता है — URL, API key और ऑथेंटिकेशन बातचीत के समय बताए गए एनवायरनमेंट के आधार पर डाइनैमिक रूप से रिज़ॉल्व होते हैं।

परिचय

एनवायरनमेंट वेरिएबल के बिना, किसी एजेंट को कई एनवायरनमेंट (development, staging, production) में डिप्लॉय करने के लिए हर एनवायरनमेंट हेतु एजेंट और टूल डुप्लिकेट करने पड़ते हैं, फिर उनके कॉन्फ़िगरेशन को मैन्युअली सिंक में रखना पड़ता है। इससे ये समस्याएं होती हैं:

• एनवायरनमेंट के बीच कॉन्फ़िगरेशन में अंतर
• डुप्लिकेट एजेंट ID में बंटे हुए एनालिटिक्स
• staging से production में जाने पर प्रमोशन की मुश्किलें

एनवायरनमेंट वेरिएबल, हर एनवायरनमेंट के लिए अलग वैल्यू स्टोर करने वाला दोबारा इस्तेमाल किया जा सकने वाला, वर्कस्पेस-स्कोप्ड रिसोर्स देकर इसे हल करते हैं। टूल और MCP सर्वर टेम्पलेट सिंटैक्स का इस्तेमाल करके इन वेरिएबल को रेफ़र करते हैं और बातचीत के एनवायरनमेंट के आधार पर रनटाइम में सही वैल्यू रिज़ॉल्व होती है।

मुख्य अवधारणाएं

एनवायरनमेंट वेरिएबल

एनवायरनमेंट वेरिएबल एक वर्कस्पेस-स्कोप्ड रिसोर्स है, जिसमें एक लेबल और हर एनवायरनमेंट के लिए वैल्यू का सेट होता है। इसके तीन प्रकार हैं:

हर एनवायरनमेंट वेरिएबल में डिफ़ॉल्ट production एनवायरनमेंट के लिए वैल्यू होना ज़रूरी है। अतिरिक्त एनवायरनमेंट (जैसे, staging, development) वैकल्पिक हैं।

टेम्पलेट सिंटैक्स

URL फ़ील्ड में एनवायरनमेंट वेरिएबल को {{system__env_<label>}} सिंटैक्स से रेफ़र करें:

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

api_host एनवायरनमेंट वेरिएबल की वैल्यू api (production) और staging.api (staging) होने पर, यह ऐसे रिज़ॉल्व होता है:

• production में: https://api.example.com/v1/text-to-speech
• staging में: https://staging.api.example.com/v1/text-to-speech

यह सिंटैक्स डायनामिक वेरिएबल के अनुरूप है और वेबहुक टूल तथा MCP सर्वर कनेक्शन के URL फ़ील्ड में काम करता है।

रिज़ॉल्यूशन और फ़ॉलबैक

जब कोई बातचीत किसी खास एनवायरनमेंट में चलती है, तो सिस्टम एनवायरनमेंट वेरिएबल को इस तरह रिज़ॉल्व करता है:

1. मांगे गए एनवायरनमेंट (जैसे, staging) की वैल्यू खोजें
2. उस एनवायरनमेंट के लिए कोई वैल्यू न होने पर, production वैल्यू पर फ़ॉलबैक करें
3. वेरिएबल रिज़ॉल्व न होने पर, टूल कॉल कॉन्फ़िगरेशन एरर के साथ विफल होती है

इस फ़ॉलबैक व्यवहार का मतलब है कि आपको सिर्फ़ उन एनवायरनमेंट के लिए वैल्यू तय करनी है जो production से अलग हैं।

एनवायरनमेंट वेरिएबल बनाना

एनवायरनमेंट वेरिएबल का इस्तेमाल

वेबहुक टूल 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 (Signed URL / Token)

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 के साथ काम करते हैं।

इनबाउंड कॉल के लिए, एनवायरनमेंट इस क्रम में रिज़ॉल्व होता है:

1. आपका सर्वर अगर हर कॉल के लिए डायनामिक रूप से कोई वैल्यू देता है, तो आपके कन्वर्सेशन इनिशिएशन वेबहुक से लौटाई गई environment वैल्यू
2. फोन नंबर पर स्टोर किया गया एनवायरनमेंट
3. डिफ़ॉल्ट रूप में 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 बैकएंड और क्रेडेंशियल का इस्तेमाल करता है।

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 वैल्यू होना ज़रूरी है

अगले चरण