डायनामिक वेरिएबल्स

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

परिचय

डायनामिक वेरिएबल्स को आपके एजेंट के कई पहलुओं में जोड़ा जा सकता है:

• व्यवहार और संदर्भ को कस्टमाइज़ करने के लिए सिस्टम प्रॉम्प्ट
• अभिवादन को व्यक्तिगत बनाने के लिए पहले मैसेज
• यूज़र-विशिष्ट डेटा पास करने के लिए टूल पैरामीटर और हेडर

यहां कुछ उदाहरण हैं, जहां डायनामिक वेरिएबल्स उपयोगी होते हैं:

• यूज़र के नाम से अभिवादन को व्यक्तिगत बनाना
• जवाबों में अकाउंट की जानकारी शामिल करना
• टूल कॉल को डेटा पास करना
• सब्सक्रिप्शन टियर के आधार पर व्यवहार को कस्टमाइज़ करना
• बातचीत ID या कॉल अवधि जैसी सिस्टम जानकारी एक्सेस करना

सिस्टम डायनामिक वेरिएबल्स

आपके एजेंट के पास ये सिस्टम वेरिएबल्स अपने-आप उपलब्ध होते हैं:

• system__agent_id - बातचीत शुरू करने वाले एजेंट का यूनिक आइडेंटिफ़ायर (पूरी बातचीत के दौरान स्थिर रहता है)
• system__current_agent_id - मौजूदा सक्रिय एजेंट का यूनिक आइडेंटिफ़ायर (एजेंट ट्रांसफर के बाद बदलता है)
• system__caller_id - कॉलर का फ़ोन नंबर (सिर्फ़ वॉइस कॉल के लिए)
• system__called_number - गंतव्य फ़ोन नंबर (सिर्फ़ वॉइस कॉल के लिए)
• system__call_duration_secs - कॉल की अवधि, सेकंड में
• system__time_utc - मौजूदा UTC समय (ISO फ़ॉर्मैट)
• system__time - तय टाइमज़ोन में मौजूदा समय (मानव-पठनीय फ़ॉर्मैट, जैसे, “Friday, 12:33 12 December 2025”)
• system__timezone - यूज़र द्वारा दिया गया टाइमज़ोन (tzinfo के लिए मान्य होना चाहिए)
• system__conversation_id - ElevenLabs का यूनिक बातचीत आइडेंटिफ़ायर
• system__call_sid - कॉल SID (सिर्फ़ twilio कॉल के लिए)
• system__call_id - SIP ट्रंक कॉल का यूनिक आइडेंटिफ़ायर (सिर्फ़ SIP ट्रंक कॉल के लिए)
• system__agent_turns - इस बातचीत में एजेंट द्वारा लिए गए बातचीत टर्न की कुल संख्या।
• system__current_agent_turns - मौजूदा एजेंट द्वारा लिए गए बातचीत टर्न की संख्या। बातचीत किसी दूसरे एजेंट को ट्रांसफर होने पर यह रीसेट हो जाती है।
• system__current_subagent_turns - मौजूदा सबएजेंट द्वारा लिए गए बातचीत टर्न की संख्या। वर्कफ़्लो के किसी दूसरे नोड पर जाने पर यह रीसेट हो जाती है।
• system__is_text_only - अगर बातचीत सिर्फ़ टेक्स्ट मोड में चल रही है, तो true; अन्यथा false।
• system__conversation_history - मौजूदा बातचीत इतिहास का JSON-सीरियलाइज़्ड रूप। इसका आकलन केवल रेफ़रेंस किए जाने के समय होता है। नीचे फ़ॉर्मैट विवरण देखें।

सिस्टम वेरिएबल्स:

• रनटाइम कॉन्फ़िगरेशन के बिना उपलब्ध होते हैं
• इनके आगे system__ लगा होता है (आरक्षित प्रीफ़िक्स)
• बातचीत के दौरान अपने-आप अपडेट होते हैं

बातचीत इतिहास का फ़ॉर्मैट

system__conversation_history वेरिएबल में निम्न संरचना वाला JSON ऑब्जेक्ट होता है:

