कोड टूल्स

कोड टूल्स आपके एजेंट को सैंडबॉक्स किए गए सर्वर-साइड एनवायरनमेंट में कस्टम JavaScript चलाने देते हैं, बिना अपना वेबहुक एंडपॉइंट सेट अप और होस्ट किए। बिल्ट-इन कोड एडिटर में एक बार लॉजिक लिखें, और जब भी एजेंट टूल कॉल करता है, ElevenLabs उसे चलाता है।

परिचय

कोड टूल एक JavaScript फ़ंक्शन है, जो एजेंट के कॉल करने पर चलता है। आप पूरा फ़ंक्शन बॉडी लिखते हैं, इसलिए टूल काम के अनुसार कम या ज़्यादा कर सकता है:

• कस्टम कैलकुलेशन: सिर्फ़ टूल-कॉल पैरामीटर का इस्तेमाल करके प्राइसिंग नियम, यूनिट कन्वर्ज़न, स्कोरिंग लॉजिक या तारीख की गणना लागू करें। नेटवर्क एक्सेस की ज़रूरत नहीं।
• बाहरी API कॉल करना: अलाउलिस्ट किए गए डोमेन से fetch करें, जिसमें वर्कस्पेस सीक्रेट्स और ऑथ कनेक्शन फ़ंक्शन के कॉन्टेक्स्ट में इंजेक्ट होते हैं।
• कई सोर्स जोड़ना: दो या तीन API कॉल करें और एक जवाब लौटाने से पहले उनके नतीजों को मर्ज, तुलना या रिकंसाइल करें।
• कंडीशनल ब्रांचिंग: टूल-कॉल पैरामीटर के आधार पर अलग लॉजिक चलाएं, बिना हर ब्रांच के लिए अलग टूल की ज़रूरत के।
• डेटा को नया रूप देना: रॉ अपस्ट्रीम रिस्पॉन्स के बजाय, एजेंट को दिखाने के लिए बिल्कुल वही स्ट्रक्चर लौटाएं जो आप चाहते हैं।

यह कैसे काम करता है

आपका कोड एक JavaScript मॉड्यूल है, जो एक सिंगल डिफ़ॉल्ट async फ़ंक्शन एक्सपोर्ट करता है। फ़ंक्शन को ctx ऑब्जेक्ट मिलता है और वह टूल का नतीजा लौटाता है:

export default async (ctx) => {
  // ctx.args.<paramName> — the parameters the agent passed to this tool call
  const { city } = ctx.args;
  return { message: `Hello from ${city}!` };
};

आपके लौटाए गए वैल्यू टूल का नतीजा बनते हैं। यह एजेंट को वापस भेजा जाता है, बातचीत के ट्रांसक्रिप्ट में दिखता है और डायनामिक वेरिएबल असाइनमेंट के लिए इस्तेमाल किया जा सकता है।

ctx ऑब्जेक्ट

ctx उन सभी चीज़ों तक पहुंचने का आपका एंट्री पॉइंट है जिन्हें टूल कॉल के समय एक्सेस कर सकता है। एजेंट के दिए पैरामीटर हमेशा ctx.args में आते हैं; सीक्रेट्स, कॉन्फ़िगरेशन वैल्यू और ऑथ कनेक्शन वैकल्पिक हैं और सिर्फ़ तभी दिखते हैं जब आप उन्हें टूल के कॉन्टेक्स्ट ऑब्जेक्ट सेक्शन में मैप करते हैं।

पैरामीटर कॉन्फ़िगर करना

पैरामीटर वे वैल्यू हैं जो एजेंट टूल कॉल करते समय देता है और वे ctx.args में आते हैं। इन्हें टूल कॉन्फ़िगरेशन फ़ॉर्म के पैरामीटर्स सेक्शन में, या कोड एडिटर में Params टैब के Define Params सब-टैब में तय करें। हर पैरामीटर में डेटा टाइप, आइडेंटिफ़ायर और विवरण होता है, जिसका इस्तेमाल एजेंट बातचीत से सही वैल्यू तय करने के लिए करता है। आपका कोड उस वैल्यू को आइडेंटिफ़ायर के तहत पढ़ता है, जैसे नीचे ctx.args.appointment_datetime।

कॉन्टेक्स्ट ऑब्जेक्ट कॉन्फ़िगर करना

टूल के कॉन्टेक्स्ट ऑब्जेक्ट सेक्शन में सीक्रेट्स, कॉन्फ़िगरेशन वैल्यू और ऑथ कनेक्शन जोड़ें। हर एंट्री में एक टाइप और नाम होता है। पैनल हर एंट्री के लिए सटीक एक्सेसर दिखाता है, जैसे नीचे ctx.secrets.DEMO_KEY।

नेटवर्क एक्सेस

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

एग्ज़ीक्यूशन सीमाएं

• टाइमआउट: हर रन को टूल के कॉन्फ़िगर किए गए रिस्पॉन्स टाइमआउट के भीतर पूरा होना चाहिए, जो 1 से 30 सेकंड तक हो सकता है।
• कोई बाहरी पैकेज नहीं: कोड टूल्स अभी npm डिपेंडेंसी के बिना चलते हैं।

अपने कोड की टेस्टिंग

सेव करने से पहले, सैंपल पैरामीटर वैल्यू के साथ अपना कोड चलाने के लिए कोड एडिटर में Run इस्तेमाल करें:

