Arbetsflöden som kod
Bygg, redigera och versionshantera agentarbetsflöden med Python- och JavaScript-SDK:erna
Översikt
Ett arbetsflöde lagras som en graf av noder och kanter. Att skriva grafen för hand innebär att du själv måste hålla kant-ID:n, listor med edge_order och villkorsobjekt konsekventa. Byggaren Workflow i Python- och JavaScript-SDK:erna låter dig beskriva samma graf med kedjade metodanrop. Den producerar sedan värdet workflow som agents.create() och agents.update() redan accepterar.
Använd den för att:
- Bygga ett arbetsflöde i kod och granska det som vilken annan kodändring som helst.
- Läsa in en agents arbetsflöde, ändra en nod och skicka tillbaka det utan att påverka resten av grafen.
- Lagra arbetsflöden som JSON i versionshantering och validera dem i CI.
Byggaren körs helt och hållet i SDK:t. Den anropar inga nya API-slutpunkter, och allt den bygger kan öppnas och redigeras i dashboardens visuella redigerare.
Krav
- Python: paketet
elevenlabs. Byggaren importeras frånelevenlabs.agent_workflows. - JavaScript: paketet
@elevenlabs/elevenlabs-js. Byggaren exporteras från paketets rot.
Bygg ett workflow
Objektet Workflow representerar startnoden. Varje verb lägger till en nod och returnerar den, så att du kan kedja nästa steg från den:
Routningsmetoderna avgör vilken kant som leder till nästa nod:
Verb som anropas direkt på workflowet förgrenas från startnoden med en ovillkorlig kant. Det här exemplet dirigerar uppringare till ordersökning, försöker identifieringen igen om sökningen misslyckas och överför VIP-kunder eller frustrerade uppringare:
build() validerar hela grafen och returnerar begärandemodellen. Metoden gör också följande:
- Ger startnoden ID:t
start_node, som API:t kräver. - Skapar kant-ID:n i formatet
source__target. - Fyller i varje nods
edge_orderi den ordning du lade till kanterna. - Positionerar alla noder som saknar position, så att grafen läggs ut från vänster till höger i den visuella redigeraren.
Skriv ett workflow som en kedja
up() returnerar noden som den aktuella noden kedjades från, så att du kan beskriva ett helt workflow i ett uttryck i stället för att spara varje nod i en variabel. I en enda kedja använder du go_to() / goTo() med ett nod-ID, eftersom det inte finns någon variabel att skicka:
För ett nodhandtag från wf.node(id) returnerar up() noden som den första inkommande kanten kommer från. För startnoden returnerar den startnoden.
Nodalternativ
Valfria inställningar anges som nyckelordsargument i Python och i ett avslutande alternativobjekt i JavaScript. Namnen motsvarar nodens fält i API:t:
Alla verb accepterar också position om du vill placera noden själv. Workflow(prevent_subagent_loops=True) i Python eller new Workflow({ preventSubagentLoops: true }) i JavaScript förhindrar att samtalet återgår till en subagent som det redan har besökt.
Överföringsdestinationer
Villkor
when() tar en vanlig sträng, ett Condition eller ett Expr:
- En sträng är ett LLM-villkor: LLM:en avgör om det uppfylls.
Condition.llm(text, label=...)är samma sak, med en etikett som visas på kanten i den visuella redigeraren. AnvändCondition.expr(expr, label=...)för att märka ett uttryck.- Ett
Exprutvärderas mot dynamiska variabler, utan att anropa LLM:en.
Bygg uttryck från Expr.variable(name) och Expr.literal(value). Jämför dem med eq, neq, gt, gte, lt och lte, och utför aritmetik med add, sub, mul och div. Kombinera dem med all_of / allOf, any_of / anyOf och if_else / ifElse. Vanliga värden omsluts automatiskt av Expr.literal(). Expr.llm(description) ber LLM:en att extrahera ett värde från samtalet. Skicka type och enum för att få en sträng, ett tal eller ett av en fast uppsättning värden i stället för ett booleskt värde.
Loopar och bakåtriktade kanter
API:t tillåter en kant mellan två noder, i valfri riktning. Om samtalet ska kunna återvända samma väg som det kom, ger du kanten ett bakåtriktat villkor med back:
go_to() / goTo() hanterar det vanliga fallet åt dig. När målnoden redan har en kant som leder hit blir den nya kanten den kantens bakåtriktade villkor. I det första exemplet skickas failed.go_to(identify) som det bakåtriktade villkoret för kanten identify → lookup_order. Alla andra kanter mellan samma två noder och alla kanter från en nod till sig själv misslyckas med valideringen.
Redigera en befintlig agent
Workflow.from_agent() / Workflow.fromAgent() läser in workflowet för en agent som returneras av agents.get(). Nod-ID:n, kant-ID:n, redigerarpositioner och kantordning behålls, så att en återpublicering bara ändrar det du har ändrat.
insert_between() / insertBetween() skickar en gren med den ersatta kantens villkor till din funktion. Funktionen returnerar den sista nod den lade till, som sedan ansluts till det ursprungliga målet. Metoden returnerar den noden, eller None / undefined om det inte finns någon kant mellan de två noderna.
Lagra workflows i versionshantering
to_json_string() / toJSONString() skriver workflowet i API:ts wire-format: snake_case-nycklar, sorterade på varje nivå, med indrag på 2 mellanslag. Det har samma struktur som REST API:t och CLI:t använder, och båda SDK:erna skriver byte-för-byte-identiska filer för samma workflow, så diffar förblir små. Workflow.from_json() / Workflow.fromJSON() läser in det igen och accepterar också en fullständig agentkonfiguration med en workflow-nyckel, till exempel en fil i CLI:ts katalog agent_configs/.
En vanlig konfiguration:
Skapa filen
Läs in agenten med from_agent() / fromAgent() och skriv ut den, eller hämta den med elevenlabs agents pull.
Redigera
Ändra JSON direkt eller läs in den med from_json() / fromJSON() och redigera den med
byggaren i ett skript.
Visualisera ett workflow
CLI:t ritar en workflowfil som ett flödesschema, så att du kan kontrollera vad din kod byggde utan att öppna dashboarden. Det accepterar en fristående workflowfil som skrivits av to_json_string() / toJSONString() eller en agentkonfiguration med en workflow-nyckel:
Som standard ritar det rutor och pilar i terminalen, med varje kantvillkor numrerat på sin kant och utskrivet i en förklaring under. Använd --format mermaid för att i stället skriva ut Mermaid-källkod, eller --format mermaid-md för att omsluta den i ett inhägnat kodblock som GitHub renderar, till exempel i en pull request-kommentar:
Kommandot läser endast lokala filer, så det behöver ingen API-nyckel och kan köras i CI.
Validering
Kedjade anrop misslyckas aldrig på egen hand. build(), to_json() / toJSON() och to_json_string() / toJSONString() kontrollerar hela grafen och ger ett enda WorkflowValidationError, vars issues listar varje problem, med en code, ett message och det berörda node_id / nodeId.
Fel omfattar:
- Två kanter mellan samma nodpar eller en kant från en nod till sig själv.
- En kant in till startnoden eller ut från en slutnod.
- En kant från en verktygsnod som inte är en framgångs- eller felkant, eller en framgångs- eller felkant från någon annan typ av nod.
- Två noder med samma ID eller en kant till en nod som inte finns.
Noder som inte kan nås från startnoden rapporteras som varningar via on_warning / onWarning och stoppar inte bygget.
Nodtyper som är nyare än din SDK
Ett workflow som lästs in från API:t eller från en fil kan innehålla nodtyper som din SDK-version ännu inte känner till. De passerar oförändrade genom from_json() / fromJSON() och to_json_string() / toJSONString(), och build() rapporterar var och en som en varning. Den typade begärandemodellen kan inte hantera dem, så uppgradera SDK:n eller skicka wire-formatet direkt: