कोड के रूप में वर्कफ़्लो
Python और JavaScript SDKs के साथ एजेंट वर्कफ़्लो बनाएं, एडिट करें और वर्शन करें
परिचय
एक वर्कफ़्लो नोड्स और एजेस के ग्राफ़ के रूप में स्टोर होता है। उस ग्राफ़ को हाथ से लिखने का मतलब है कि आपको एज IDs, edge_order सूचियों और कंडीशन ऑब्जेक्ट्स को खुद संगत रखना होगा। Python और JavaScript SDKs में Workflow बिल्डर आपको चेन किए गए मेथड कॉल्स से उसी ग्राफ़ का वर्णन करने देता है। फिर यह वह workflow वैल्यू बनाता है, जिसे agents.create() और agents.update() पहले से स्वीकार करते हैं।
इसका इस्तेमाल इन कामों के लिए करें:
- कोड में वर्कफ़्लो बनाएं और किसी भी अन्य कोड बदलाव की तरह उसका रिव्यू करें।
- किसी एजेंट का वर्कफ़्लो लोड करें, एक नोड बदलें और बाकी ग्राफ़ को प्रभावित किए बिना वापस पुश करें।
- वर्कफ़्लो को वर्शन कंट्रोल में JSON के रूप में स्टोर करें और CI में उन्हें वैलिडेट करें।
बिल्डर पूरी तरह SDK में चलता है। यह कोई नया API एंडपॉइंट कॉल नहीं करता और इसके बनाए किसी भी वर्कफ़्लो को डैशबोर्ड के विज़ुअल एडिटर में खोला और एडिट किया जा सकता है।
आवश्यकताएं
- Python:
elevenlabsपैकेज। बिल्डरelevenlabs.agent_workflowsसे इंपोर्ट किया जाता है। - JavaScript:
@elevenlabs/elevenlabs-jsपैकेज। बिल्डर पैकेज रूट से एक्सपोर्ट किया जाता है।
वर्कफ़्लो बनाएं
Workflow ऑब्जेक्ट स्टार्ट नोड को दर्शाता है। हर verb एक नोड जोड़ता है और उसे लौटाता है, ताकि आप उससे अगला चरण chain कर सकें:
रूटिंग मेथड तय करते हैं कि कौन-सा edge अगले नोड तक जाता है:
वर्कफ़्लो पर सीधे कॉल किए गए verbs, बिना शर्त वाले edge के साथ स्टार्ट नोड से branch होते हैं। यह उदाहरण callers को order lookup पर भेजता है, lookup विफल होने पर पहचान की फिर से कोशिश करता है, और VIP या निराश callers को transfer करता है:
build() पूरे graph को validate करता है और request model लौटाता है। यह:
- स्टार्ट नोड को
start_nodeID देता है, जिसकी API को ज़रूरत होती है। source__targetफ़ॉर्म में edge IDs बनाता है।- आपके द्वारा edges जोड़ने के क्रम में हर नोड का
edge_orderभरता है। - जिस नोड की position नहीं है, उसे position करता है, ताकि visual editor में graph बाएं से दाएं व्यवस्थित रहे।
वर्कफ़्लो को एक chain के रूप में लिखें
up() उस नोड को लौटाता है जिससे मौजूदा नोड chain किया गया था, इसलिए हर नोड को variable में रखने के बजाय आप पूरे वर्कफ़्लो को एक expression में लिख सकते हैं। एक ही chain में go_to() / goTo() के साथ node ID इस्तेमाल करें, क्योंकि पास करने के लिए कोई variable नहीं होता:
wf.node(id) से मिले node handle के लिए, up() उस नोड को लौटाता है जिससे उसमें आने वाला पहला edge आता है। स्टार्ट नोड के लिए, यह स्टार्ट नोड ही लौटाता है।
नोड विकल्प
वैकल्पिक सेटिंग्स Python में keyword arguments में और JavaScript में आखिर के options object में जाती हैं। इनके नाम API में नोड के fields से मेल खाते हैं:
अगर आप नोड को खुद place करना चाहते हैं, तो हर verb position भी स्वीकार करता है। Python में Workflow(prevent_subagent_loops=True) या JavaScript में new Workflow({ preventSubagentLoops: true }) बातचीत को पहले से visit किए गए subagent में दोबारा जाने से रोकता है।
Transfer destinations
Conditions
when() एक सामान्य string, Condition या Expr लेता है:
- string एक LLM condition होती है: LLM तय करता है कि वह लागू होती है या नहीं।
Condition.llm(text, label=...)भी यही है, लेकिन visual editor में edge पर label दिखता है। किसी expression को label करने के लिएCondition.expr(expr, label=...)इस्तेमाल करें।Exprको LLM को कॉल किए बिना dynamic variables के आधार पर evaluate किया जाता है।
Expr.variable(name) और Expr.literal(value) से expressions बनाएं। उनकी तुलना eq, neq, gt, gte, lt और lte से करें, और arithmetic के लिए add, sub, mul और div का इस्तेमाल करें। इन्हें all_of / allOf, any_of / anyOf और if_else / ifElse से combine करें। सामान्य values आपके लिए Expr.literal() में wrap हो जाती हैं। Expr.llm(description) LLM से बातचीत में से कोई value निकालने को कहता है; boolean के बजाय string, number या fixed set में से एक value पाने के लिए type और enum पास करें।
Loops और backward edges
API किसी भी दो नोड्स के बीच, किसी भी दिशा में एक edge की अनुमति देता है। बातचीत को उसी रास्ते से वापस जाने देने के लिए, edge को back के साथ एक backward condition दें:
go_to() / goTo() आपके लिए सामान्य मामले को संभालता है। जब target नोड के पास पहले से यहां आने वाला edge होता है, तो नया edge उस edge की backward condition बन जाता है। पहले उदाहरण में, failed.go_to(identify) को identify → lookup_order edge की backward condition के रूप में भेजा जाता है। एक ही दो नोड्स के बीच कोई भी दूसरा edge, और किसी नोड से उसी नोड तक कोई भी edge, validation में विफल होता है।
मौजूदा एजेंट को संपादित करें
Workflow.from_agent() / Workflow.fromAgent() agents.get() से लौटे एजेंट का वर्कफ़्लो लोड करता है। Node IDs, edge IDs, editor positions और edge order बनाए रखे जाते हैं, इसलिए इसे वापस push करने पर सिर्फ़ आपके बदलाव बदलते हैं।
insert_between() / insertBetween() आपके function को एक branch देता है जिसमें बदले गए edge की condition होती है। function अपने जोड़े हुए आखिरी नोड को लौटाता है, जिसे फिर original target से connect किया जाता है। मेथड वह नोड लौटाता है, या अगर दोनों नोड्स के बीच कोई edge नहीं है तो None / undefined लौटाता है।
वर्कफ़्लो को version control में स्टोर करें
to_json_string() / toJSONString() वर्कफ़्लो को API के wire format में लिखता है: snake_case keys, हर स्तर पर sorted, और 2-space indentation के साथ। यह वही shape है जिसे REST API और CLI इस्तेमाल करते हैं, और दोनों SDKs एक ही वर्कफ़्लो के लिए byte-for-byte एक जैसी files लिखते हैं, इसलिए diffs छोटे रहते हैं। Workflow.from_json() / Workflow.fromJSON() इसे वापस पढ़ता है और workflow key वाले पूरे agent config को भी स्वीकार करता है, जैसे CLI की agent_configs/ directory में मौजूद file।
एक सामान्य setup:
फ़ाइल तैयार करें
एजेंट को from_agent() / fromAgent() से लोड करके लिखें, या उसे elevenlabs agents pull से pull करें।
संपादित करें
JSON को सीधे बदलें, या उसे from_json() / fromJSON() से लोड करके script में
builder से संपादित करें।
वर्कफ़्लो को visualize करें
CLI किसी वर्कफ़्लो file को flowchart के रूप में बनाता है, ताकि dashboard खोले बिना आप देख सकें कि आपके code ने क्या बनाया है। यह to_json_string() / toJSONString() से लिखी plain workflow file या workflow key वाला agent config स्वीकार करता है:
डिफ़ॉल्ट रूप से यह terminal में boxes और arrows बनाता है, जिसमें हर edge condition उसके edge पर numbered होती है और नीचे legend में लिखी होती है। इसके बजाय Mermaid source प्रिंट करने के लिए --format mermaid इस्तेमाल करें, या इसे fenced code block में wrap करने के लिए --format mermaid-md इस्तेमाल करें, जिसे GitHub render करता है, जैसे pull request comment में:
यह command सिर्फ़ local files पढ़ता है, इसलिए इसे API key की ज़रूरत नहीं होती और यह CI में चल सकता है।
Validation
Chained calls अपने-आप कभी विफल नहीं होतीं। build(), to_json() / toJSON() और to_json_string() / toJSONString() पूरे graph की जांच करते हैं और एक ही WorkflowValidationError raise या throw करते हैं, जिसकी issues सूची में हर समस्या होती है। हर समस्या के साथ code, message और उससे संबंधित node_id / nodeId होता है।
Errors में शामिल हैं:
- एक ही जोड़ी के नोड्स के बीच दो edges, या किसी नोड से उसी नोड तक edge।
- स्टार्ट नोड में आने वाला edge, या end नोड से निकलने वाला edge।
- tool नोड से ऐसा edge जो success या failure edge नहीं है, या किसी और तरह के नोड से success या failure edge।
- एक ही ID वाले दो नोड्स, या ऐसे नोड तक edge जो मौजूद नहीं है।
जो नोड्स स्टार्ट नोड से नहीं पहुंच सकते, उन्हें on_warning / onWarning के जरिए warnings के रूप में रिपोर्ट किया जाता है और वे build को नहीं रोकते।
आपके SDK से नए node types
API या file से लोड किए गए वर्कफ़्लो में ऐसे node types हो सकते हैं जिन्हें आपका SDK version अभी नहीं जानता। वे from_json() / fromJSON() और to_json_string() / toJSONString() के जरिए बिना बदलाव के round-trip होते हैं, और build() हर एक को warning के रूप में रिपोर्ट करता है। Typed request model उन्हें carry नहीं कर सकता, इसलिए SDK upgrade करें या wire format सीधे भेजें: