Workflows als code
Bouw, bewerk en versioneer agentworkflows met de Python- en JavaScript-SDK’s
Overzicht
Een workflow wordt opgeslagen als een grafiek van knooppunten en randen. Als je die grafiek handmatig schrijft, moet je zelf zorgen dat rand-ID’s, lijsten met edge_order en voorwaardeobjecten consistent blijven. Met de Workflow-builder in de Python- en JavaScript-SDK’s kun je dezelfde grafiek beschrijven met gekoppelde methodeaanroepen. Vervolgens produceert deze de waarde workflow die agents.create() en agents.update() al accepteren.
Gebruik deze om:
- Een workflow in code te bouwen en deze te beoordelen zoals elke andere codewijziging.
- De workflow van een agent te laden, één knooppunt te wijzigen en deze terug te pushen zonder de rest van de grafiek te verstoren.
- Workflows als JSON op te slaan in versiebeheer en ze te valideren in CI.
De builder wordt volledig in de SDK uitgevoerd. Deze roept geen nieuwe API-endpoints aan en alles wat ermee wordt gebouwd, kan worden geopend en bewerkt in de visuele editor van het dashboard.
Vereisten
- Python: het pakket
elevenlabs. De builder wordt geïmporteerd uitelevenlabs.agent_workflows. - JavaScript: het pakket
@elevenlabs/elevenlabs-js. De builder wordt geëxporteerd vanuit de hoofdmap van het pakket.
Een workflow bouwen
Het Workflow-object staat voor de startnode. Elk werkwoord voegt een node toe en retourneert die, zodat je de volgende stap eraan kunt koppelen:
De routeringsmethoden bepalen welke edge naar de volgende node leidt:
Werkwoorden die je rechtstreeks op de workflow aanroept, vertakken vanaf de startnode met een onvoorwaardelijke edge. In dit voorbeeld worden bellers naar een bestellingszoekopdracht geleid, wordt de identificatie opnieuw geprobeerd als het opzoeken mislukt, en worden VIP-bellers of gefrustreerde bellers doorverbonden:
build() valideert de volledige grafiek en retourneert het requestmodel. Het doet ook het volgende:
- Geeft de startnode de ID
start_node, die de API vereist. - Genereert edge-ID’s in de vorm
source__target. - Vult de
edge_ordervan elke node in de volgorde waarin je de edges hebt toegevoegd. - Positioneert elke node zonder positie, zodat de grafiek in de visuele editor van links naar rechts wordt ingedeeld.
Een workflow als één keten schrijven
up() retourneert de node waaraan de huidige node is gekoppeld, zodat je een volledige workflow in één expressie kunt beschrijven in plaats van elke node in een variabele te bewaren. Gebruik binnen één keten go_to() / goTo() met een node-ID, omdat er geen variabele is om door te geven:
Voor een node-handle van wf.node(id) retourneert up() de node waar de eerste inkomende edge vandaan komt. Voor de startnode retourneert het de startnode.
Node-opties
Optionele instellingen geef je in Python op als keyword arguments en in JavaScript in een afsluitend optiesobject. De namen komen overeen met de velden van de node in de API:
Elk werkwoord accepteert ook position als je de node zelf wilt plaatsen. Workflow(prevent_subagent_loops=True) in Python, of new Workflow({ preventSubagentLoops: true }) in JavaScript, voorkomt dat het gesprek opnieuw een subagent binnengaat die het al heeft bezocht.
Overdrachtsbestemmingen
Voorwaarden
when() accepteert een gewone string, een Condition of een Expr:
- Een string is een LLM-voorwaarde: de LLM bepaalt of deze geldt.
Condition.llm(text, label=...)doet hetzelfde, met een label dat op de edge in de visuele editor wordt weergegeven. GebruikCondition.expr(expr, label=...)om een expressie te labelen.- Een
Exprwordt geëvalueerd aan de hand van dynamische variabelen, zonder de LLM aan te roepen.
Bouw expressies met Expr.variable(name) en Expr.literal(value). Vergelijk ze met eq, neq, gt, gte, lt en lte, en voer rekenkundige bewerkingen uit met add, sub, mul en div. Combineer ze met all_of / allOf, any_of / anyOf en if_else / ifElse. Gewone waarden worden automatisch verpakt in Expr.literal(). Expr.llm(description) vraagt de LLM om een waarde uit het gesprek te extraheren; geef type en enum door om een string, een getal of een waarde uit een vaste set te krijgen in plaats van een boolean.
Loops en terugwaartse edges
De API staat één edge toe tussen twee nodes, in beide richtingen. Geef de edge een terugwaartse voorwaarde met back om het gesprek te laten terugkeren langs dezelfde weg:
go_to() / goTo() handelt het veelvoorkomende geval voor je af. Wanneer de doelnode al een edge heeft die hierheen leidt, wordt de nieuwe edge de terugwaartse voorwaarde van die edge. In het eerste voorbeeld wordt failed.go_to(identify) verzonden als de terugwaartse voorwaarde van de edge identify → lookup_order. Elke andere tweede edge tussen dezelfde twee nodes, en elke edge van een node naar zichzelf, mislukt bij validatie.
Een bestaande agent bewerken
Workflow.from_agent() / Workflow.fromAgent() laadt de workflow van een agent die door agents.get() is geretourneerd. Node-ID’s, edge-ID’s, editorposities en edge-volgorde blijven behouden, dus door deze terug te pushen wijzig je alleen wat je hebt gewijzigd.
insert_between() / insertBetween() geeft je functie een branch met de voorwaarde van de vervangen edge. De functie retourneert de laatste node die deze toevoegt, die vervolgens met het oorspronkelijke doel wordt verbonden. De methode retourneert die node, of None / undefined als er geen edge tussen de twee nodes bestaat.
Workflows opslaan in versiebeheer
to_json_string() / toJSONString() schrijft de workflow in het wire format van de API: snake_case-sleutels, op elk niveau gesorteerd, met inspringing van 2 spaties. Dit is dezelfde structuur die de REST API en de CLI gebruiken, en beide SDK’s schrijven byte-voor-byte identieke bestanden voor dezelfde workflow, zodat diffs klein blijven. Workflow.from_json() / Workflow.fromJSON() leest dit weer in en accepteert ook een volledige agentconfiguratie met een workflow-sleutel, zoals een bestand in de map agent_configs/ van de CLI.
Een gebruikelijke configuratie:
Het bestand maken
Laad de agent met from_agent() / fromAgent() en schrijf deze weg, of haal hem op met elevenlabs agents pull.
Bewerken
Wijzig de JSON rechtstreeks, of laad deze met from_json() / fromJSON() en bewerk deze met de
builder in een script.
Een workflow visualiseren
De CLI tekent een workflowbestand als een stroomdiagram, zodat je kunt controleren wat je code heeft gebouwd zonder het dashboard te openen. De CLI accepteert een los workflowbestand dat is geschreven door to_json_string() / toJSONString(), of een agentconfiguratie met een workflow-sleutel:
Standaard tekent de CLI vakken en pijlen in de terminal, waarbij elke edge-voorwaarde op de edge wordt genummerd en in een legenda eronder wordt uitgeschreven. Gebruik in plaats daarvan --format mermaid om de broncode van Mermaid af te drukken, of --format mermaid-md om deze in een fenced code block te plaatsen dat GitHub weergeeft, bijvoorbeeld in een pull request-commentaar:
De opdracht leest alleen lokale bestanden, dus heeft deze geen API-sleutel nodig en kan deze in CI worden uitgevoerd.
Validatie
Gekoppelde aanroepen mislukken nooit op zichzelf. build(), to_json() / toJSON() en to_json_string() / toJSONString() controleren de volledige grafiek en genereren of gooien één WorkflowValidationError, waarvan issues elk probleem opsomt, met telkens een code, een message en de bijbehorende node_id / nodeId.
Fouten zijn onder meer:
- Twee edges tussen hetzelfde paar nodes, of een edge van een node naar zichzelf.
- Een edge naar de startnode, of vanuit een eindnode.
- Een edge vanuit een toolnode die geen success- of failure-edge is, of een success- of failure-edge vanuit een ander type node.
- Twee nodes met dezelfde ID, of een edge naar een node die niet bestaat.
Nodes die niet bereikbaar zijn vanaf de startnode worden als waarschuwingen gemeld via on_warning / onWarning en stoppen de build niet.
Nodetypen die nieuwer zijn dan je SDK
Een workflow die is geladen vanuit de API of uit een bestand kan nodetypen bevatten die je SDK-versie nog niet kent. Deze gaan ongewijzigd heen en weer via from_json() / fromJSON() en to_json_string() / toJSONString(), en build() meldt elk type als waarschuwing. Het getypeerde requestmodel kan ze niet bevatten, dus upgrade de SDK of verzend het wire format rechtstreeks: