नेविगेशन पर जाएँ

कोड के रूप में टूल्स

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 कुंजी भेजता है और ऑर्डर का स्टेटस एक डायनामिक वैरिएबल में स्टोर करता है:

from elevenlabs import ElevenLabs
from elevenlabs.agent_tools import Header, Schema, Tool
elevenlabs = ElevenLabs()
get_order = (
Tool.webhook("get_order", "Look up an order by the number the caller gives")
.get("https://api.example.com/orders/{order_id}")
.path_param("order_id", Schema.string().describe("The order number, e.g. A-1042"))
.query_param("include", Schema.string().constant("items"))
.header("Authorization", Header.secret("sec_orders_api"))
.assign("order_status", "order.status")
.options(response_timeout_secs=10)
)
tool = elevenlabs.conversational_ai.tools.create(request=get_order.build())

रिक्वेस्ट मेथड्स HTTP मेथड और URL सेट करते हैं। URL में {name} प्लेसहोल्डर्स को पाथ पैरामीटर्स से भरा जाता है:

PythonJavaScriptसेट करता है
get(url), post(url), put(url), patch(url), delete(url)sameमेथड और URL। POST, PUT और PATCH को एक बॉडी चाहिए; GET में बॉडी नहीं हो सकती।
path_param(name, schema)pathParam(name, schema)URL में {name} प्लेसहोल्डर के लिए एक पाथ पैरामीटर।
query_param(name, schema)queryParam(name, schema)एक क्वेरी पैरामीटर।
body(schema)body(schema)रिक्वेस्ट बॉडी। यह एक ऑब्जेक्ट स्कीमा होना चाहिए।
response(schema)response(schema)रिस्पॉन्स बॉडी स्कीमा। यह एक ऑब्जेक्ट स्कीमा होना चाहिए।
header(name, value)header(name, value)एक रिक्वेस्ट हेडर। हेडर्स और ऑथेंटिकेशन देखें।
auth(connection)auth(connection)इस्तेमाल करने के लिए ऑथ कनेक्शन।
assign(variable, path)assign(variable, path)रिस्पॉन्स में path (डॉट नोटेशन) पर मौजूद वैल्यू को डायनामिक वैरिएबल में स्टोर करता है।

पहले से मौजूद नाम वाले पैरामीटर या हेडर को सेट करने पर वह बदल जाता है और अपनी जगह बनाए रखता है। remove_path_param(), remove_query_param(), remove_header() और remove_assignment() (JavaScript में removePathParam() वगैरह) किसी को हटा देते हैं। पाथ, क्वेरी और बॉडी में पैरामीटर नाम यूनिक होने चाहिए।

बॉडी एक ऑब्जेक्ट स्कीमा है, जिसे प्रॉपर्टी दर प्रॉपर्टी बनाया जाता है:

refund = (
Tool.webhook("issue_refund", "Refund an order the caller asked to return")
.post("https://api.example.com/refunds")
.body(
Schema.object()
.property("order_id", Schema.string().from_variable("order_id"))
.property(
"reason",
Schema.string().describe("Why the caller wants a refund").choices(["damaged", "late", "other"]),
)
.property("note", Schema.string().describe("Anything else the caller said").optional())
)
)

पैरामीटर स्कीमाएं

Schema उन पैरामीटर स्कीमाओं को बनाता है जिनका इस्तेमाल वेबहुक और क्लाइंट टूल्स करते हैं। हर मेथड एक नई स्कीमा लौटाता है और जिस स्कीमा पर उसे कॉल किया गया था उसे बिना बदले रखता है, इसलिए आप किसी स्कीमा को एक बार परिभाषित करके कई टूल्स में इस्तेमाल कर सकते हैं।

कंस्ट्रक्टरबनाता है
Schema.string(), Schema.integer(), Schema.number(), Schema.bool()एक लिटरल वैल्यू
Schema.object()एक ऑब्जेक्ट। property() से प्रॉपर्टीज़ जोड़ें।
Schema.array(items)एक ऐरे, जिसके एलिमेंट्स items स्कीमा से मेल खाते हैं

वैल्यू कहाँ से आती है

हर लिटरल को ठीक एक वैल्यू स्रोत चाहिए, वह चाहे कहीं भी हो: पैरामीटर में, बॉडी में, रिस्पॉन्स स्कीमा में या किसी ऑब्जेक्ट अथवा ऐरे के अंदर। किसी ऑब्जेक्ट या ऐरे का भी एक स्रोत हो सकता है, जो फिर पूरी वैल्यू देता है।

PythonJavaScriptवैल्यू
describe(text)describe(text)LLM द्वारा दी जाती है, जिसमें text मार्गदर्शन करता है।
from_variable(name)fromVariable(name)टूल चलने पर डायनामिक वैरिएबल से पढ़ी जाती है।
constant(value)constant(value)हमेशा value होती है।
system_provided()systemProvided()टूल चलने पर सिस्टम द्वारा भरी जाती है। सिर्फ़ लिटरल्स के लिए।
omit()omit()रिक्वेस्ट में शामिल नहीं की जाती। सिर्फ़ वैकल्पिक प्रॉपर्टी के लिए।

किसी ऑब्जेक्ट या ऐरे पर, describe() LLM के लिए कंटेनर का दस्तावेज़ीकरण करता है और हर प्रॉपर्टी या एलिमेंट का अपना स्रोत रहता है।

अन्य स्कीमा मेथड्स

PythonJavaScriptकाम
optional()optional()किसी प्रॉपर्टी को वैकल्पिक बनाता है। वैकल्पिक के रूप में चिह्नित न होने पर प्रॉपर्टीज़ आवश्यक होती हैं।
choices(values)choices(values)किसी स्ट्रिंग को तय वैल्यू के सेट तक सीमित करता है, जिसमें से LLM चुनता है।
allowed_from(variable)allowedFrom(variable)अगर LLM की वैल्यू डायनामिक वैरिएबल में मौजूद सूची में नहीं है, तो उसे अस्वीकार करता है। describe() चाहिए।
property(name, schema) / without(name)property(name, schema) / without(name)ऑब्जेक्ट प्रॉपर्टी जोड़ता, बदलता या हटाता है। बदली गई प्रॉपर्टी अपनी जगह बनाए रखती है।
require_any_of(names) / require_all_of(names)requireAnyOf(names) / requireAllOf(names)वैकल्पिक प्रॉपर्टीज़ के समूह में से कम से कम एक या सभी की ज़रूरत रखता है।

हेडर्स और ऑथेंटिकेशन

हेडर वैल्यू चार में से किसी एक जगह से आती है। संवेदनशील जानकारी के लिए सीक्रेट या एनवायरनमेंट वैरिएबल इस्तेमाल करें, ताकि वैल्यू कभी टूल कॉन्फ़िग में दिखाई न दे:

कंस्ट्रक्टरहेडर वैल्यू है
Header.value(text)तय टेक्स्ट।
Header.secret(id)वर्कस्पेस के सीक्रेट स्टोर से एक सीक्रेट।
Header.variable(name)एक डायनामिक वैरिएबल, जिसे टूल चलने पर पढ़ा जाता है।
Header.env_var(label) / Header.envVar(label)एक वर्कस्पेस एनवायरनमेंट वैरिएबल, जिसे मौजूदा एनवायरनमेंट के लिए रिज़ॉल्व किया जाता है।

AuthConnection.id(id) ID से वर्कस्पेस का एक ऑथ कनेक्शन इस्तेमाल करता है। AuthConnection.env_var(label) / AuthConnection.envVar(label) उसे एनवायरनमेंट वैरिएबल से चुनता है, ताकि वही टूल कॉन्फ़िग हर एनवायरनमेंट में अलग कनेक्शन इस्तेमाल कर सके।

from elevenlabs.agent_tools import AuthConnection, Header
update_profile = (
Tool.webhook("update_profile", "Update the caller's email address")
.put("https://api.example.com/profiles/{profile_id}")
.path_param("profile_id", Schema.string().from_variable("profile_id"))
.body(Schema.object().property("email", Schema.string().describe("The new email address")))
.header("X-Api-Key", Header.env_var("profiles_api_key"))
.auth(AuthConnection.env_var("profiles_oauth"))
)

क्लाइंट टूल बनाएं

Tool.client(name, description) एक क्लाइंट टूल शुरू करता है, जो सर्वर के बजाय आपके एप्लिकेशन में चलता है। इसके पैरामीटर्स को param(name, schema) से जोड़ें। जब एजेंट को आपके एप्लिकेशन के परिणाम का इंतज़ार करना हो, तब expects_response / expectsResponse सेट करें:

show_map = (
Tool.client("show_store_map", "Show the caller a map of the nearest store")
.param("store_id", Schema.string().describe("The store to show"))
.options(expects_response=False)
)

सिस्टम टूल बनाएं

सिस्टम टूल्स प्लेटफ़ॉर्म में पहले से शामिल होते हैं। हर टूल का SystemTool पर अपना कंस्ट्रक्टर होता है, जो उस टूल की सेटिंग्स लेता है:

PythonJavaScript
SystemTool.end_call()SystemTool.endCall()
SystemTool.skip_turn(wait_timeout_secs=...)SystemTool.skipTurn({ waitTimeoutSecs })
SystemTool.language_detection(...)SystemTool.languageDetection(options?)
SystemTool.play_keypad_touch_tone(...)SystemTool.playKeypadTouchTone(options?)
SystemTool.voicemail_detection(voicemail_message=...)SystemTool.voicemailDetection({ voicemailMessage })
SystemTool.knowledge_base(enabled_strategies=...)SystemTool.knowledgeBase({ enabledStrategies })
SystemTool.transfer_to_number(...)SystemTool.transferToNumber(options?)
SystemTool.transfer_to_agent()SystemTool.transferToAgent()

दो ट्रांसफ़र टूल्स अपने डेस्टिनेशन transfer(condition, destination, options) से लेते हैं। कंडीशन LLM को बताती है कि वहाँ कब ट्रांसफ़र करना है, और डेस्टिनेशन वही Destination इस्तेमाल करता है जो कोड के रूप में वर्कफ़्लोज़ में होता है। SIP URI में ट्रांसफ़र के लिए SIP REFER ट्रांसफ़र चाहिए:

from elevenlabs.agent_tools import SystemTool
from elevenlabs.agent_workflows import Destination
transfer = (
SystemTool.transfer_to_number()
.transfer("Caller asks for billing", Destination.phone("+15551234567"))
.transfer("Caller is a reseller partner", Destination.sip("sip:partners@pbx.example.com"), transfer_type="sip_refer")
)
to_sales = SystemTool.transfer_to_agent().transfer(
"Caller wants to buy something", Destination.agent("agent_sales"), transfer_message="Connecting you to sales"
)

टूल विकल्प

हर तरह के टूल की साझा सेटिंग्स options() में जाती हैं: Python में कीवर्ड आर्ग्युमेंट्स के रूप में और JavaScript में ऑब्जेक्ट के रूप में। इनके नाम API में टूल कॉन्फ़िग के फ़ील्ड्स से मेल खाते हैं:

लागू होता हैPythonJavaScript
सभी टूल्सname, description, response_timeout_secs, interruption_mode, pre_tool_speech, tool_call_sound, tool_error_handling_mode, …name, description, responseTimeoutSecs, interruptionMode, preToolSpeech, toolCallSound, toolErrorHandlingMode, …
वेबहुक टूल्सexecution_mode, content_type, response_filter, follow_redirects, follow_redirects_allowed_domains, dynamic_variable_placeholdersexecutionMode, contentType, responseFilter, followRedirects, followRedirectsAllowedDomains, dynamicVariablePlaceholders
क्लाइंट टूल्सexecution_mode, expects_response, dynamic_variable_placeholdersexecutionMode, expectsResponse, dynamicVariablePlaceholders

