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

कोड के रूप में वर्कफ़्लो

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 कर सकें:

PythonJavaScriptजोड़ता है
converse(id, prompt, **options)converse(id, prompt, options?)एक subagent नोड। एजेंट अपने निर्देशों में जोड़े गए prompt के साथ बातचीत करता है।
tool(id, tool_ids, **options)tool(id, toolIds, options?)दिया गया tool चलाने वाला dispatch tool नोड। इन्हें कोड के रूप में tools से परिभाषित करें।
transfer(id, destination, **options)transfer(id, destination, options?)किसी फ़ोन नंबर, SIP URI या दूसरे एजेंट को transfer।
end(id="end")end(options?)एक end नोड। ID के बिना हर end() एक ही "end" नोड शेयर करता है।

रूटिंग मेथड तय करते हैं कि कौन-सा edge अगले नोड तक जाता है:

PythonJavaScriptबनाता है
when(condition)when(condition)एक conditional edge। string एक LLM condition है; Expr एक expression है।
on_success() / on_failure()onSuccess() / onFailure()tool नोड से एक edge, जो tool call सफल या असफल होने पर लिया जाता है।
on_result(success=..., failure=...)onResult({ success, failure })दोनों tool result edges एक साथ।
go_to(node)goTo(node)पहले से मौजूद नोड तक edge, merges और loops के लिए।
up()up()कोई edge नहीं। उस नोड को लौटाता है जिससे मौजूदा नोड chain किया गया था, ताकि आप उससे chain जारी रख सकें। वर्कफ़्लो को एक chain के रूप में लिखें देखें।

वर्कफ़्लो पर सीधे कॉल किए गए verbs, बिना शर्त वाले edge के साथ स्टार्ट नोड से branch होते हैं। यह उदाहरण callers को order lookup पर भेजता है, lookup विफल होने पर पहचान की फिर से कोशिश करता है, और VIP या निराश callers को transfer करता है:

from elevenlabs import ElevenLabs
from elevenlabs.agent_workflows import Destination, Expr, Workflow
elevenlabs = ElevenLabs()
wf = Workflow()
triage = wf.converse("triage", "Greet the caller and find out why they're calling")
identify = triage.when("Caller wants to check an order").converse(
"identify", "Ask for the order number and the email on the account"
)
lookup = identify.when("Caller gave an order number").tool("lookup_order", ["tool_get_order"])
lookup.on_result(
success=lambda ok: ok.converse("resolve", "Explain the order status")
.when("Caller is satisfied")
.end(),
failure=lambda failed: failed.go_to(identify),
)
triage.when(Expr.variable("tier").eq("gold")).transfer("vip", Destination.agent("agent_vip"))
triage.when("Caller wants a human").transfer("human", Destination.phone("+15551234567"))
elevenlabs.conversational_ai.agents.update("agent_id", workflow=wf.build())

build() पूरे graph को validate करता है और request model लौटाता है। यह:

  • स्टार्ट नोड को start_node ID देता है, जिसकी 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 = Workflow()
(
wf.converse("triage", "Find out why the customer is calling")
.when("Caller gave an order number")
.tool("lookup_order", ["tool_get_order"])
.on_result(
success=lambda ok: ok.converse("resolve", "Explain the order status").when("Customer is satisfied").end(),
failure=lambda failed: failed.go_to("triage"),
)
.up()
.when(Expr.variable("tier").eq("gold"))
.transfer("vip", Destination.agent("agent_vip_desk"))
)
elevenlabs.conversational_ai.agents.update("agent_id", workflow=wf.build())

wf.node(id) से मिले node handle के लिए, up() उस नोड को लौटाता है जिससे उसमें आने वाला पहला edge आता है। स्टार्ट नोड के लिए, यह स्टार्ट नोड ही लौटाता है।

नोड विकल्प

वैकल्पिक सेटिंग्स Python में keyword arguments में और JavaScript में आखिर के options object में जाती हैं। इनके नाम API में नोड के fields से मेल खाते हैं:

नोडPythonJavaScript
converselabel, tool_ids, knowledge_base, conversation_config, entry_behaviorlabel, toolIds, knowledgeBase, conversationConfig, entryBehavior
toolschema_overridesschemaOverrides
transfertransfer_type, custom_sip_headers, post_dial_digits, delay_ms, transfer_message, …transferType, customSipHeaders, postDialDigits, delayMs, transferMessage, …
endidid

अगर आप नोड को खुद place करना चाहते हैं, तो हर verb position भी स्वीकार करता है। Python में Workflow(prevent_subagent_loops=True) या JavaScript में new Workflow({ preventSubagentLoops: true }) बातचीत को पहले से visit किए गए subagent में दोबारा जाने से रोकता है।

triage = wf.converse(
"triage",
"Greet the caller and find out why they're calling",
label="Triage",
tool_ids=["tool_crm_search"],
entry_behavior="generate_immediately",
)
triage.when("Caller is a VIP").transfer(
"vip_desk",
Destination.agent("agent_vip_concierge"),
transfer_message="Connecting you to our VIP team",
delay_ms=500,
)
identify.when("Caller refuses to share details").end(id="abandoned")

Transfer destinations

PythonJavaScriptयहां transfer करता है
Destination.phone(number)Destination.phone(number)एक फ़ोन नंबर
Destination.phone_variable(name)Destination.phoneVariable(name)dynamic variable में मौजूद फ़ोन नंबर
Destination.sip(uri)Destination.sip(uri)एक SIP URI
Destination.sip_variable(name)Destination.sipVariable(name)dynamic variable में मौजूद SIP URI
Destination.agent(agent_id)Destination.agent(agentId)दूसरा एजेंट

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 पास करें।

from elevenlabs.agent_workflows import Condition, Expr
is_vip = Expr.any_of(
Expr.variable("tier").eq("gold"),
Expr.all_of(Expr.variable("orders").gte(10), Expr.variable("churn_risk").eq(True)),
)
triage.when(Condition.expr(is_vip, label="VIP")).transfer("vip_desk", Destination.agent("agent_vip"))
big_refund = Expr.variable("unit_price").mul(Expr.variable("quantity")).gt(500)
resolve.when(big_refund).transfer("finance", Destination.phone("+15551234567"))
score = Expr.llm("How satisfied the caller sounds, from 1 to 5", type="integer")
resolve.when(score.lte(2)).converse("recovery", "Apologize and offer a discount code")

Loops और backward edges

API किसी भी दो नोड्स के बीच, किसी भी दिशा में एक edge की अनुमति देता है। बातचीत को उसी रास्ते से वापस जाने देने के लिए, edge को back के साथ एक backward condition दें:

faq = triage.when("Caller has a general question", back="Question answered").converse(
"faq", "Answer using the FAQ knowledge base"
)

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 करने पर सिर्फ़ आपके बदलाव बदलते हैं।

PythonJavaScriptकार्य
wf.node(id)wf.node(id)किसी मौजूदा नोड का handle लौटाता है, ताकि उसे संपादित किया जा सके या उससे chain किया जा सके।
node.update(**fields)node.update(fields)नोड के prompt, tools, destination या options बदलता है।
wf.insert_between(source, target, fn)wf.insertBetween(source, target, fn)मौजूदा edge की condition बनाए रखते हुए उसमें नए नोड्स जोड़ता है।
wf.remove(id)wf.remove(id)एक नोड और उससे आने-जाने वाले हर edge को हटाता है।

insert_between() / insertBetween() आपके function को एक branch देता है जिसमें बदले गए edge की condition होती है। function अपने जोड़े हुए आखिरी नोड को लौटाता है, जिसे फिर original target से connect किया जाता है। मेथड वह नोड लौटाता है, या अगर दोनों नोड्स के बीच कोई edge नहीं है तो None / undefined लौटाता है।

agent = elevenlabs.conversational_ai.agents.get("agent_id")
wf = Workflow.from_agent(agent)
wf.node("resolve").update(prompt="Explain the status, then offer a discount code")
verify = wf.insert_between(
"identify",
"lookup_order",
lambda start: start.converse("verify", "Verify the caller's identity with a one-time code"),
)
if verify is not None:
verify.when("Caller can't verify").end(id="unverified")
wf.remove("vip")
elevenlabs.conversational_ai.agents.update("agent_id", workflow=wf.build())

वर्कफ़्लो को 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।

from pathlib import Path
from elevenlabs.agent_workflows import Workflow
Path("workflows/support.json").write_text(wf.to_json_string())
stored = Workflow.from_json(Path("workflows/support.json").read_text())
from_cli = Workflow.from_json(Path("agent_configs/support.json").read_text())

एक सामान्य setup:

1

फ़ाइल तैयार करें

एजेंट को from_agent() / fromAgent() से लोड करके लिखें, या उसे elevenlabs agents pull से pull करें।

2

संपादित करें

JSON को सीधे बदलें, या उसे from_json() / fromJSON() से लोड करके script में builder से संपादित करें।

3

CI में validate करें

हर pull request पर Workflow.from_json(file).build() / Workflow.fromJSON(file).build() चलाएं, और comment के रूप में elevenlabs agents workflow diagram <file> --format mermaid-md पोस्ट करें ताकि reviewers graph देख सकें।

4

Merge पर deploy करें

बने हुए वर्कफ़्लो को agents.update() से push करें।

वर्कफ़्लो को visualize करें

CLI किसी वर्कफ़्लो file को flowchart के रूप में बनाता है, ताकि dashboard खोले बिना आप देख सकें कि आपके code ने क्या बनाया है। यह to_json_string() / toJSONString() से लिखी plain workflow file या workflow key वाला agent config स्वीकार करता है:

elevenlabs agents workflow diagram workflows/support.json

डिफ़ॉल्ट रूप से यह terminal में boxes और arrows बनाता है, जिसमें हर edge condition उसके edge पर numbered होती है और नीचे legend में लिखी होती है। इसके बजाय Mermaid source प्रिंट करने के लिए --format mermaid इस्तेमाल करें, या इसे fenced code block में wrap करने के लिए --format mermaid-md इस्तेमाल करें, जिसे GitHub render करता है, जैसे pull request comment में:

elevenlabs agents workflow diagram workflows/support.json --format mermaid-md

यह 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 होता है।

from elevenlabs.agent_workflows import WorkflowValidationError
try:
workflow = wf.build(on_warning=lambda issue: print("warning:", issue.message))
except WorkflowValidationError as err:
for issue in err.issues:
print(issue.code, issue.message)

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 सीधे भेजें:

elevenlabs.conversational_ai.agents.update(
"agent_id",
request_options={"additional_body_parameters": {"workflow": wf.to_json()}},
)