कोड के रूप में टूल्स
Python और JavaScript SDKs से एजेंट टूल्स बनाएं, संपादित करें और वर्शन करें
खास जानकारी
एक टूल अपने पैरामीटर्स के लिए नेस्टेड JSON स्कीमाओं वाले कॉन्फ़िग के रूप में स्टोर होता है। उस कॉन्फ़िग को हाथ से लिखने का मतलब है कि आपको पाथ पैरामीटर्स को URL के साथ, required सूचियों को उनकी प्रॉपर्टीज़ के साथ सिंक में रखना होगा और हर पैरामीटर को ठीक एक वैल्यू स्रोत देना होगा। Python और JavaScript SDKs में टूल बिल्डर आपको चेन किए गए मेथड कॉल्स से उसी टूल का विवरण देने देता है। फिर यह वह रिक्वेस्ट बनाता है जिसे tools.create() और tools.update() पहले से स्वीकार करते हैं।
इसका इस्तेमाल इन कामों के लिए करें:
- वेबहुक, क्लाइंट और सिस्टम टूल्स को कोड में परिभाषित करें और किसी भी अन्य कोड बदलाव की तरह उनका रिव्यू करें।
- कोई टूल लोड करें, एक पैरामीटर बदलें और उसके बाकी कॉन्फ़िग को बदले बिना उसे वापस पुश करें।
- टूल्स को वर्शन कंट्रोल में JSON के रूप में स्टोर करें और CI में उन्हें वैलिडेट करें।
बिल्डर पूरी तरह SDK में चलता है। यह कोई नया API एंडपॉइंट कॉल नहीं करता, और इससे बनाया गया कुछ भी डैशबोर्ड में खोला और संपादित किया जा सकता है।
ज़रूरी चीज़ें
- Python:
elevenlabsपैकेज। बिल्डर कोelevenlabs.agent_toolsसे इंपोर्ट किया जाता है। - JavaScript:
@elevenlabs/elevenlabs-jsपैकेज। बिल्डर को पैकेज रूट से एक्सपोर्ट किया जाता है।
वेबहुक टूल बनाएं
Tool.webhook(name, description) एक वेबहुक टूल शुरू करता है। नाम और विवरण वही हैं जो LLM तब देखता है, जब वह तय करता है कि टूल को कॉल करना है या नहीं। यह उदाहरण कॉलर के दिए नंबर से ऑर्डर खोजता है, वर्कस्पेस के सीक्रेट्स से API कुंजी भेजता है और ऑर्डर का स्टेटस एक डायनामिक वैरिएबल में स्टोर करता है:
रिक्वेस्ट मेथड्स HTTP मेथड और URL सेट करते हैं। URL में {name} प्लेसहोल्डर्स को पाथ पैरामीटर्स से भरा जाता है:
पहले से मौजूद नाम वाले पैरामीटर या हेडर को सेट करने पर वह बदल जाता है और अपनी जगह बनाए रखता है। remove_path_param(), remove_query_param(), remove_header() और remove_assignment() (JavaScript में removePathParam() वगैरह) किसी को हटा देते हैं। पाथ, क्वेरी और बॉडी में पैरामीटर नाम यूनिक होने चाहिए।
बॉडी एक ऑब्जेक्ट स्कीमा है, जिसे प्रॉपर्टी दर प्रॉपर्टी बनाया जाता है:
पैरामीटर स्कीमाएं
Schema उन पैरामीटर स्कीमाओं को बनाता है जिनका इस्तेमाल वेबहुक और क्लाइंट टूल्स करते हैं। हर मेथड एक नई स्कीमा लौटाता है और जिस स्कीमा पर उसे कॉल किया गया था उसे बिना बदले रखता है, इसलिए आप किसी स्कीमा को एक बार परिभाषित करके कई टूल्स में इस्तेमाल कर सकते हैं।
वैल्यू कहाँ से आती है
हर लिटरल को ठीक एक वैल्यू स्रोत चाहिए, वह चाहे कहीं भी हो: पैरामीटर में, बॉडी में, रिस्पॉन्स स्कीमा में या किसी ऑब्जेक्ट अथवा ऐरे के अंदर। किसी ऑब्जेक्ट या ऐरे का भी एक स्रोत हो सकता है, जो फिर पूरी वैल्यू देता है।
किसी ऑब्जेक्ट या ऐरे पर, describe() LLM के लिए कंटेनर का दस्तावेज़ीकरण करता है और हर प्रॉपर्टी या एलिमेंट का अपना स्रोत रहता है।
अन्य स्कीमा मेथड्स
हेडर्स और ऑथेंटिकेशन
हेडर वैल्यू चार में से किसी एक जगह से आती है। संवेदनशील जानकारी के लिए सीक्रेट या एनवायरनमेंट वैरिएबल इस्तेमाल करें, ताकि वैल्यू कभी टूल कॉन्फ़िग में दिखाई न दे:
AuthConnection.id(id) ID से वर्कस्पेस का एक ऑथ कनेक्शन इस्तेमाल करता है। AuthConnection.env_var(label) / AuthConnection.envVar(label) उसे एनवायरनमेंट वैरिएबल से चुनता है, ताकि वही टूल कॉन्फ़िग हर एनवायरनमेंट में अलग कनेक्शन इस्तेमाल कर सके।
क्लाइंट टूल बनाएं
Tool.client(name, description) एक क्लाइंट टूल शुरू करता है, जो सर्वर के बजाय आपके एप्लिकेशन में चलता है। इसके पैरामीटर्स को param(name, schema) से जोड़ें। जब एजेंट को आपके एप्लिकेशन के परिणाम का इंतज़ार करना हो, तब expects_response / expectsResponse सेट करें:
सिस्टम टूल बनाएं
सिस्टम टूल्स प्लेटफ़ॉर्म में पहले से शामिल होते हैं। हर टूल का SystemTool पर अपना कंस्ट्रक्टर होता है, जो उस टूल की सेटिंग्स लेता है:
दो ट्रांसफ़र टूल्स अपने डेस्टिनेशन transfer(condition, destination, options) से लेते हैं। कंडीशन LLM को बताती है कि वहाँ कब ट्रांसफ़र करना है, और डेस्टिनेशन वही Destination इस्तेमाल करता है जो कोड के रूप में वर्कफ़्लोज़ में होता है। SIP URI में ट्रांसफ़र के लिए SIP REFER ट्रांसफ़र चाहिए:
टूल विकल्प
हर तरह के टूल की साझा सेटिंग्स options() में जाती हैं: Python में कीवर्ड आर्ग्युमेंट्स के रूप में और JavaScript में ऑब्जेक्ट के रूप में। इनके नाम API में टूल कॉन्फ़िग के फ़ील्ड्स से मेल खाते हैं:
वेबहुक टूल का रिस्पॉन्स टाइमआउट 5 से 300 सेकंड होता है। क्लाइंट टूल का 1 से 120 सेकंड या जितना समय लगे उतना इंतज़ार करने के लिए -1 होता है, जिसके लिए expects_response / expectsResponse चाहिए। follow_redirects / followRedirects को अनुमत डोमेन्स की सूची चाहिए।
एजेंट से टूल्स जोड़ें
वेबहुक और क्लाइंट टूल्स tools.create() से अलग से बनाए जाते हैं और ID से एजेंट्स से जोड़े जाते हैं, इसलिए एक टूल कई एजेंट्स के साथ शेयर किया जा सकता है। सिस्टम टूल्स एजेंट के कॉन्फ़िग का हिस्सा होते हैं: build_config() / buildConfig() एजेंट के बिल्ट-इन टूल्स के लिए एंट्री लौटाता है।
एजेंट का prompt.tools फ़ील्ड, जिसमें टूल कॉन्फ़िग्स इनलाइन होते हैं, अब डिप्रिकेटेड है। इसे
tool_ids के साथ नहीं जोड़ा जा सकता, और जब किसी रिक्वेस्ट में यह शामिल होता है, तो एजेंट के बिल्ट-इन टूल्स
उसमें मौजूद सिस्टम टूल्स से बदल दिए जाते हैं। इसके बजाय tools.create() से टूल्स बनाएं और उन्हें ID से जोड़ें।
मौजूदा टूल संपादित करें
Tool.from_response() / Tool.fromResponse() tools.get() से लौटाया गया टूल लोड करता है। जिन फ़ील्ड्स को बिल्डर मॉडल नहीं करता और API द्वारा भरे जाने वाले डिफ़ॉल्ट्स को बनाए रखा जाता है, इसलिए उसे वापस पुश करने पर केवल आपके बदले गए हिस्से बदलते हैं। as_webhook(), as_client() और as_system() (JavaScript में asWebhook() वगैरह) आपको संपादित करने के लिए टाइप्ड टूल देते हैं, या अगर वह दूसरे प्रकार का है तो None / undefined देते हैं।
बॉडी प्रॉपर्टी बदलने के लिए, बॉडी स्कीमा पढ़ें, प्रॉपर्टी फिर से सेट करें और बॉडी सेट करें:
टूल्स को वर्शन कंट्रोल में स्टोर करें
to_json_string() / toJSONString() API के वायर फ़ॉर्मैट में टूल लिखता है: snake_case कुंजियां, हर स्तर पर सॉर्ट की हुई और 2-स्पेस इंडेंटेशन के साथ। यह वही स्वरूप है जिसे CLI अपनी tool_configs/ डायरेक्टरी में रखता है, और दोनों SDKs एक ही टूल के लिए बाइट-दर-बाइट एक जैसी फ़ाइलें लिखते हैं, इसलिए डिफ़्स छोटे रहते हैं। Tool.from_json() / Tool.fromJSON() उसे वापस पढ़ता है।
एक सामान्य सेटअप वर्कफ़्लोज़ जैसा ही है: फ़ाइलों को elevenlabs tools pull से सीड करें, उन्हें सीधे या बिल्डर से संपादित करें, हर पुल रिक्वेस्ट पर CI में Tool.from_json(file).build() / Tool.fromJSON(file).build() चलाएं और मर्ज होने पर tools.update() या elevenlabs tools push से पुश करें।
वैलिडेशन
चेन किए गए कॉल्स अपने-आप कभी फ़ेल नहीं होते। build(), build_config() / buildConfig(), to_json() / toJSON() और to_json_string() / toJSONString() पूरे टूल की जांच करते हैं और एक ही ToolValidationError को रेज़ या थ्रो करते हैं, जिसकी issues सूची में हर समस्या होती है और हर समस्या के साथ code, message और संबंधित हिस्से का path होता है, जैसे body.reason।
एरर्स में ये शामिल हैं:
- पाथ पैरामीटर के बिना URL प्लेसहोल्डर, या प्लेसहोल्डर के बिना पाथ पैरामीटर।
{{system__env_api_host}}जैसे एनवायरनमेंट वैरिएबल टेम्प्लेट्स प्लेसहोल्डर नहीं होते। - बिना वैल्यू स्रोत वाला लिटरल या एक से ज़्यादा स्रोत वाला लिटरल।
GETपर बॉडी, याPOST,PUTअथवाPATCHपर बॉडी न होना।- पाथ, क्वेरी और बॉडी में से एक से ज़्यादा में एक ही पैरामीटर नाम।
- आवश्यक प्रॉपर्टी पर
omit(), स्ट्रिंग न होने वाली स्कीमा परchoices(), या स्कीमा के टाइप से मेल न खाने वाला कॉन्स्टेंट। - बिना डेस्टिनेशन्स वाला ट्रांसफ़र टूल, गलत प्रकार का डेस्टिनेशन, या SIP REFER ट्रांसफ़र के बिना SIP URI डेस्टिनेशन।
- ऐसा विकल्प जो टूल के प्रकार पर लागू नहीं होता या सीमा से बाहर का टाइमआउट।
आपके SDK से नए टूल प्रकार
API या फ़ाइल से लोड किया गया कोई टूल ऐसे प्रकार का हो सकता है जिसे बिल्डर संपादित नहीं कर सकता, जैसे MCP टूल। वह "other" प्रकार के साथ लोड होता है और from_json() / fromJSON() तथा to_json_string() / toJSONString() के ज़रिए बिना बदले राउंड-ट्रिप होता है, और build() उसे on_warning / onWarning के ज़रिए चेतावनी के रूप में रिपोर्ट करता है।