वेबहुक टूल का रिस्पॉन्स टाइमआउट 5 से 300 सेकंड होता है। क्लाइंट टूल का 1 से 120 सेकंड या जितना समय लगे उतना इंतज़ार करने के लिए -1 होता है, जिसके लिए expects_response / expectsResponse चाहिए। follow_redirects / followRedirects को अनुमत डोमेन्स की सूची चाहिए।

एजेंट से टूल्स जोड़ें

वेबहुक और क्लाइंट टूल्स tools.create() से अलग से बनाए जाते हैं और ID से एजेंट्स से जोड़े जाते हैं, इसलिए एक टूल कई एजेंट्स के साथ शेयर किया जा सकता है। सिस्टम टूल्स एजेंट के कॉन्फ़िग का हिस्सा होते हैं: build_config() / buildConfig() एजेंट के बिल्ट-इन टूल्स के लिए एंट्री लौटाता है।

from elevenlabs import AgentConfig, BuiltInToolsOutput, ConversationalConfig, PromptAgentApiModelOutput
order_tool = elevenlabs.conversational_ai.tools.create(request=get_order.build())
agent = elevenlabs.conversational_ai.agents.create(
name="Support line",
conversation_config=ConversationalConfig(
agent=AgentConfig(
prompt=PromptAgentApiModelOutput(
prompt="You are a support agent for Acme.",
tool_ids=[order_tool.id],
built_in_tools=BuiltInToolsOutput(
end_call=SystemTool.end_call().build_config(),
transfer_to_number=transfer.build_config(),
),
)
)
),
)

एजेंट का 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 देते हैं।

बॉडी प्रॉपर्टी बदलने के लिए, बॉडी स्कीमा पढ़ें, प्रॉपर्टी फिर से सेट करें और बॉडी सेट करें:

from elevenlabs.agent_tools import ObjectSchema
loaded = Tool.from_response(elevenlabs.conversational_ai.tools.get("tool_id")).as_webhook()
if loaded is None:
raise ValueError("Not a webhook tool")
body = loaded.body_schema
assert isinstance(body, ObjectSchema)
loaded.body(body.property("reason", Schema.string().describe("Why the caller wants a refund")))
loaded.query_param("locale", Schema.string().describe("The caller's language").optional())
elevenlabs.conversational_ai.tools.update("tool_id", request=loaded.build())

टूल्स को वर्शन कंट्रोल में स्टोर करें

to_json_string() / toJSONString() API के वायर फ़ॉर्मैट में टूल लिखता है: snake_case कुंजियां, हर स्तर पर सॉर्ट की हुई और 2-स्पेस इंडेंटेशन के साथ। यह वही स्वरूप है जिसे CLI अपनी tool_configs/ डायरेक्टरी में रखता है, और दोनों SDKs एक ही टूल के लिए बाइट-दर-बाइट एक जैसी फ़ाइलें लिखते हैं, इसलिए डिफ़्स छोटे रहते हैं। Tool.from_json() / Tool.fromJSON() उसे वापस पढ़ता है।

from pathlib import Path
from elevenlabs.agent_tools import Tool
Path("tool_configs/get_order.json").write_text(get_order.to_json_string())
stored = Tool.from_json(Path("tool_configs/get_order.json").read_text())
elevenlabs.conversational_ai.tools.update("tool_id", request=stored.build())

एक सामान्य सेटअप वर्कफ़्लोज़ जैसा ही है: फ़ाइलों को 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।

from elevenlabs.agent_tools import ToolValidationError
try:
request = refund.build()
except ToolValidationError as err:
for issue in err.issues:
print(issue.code, issue.path, issue.message)

एरर्स में ये शामिल हैं:

  • पाथ पैरामीटर के बिना 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 के ज़रिए चेतावनी के रूप में रिपोर्ट करता है।