{
  "x-elevenlabs-history": true,
  "entries": [
    { "role": "user", "message": "Hello" },
    { "role": "agent", "message": "Hi, how can I help?" },
    {
      "role": "agent",
      "tool_requests": [{ "tool_name": "lookup_order", "params_as_json": { "order_id": "123" } }]
    },
    {
      "role": "tool",
      "tool_results": [{ "tool_name": "lookup_order", "result_value": "{\"status\": \"shipped\"}" }]
    }
  ]
}

हर एंट्री में एक role ("user", "agent", या "tool") और इनमें से एक शामिल होता है:

• message — टर्न का टेक्स्ट कॉन्टेंट
• tool_requests — एजेंट द्वारा किए गए टूल कॉल का एक ऐरे, जिसमें हल किए गए पैरामीटर वैल्यू होते हैं
• tool_results — टूल रिस्पॉन्स का एक ऐरे

अगर किसी टूल रिज़ल्ट या पैरामीटर में नेस्टेड बातचीत इतिहास है, तो असीमित रिकर्सिव विस्तार से बचने के लिए उसे प्लेसहोल्डर से रिडैक्ट कर दिया जाता है (जैसे, [conversation_history (5 turns)])।

यह वेरिएबल टूल्स (जैसे वेबहुक, कस्टम LLM) को बातचीत का संदर्भ पास करने या हैंडऑफ़ के दौरान सब-एजेंट प्रॉम्प्ट में बातचीत इतिहास शामिल करने के लिए उपयोगी है।

सीक्रेट डायनामिक वेरिएबल्स

सीक्रेट डायनामिक वेरिएबल्स सामान्य डायनामिक वेरिएबल्स की तरह ही पॉप्युलेट होते हैं, लेकिन ये हमारे ElevenAgents को बताते हैं कि इनका इस्तेमाल सिर्फ़ डायनामिक वेरिएबल हेडर में किया जाना चाहिए और इन्हें एजेंट के सिस्टम प्रॉम्प्ट या पहले मैसेज के हिस्से के रूप में कभी भी LLM प्रोवाइडर को नहीं भेजना चाहिए।

हम इन्हें ऐसे ऑथ टोकन या प्राइवेट ID के लिए इस्तेमाल करने की सलाह देते हैं जिन्हें LLM को नहीं भेजा जाना चाहिए। सीक्रेट डायनामिक वेरिएबल बनाने के लिए, बस डायनामिक वेरिएबल के आगे secret__ लगाएं।

टूल्स से डायनामिक वेरिएबल्स अपडेट करना

अगर टूल कॉल वैध JSON ऑब्जेक्ट लौटाते हैं, तो वे डायनामिक वेरिएबल्स बना या अपडेट कर सकते हैं। क्या एक्सट्रैक्ट करना है, यह तय करने के लिए डॉट नोटेशन से ऑब्जेक्ट पाथ सेट करें। अगर फ़ील्ड या पाथ मौजूद नहीं है, तो कुछ भी अपडेट नहीं होता।

रिस्पॉन्स ऑब्जेक्ट और डॉट नोटेशन का उदाहरण:

• स्टेटस इस पाथ से मेल खाता है: response.status
• users ऐरे में पहले यूज़र का ईमेल इस पाथ से मेल खाता है: response.users.0.email

{
  "response": {
    "status": 200,
    "message": "Successfully found 5 users",
    "users": [
      "user_1": {
        "user_name": "test_user_1",
        "email": "test_user_1@email.com"
      }
    ]
  }
}

डायनामिक वेरिएबल को पहले यूज़र के ईमेल से अपडेट करने के लिए, असाइनमेंट इस तरह सेट करें।

असाइनमेंट हर वेबहुक टूल का एक फ़ील्ड हैं, जिसका दस्तावेज़ यहां दिया गया है।

गाइड

आवश्यक शर्तें

• एक ElevenLabs अकाउंट
• कॉन्फ़िगर किया हुआ ElevenLabs कन्वर्सेशनल एजेंट (यहां बनाएं)