• Params — आपके टूल के तय किए गए हर पैरामीटर के लिए टेस्ट वैल्यू सेट करें।
• Output — लौटाया गया नतीजा, या एग्ज़ीक्यूशन विफल होने पर एरर देखें।
• Logs — console.log, console.warn या console.error से लिखी गई हर चीज़, साथ ही बिल्ड और एग्ज़ीक्यूशन टाइमिंग देखें।

गाइड

इस गाइड में, हम एक ऐसा कोड टूल बनाएंगे जो तापमान कन्वर्ट करता है और एक आसान, फ़ॉर्मैट की गई स्ट्रिंग लौटाता है:

export default async (ctx) => {
  const { value, from_unit } = ctx.args;
  if (from_unit === "C") {
    const fahrenheit = (value * 9) / 5 + 32;
    return { result: `${value}°C is ${fahrenheit.toFixed(1)}°F` };
  }
  const celsius = ((value - 32) * 5) / 9;
  return { result: `${value}°F is ${celsius.toFixed(1)}°C` };
};

When the user asks to convert a temperature, call convert_temperature with the
value and its unit ("C" or "F"), and read back the result naturally.

ऑथेंटिकेशन उदाहरण

सीक्रेट के साथ API कॉल करना

export default async (ctx) => {
  const { order_id } = ctx.args;
  const response = await fetch(`https://api.example.com/orders/${order_id}`, {
    headers: {
      Authorization: `Bearer ${ctx.secrets.EXAMPLE_API_KEY}`,
    },
  });
  if (!response.ok) {
    throw new Error(`Upstream error: ${response.status}`);
  }
  return await response.json();
};

टूल के कॉन्टेक्स्ट ऑब्जेक्ट सेक्शन में EXAMPLE_API_KEY को वर्कस्पेस सीक्रेट से मैप करें, फिर एग्रेस के लिए रिक्वेस्ट की अनुमति देने हेतु api.example.com को कोड टूल अनुमति प्राप्त डोमेन में जोड़ें। आपके रेफ़रेंस की गई वैल्यू एक प्लेसहोल्डर है: एग्रेस पर असली सीक्रेट हेडर में डाला जाता है और वह आपके कोड को कभी नहीं दिखता।

OAuth ऑथ कनेक्शन के साथ API कॉल करना

export default async (ctx) => {
  const { customer_id } = ctx.args;
  const response = await fetch(`https://api.example.com/customers/${customer_id}`, {
    headers: {
      "X-With-Auth-Connection": ctx.authConnections.EXAMPLE_CRM,
    },
  });
  if (!response.ok) {
    throw new Error(`Upstream error: ${response.status}`);
  }
  return await response.json();
};

टूल के कॉन्टेक्स्ट ऑब्जेक्ट सेक्शन में EXAMPLE_CRM को कॉन्फ़िगर किए गए ऑथ कनेक्शन से मैप करें। आपके रेफ़रेंस की गई वैल्यू एक प्लेसहोल्डर है: एग्रेस पर असली क्रेडेंशियल हेडर में डाला जाता है और वह आपके कोड को कभी नहीं दिखता।

सर्वोत्तम तरीके

टूल को स्पष्ट नाम और विस्तृत विवरण दें

अगर असिस्टेंट सही टूल को कॉल नहीं करता, तो आपको टूल के नाम और विवरण अपडेट करने पड़ सकते हैं, ताकि असिस्टेंट बेहतर ढंग से समझ सके कि उसे हर टूल कब चुनना है। टूल और आर्ग्युमेंट के नाम छोटे करने के लिए संक्षिप्त रूप या एक्रोनिम का इस्तेमाल न करें।

आप यह भी विस्तार से बता सकते हैं कि टूल को कब कॉल करना चाहिए। जटिल टूल के लिए, हर आर्ग्युमेंट का विवरण शामिल करें, ताकि असिस्टेंट समझ सके कि उस आर्ग्युमेंट के लिए उसे यूज़र से क्या पूछना है।

टूल पैरामीटर को स्पष्ट नाम और विस्तृत विवरण दें

टूल पैरामीटर के लिए स्पष्ट और वर्णनात्मक नाम इस्तेमाल करें। अगर लागू हो, तो विवरण में पैरामीटर का अपेक्षित फ़ॉर्मैट बताएं (जैसे तारीख के लिए YYYY-mm-dd या dd/mm/yy)।

अपने असिस्टेंट के सिस्टम प्रॉम्प्ट में टूल को कैसे और कब कॉल करना है, इसकी अतिरिक्त जानकारी देने पर विचार करें

अपने सिस्टम प्रॉम्प्ट में स्पष्ट निर्देश देने से असिस्टेंट की टूल कॉलिंग सटीकता काफ़ी बेहतर हो सकती है। उदाहरण के लिए, असिस्टेंट को इस तरह के निर्देश दें:

Use `check_order_status` when the user inquires about the status of their order, such as 'Where is my order?' or 'Has my order shipped yet?'.

जटिल स्थितियों के लिए संदर्भ दें। उदाहरण के लिए:

Before scheduling a meeting with `schedule_meeting`, check the user's calendar for availability using check_availability to avoid conflicts.

LLM चयन

यह ध्यान रखना ज़रूरी है कि फंक्शन कॉल की सफलता के लिए LLM का चुनाव मायने रखता है। कुछ LLM बातचीत से संबंधित पैरामीटर निकालने में मुश्किल महसूस कर सकते हैं।