import os
import signal
from elevenlabs.client import ElevenLabs
from elevenlabs.conversational_ai.conversation import Conversation, ConversationInitiationData
from elevenlabs.conversational_ai.default_audio_interface import DefaultAudioInterface
agent_id = os.getenv("AGENT_ID")
api_key = os.getenv("ELEVENLABS_API_KEY")
elevenlabs = ElevenLabs(api_key=api_key)
dynamic_vars = {
    "user_name": "Angelo",
}
config = ConversationInitiationData(
    dynamic_variables=dynamic_vars
)
conversation = Conversation(
    elevenlabs,
    agent_id,
    config=config,
    # Assume auth is required when API_KEY is set.
    requires_auth=bool(api_key),
    # Use the default audio interface.
    audio_interface=DefaultAudioInterface(),
    # Simple callbacks that print the conversation to the console.
    callback_agent_response=lambda response: print(f"Agent: {response}"),
    callback_agent_response_correction=lambda original, corrected: print(f"Agent: {original} -> {corrected}"),
    callback_user_transcript=lambda transcript: print(f"User: {transcript}"),
    # Uncomment the below if you want to see latency measurements.
    # callback_latency_measurement=lambda latency: print(f"Latency: {latency}ms"),
)
conversation.start_session()
signal.signal(signal.SIGINT, lambda sig, frame: conversation.end_session())

पब्लिक Talk-to पेज इंटीग्रेशन

पब्लिक Talk-to पेज URL पैरामीटर के जरिए डायनामिक वेरिएबल्स को सपोर्ट करता है, जिससे एजेंट लिंक शेयर करते समय आप बातचीत को व्यक्तिगत बना सकते हैं। यह वेबसाइट, ईमेल या मार्केटिंग कैंपेन में व्यक्तिगत एजेंट एम्बेड करने के लिए खास तौर पर उपयोगी है।

URL पैरामीटर के तरीके

पब्लिक Talk-to पेज पर डायनामिक वेरिएबल्स पास करने के दो तरीके हैं:

तरीका 1: Base64-एन्कोडेड JSON

vars पैरामीटर का इस्तेमाल करके वेरिएबल्स को base64-एन्कोडेड JSON ऑब्जेक्ट के रूप में पास करें:

https://elevenlabs.io/app/talk-to?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6&vars=eyJ1c2VyX25hbWUiOiJKb2huIiwiYWNjb3VudF90eXBlIjoicHJlbWl1bSJ9

vars पैरामीटर में base64-एन्कोडेड JSON होता है:

{ "user_name": "John", "account_type": "premium" }

तरीका 2: अलग-अलग क्वेरी पैरामीटर

var_ प्रीफ़िक्स वाले क्वेरी पैरामीटर का इस्तेमाल करके वेरिएबल्स पास करें:

https://elevenlabs.io/app/talk-to?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6&var_user_name=John&var_account_type=premium

पैरामीटर प्राथमिकता

जब दोनों तरीकों का एक साथ इस्तेमाल किया जाता है, तो टकराव से बचने के लिए अलग-अलग var_ पैरामीटर base64-एन्कोडेड वेरिएबल्स पर प्राथमिकता लेते हैं:

https://elevenlabs.io/app/talk-to?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6&vars=eyJ1c2VyX25hbWUiOiJKYW5lIn0=&var_user_name=John

इस उदाहरण में, user_name “Jane” (base64-एन्कोडेड vars से) के बजाय “John” (var_user_name से) होगा।

इम्प्लीमेंटेशन उदाहरण

// Method 1: Base64-encoded JSON
function generateTalkToURL(agentId, variables) {
  const baseURL = 'https://elevenlabs.io/app/talk-to';
  const encodedVars = btoa(JSON.stringify(variables));
  return `${baseURL}?agent_id=${agentId}&vars=${encodedVars}`;
}
// Method 2: Individual parameters
function generateTalkToURLWithParams(agentId, variables) {
  const baseURL = 'https://elevenlabs.io/app/talk-to';
  const params = new URLSearchParams({ agent_id: agentId });
  Object.entries(variables).forEach(([key, value]) => {
    params.append(`var_${key}`, encodeURIComponent(value));
  });
  return `${baseURL}?${params.toString()}`;
}
// Usage
const variables = {
  user_name: "John Doe",
  account_type: "premium",
  session_id: "sess_123"
};
const urlMethod1 = generateTalkToURL("agent_7101k5zvyjhmfg983brhmhkd98n6", variables);
const urlMethod2 = generateTalkToURLWithParams("agent_7101k5zvyjhmfg983brhmhkd98n6", variables);

समर्थित टाइप

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

समस्या निवारण