Workflow come codice
Panoramica
Un workflow viene archiviato come un grafo di nodi e archi. Scrivere questo grafo a mano significa dover mantenere coerenti autonomamente gli ID degli archi, gli elenchi edge_order e gli oggetti condizione. Il builder Workflow negli SDK Python e JavaScript ti consente di descrivere lo stesso grafo con chiamate di metodi concatenate. Genera quindi il valore workflow già accettato da agents.create() e agents.update().
Usalo per:
- Creare un workflow nel codice e revisionarlo come qualsiasi altra modifica al codice.
- Caricare il workflow di un agente, modificare un nodo e caricarlo di nuovo senza alterare il resto del grafo.
- Archiviare i workflow come JSON nel controllo delle versioni e convalidarli in CI.
Il builder viene eseguito interamente nell’SDK. Non chiama nuovi endpoint API e tutto ciò che crea può essere aperto e modificato nell’editor visivo della dashboard.
Requisiti
- Python: il pacchetto
elevenlabs. Il builder viene importato daelevenlabs.agent_workflows. - JavaScript: il pacchetto
@elevenlabs/elevenlabs-js. Il builder viene esportato dalla root del pacchetto.
Crea un workflow
L’oggetto Workflow rappresenta il nodo iniziale. Ogni verbo aggiunge un nodo e lo restituisce, così puoi concatenare il passaggio successivo:
I metodi di routing stabiliscono quale arco porta al nodo successivo:
I verbi chiamati direttamente sul workflow si diramano dal nodo iniziale con un arco incondizionato. Questo esempio indirizza i chiamanti a una ricerca dell’ordine, ritenta l’identificazione se la ricerca non riesce e trasferisce i chiamanti VIP o frustrati:
build() convalida l’intero grafo e restituisce il modello della richiesta. Inoltre:
- Assegna al nodo iniziale l’ID
start_node, richiesto dall’API. - Genera ID degli archi nel formato
source__target. - Compila
edge_orderdi ogni nodo nell’ordine in cui hai aggiunto gli archi. - Posiziona tutti i nodi senza posizione, in modo che il grafo sia disposto da sinistra a destra nell’editor visuale.
Scrivere un workflow in un’unica catena
up() restituisce il nodo da cui è stato concatenato quello corrente, così puoi descrivere un intero workflow in un’unica espressione invece di conservare ogni nodo in una variabile. All’interno di una singola catena, usa go_to() / goTo() con un ID nodo, perché non c’è una variabile da passare:
Per un handle di nodo da wf.node(id), up() restituisce il nodo da cui proviene il primo arco in entrata. Per il nodo iniziale, restituisce il nodo iniziale.
Opzioni del nodo
Le impostazioni facoltative vanno negli argomenti keyword in Python e in un oggetto options finale in JavaScript. I loro nomi corrispondono ai campi del nodo nell’API:
Ogni verbo accetta anche position se vuoi posizionare il nodo manualmente. Workflow(prevent_subagent_loops=True) in Python, oppure new Workflow({ preventSubagentLoops: true }) in JavaScript, impedisce alla conversazione di rientrare in un subagente già visitato.
Destinazioni di trasferimento
Condizioni
when() accetta una stringa semplice, una Condition o un Expr:
- Una stringa è una condizione LLM: l’LLM decide se è soddisfatta.
Condition.llm(text, label=...)è equivalente, con un’etichetta mostrata sull’arco nell’editor visuale. UsaCondition.expr(expr, label=...)per etichettare un’espressione.- Un
Exprviene valutato rispetto alle variabili dinamiche, senza chiamare l’LLM.
Crea espressioni da Expr.variable(name) e Expr.literal(value). Confrontale con eq, neq, gt, gte, lt e lte, ed esegui operazioni aritmetiche con add, sub, mul e div. Combinale con all_of / allOf, any_of / anyOf e if_else / ifElse. I valori semplici vengono racchiusi in Expr.literal() automaticamente. Expr.llm(description) chiede all’LLM di estrarre un valore dalla conversazione; passa type e enum per ottenere una stringa, un numero o uno di un insieme fisso, anziché un booleano.
Cicli e archi all’indietro
L’API consente un arco tra due nodi qualsiasi, in entrambe le direzioni. Per permettere alla conversazione di tornare da dove è arrivata, assegna all’arco una condizione all’indietro con back:
go_to() / goTo() gestisce automaticamente il caso più comune. Quando il nodo di destinazione ha già un arco che conduce qui, il nuovo arco diventa la condizione all’indietro di quell’arco. Nel primo esempio, failed.go_to(identify) viene inviato come condizione all’indietro dell’arco identify → lookup_order. Qualsiasi altro secondo arco tra gli stessi due nodi, e qualsiasi arco da un nodo a sé stesso, non supera la convalida.
Modificare un agente esistente
Workflow.from_agent() / Workflow.fromAgent() carica il workflow di un agente restituito da agents.get(). Gli ID dei nodi, gli ID degli archi, le posizioni nell’editor e l’ordine degli archi vengono mantenuti, quindi il caricamento di nuovo modifica soltanto ciò che hai cambiato.
insert_between() / insertBetween() passa alla tua funzione un ramo che conserva la condizione dell’arco sostituito. La funzione restituisce l’ultimo nodo aggiunto, che viene poi collegato alla destinazione originale. Il metodo restituisce quel nodo, oppure None / undefined se non esiste alcun arco tra i due nodi.
Archiviare i workflow nel controllo versione
to_json_string() / toJSONString() scrive il workflow nel formato wire dell’API: chiavi in snake_case, ordinate a ogni livello, con rientri di 2 spazi. È lo stesso formato usato dall’API REST e dalla CLI, ed entrambi gli SDK scrivono file identici byte per byte per lo stesso workflow, così le differenze restano minime. Workflow.from_json() / Workflow.fromJSON() lo rilegge e accetta anche una configurazione completa dell’agente con una chiave workflow, come un file nella directory agent_configs/ della CLI.
Una configurazione tipica:
Inizializza il file
Carica l’agente con from_agent() / fromAgent() e scrivilo su file, oppure recuperalo con elevenlabs agents pull.
Modifica
Modifica direttamente il JSON oppure caricalo con from_json() / fromJSON() e modificalo con il
builder in uno script.
Visualizzare un workflow
La CLI disegna un file di workflow come diagramma di flusso, così puoi controllare cosa ha creato il tuo codice senza aprire la dashboard. Accetta un file di workflow autonomo scritto da to_json_string() / toJSONString(), oppure una configurazione dell’agente con una chiave workflow:
Per impostazione predefinita, disegna riquadri e frecce nel terminale, con ogni condizione dell’arco numerata sul relativo arco e riportata in una legenda sottostante. Usa --format mermaid per stampare invece il codice sorgente Mermaid, oppure --format mermaid-md per racchiuderlo in un blocco di codice delimitato che GitHub visualizza, ad esempio in un commento a una pull request:
Il comando legge soltanto file locali, quindi non richiede una chiave API e può essere eseguito in CI.
Convalida
Le chiamate concatenate non falliscono mai da sole. build(), to_json() / toJSON() e to_json_string() / toJSONString() controllano l’intero grafo e sollevano o generano un unico WorkflowValidationError il cui elenco issues riporta ogni problema, ciascuno con un code, un message e il node_id / nodeId a cui si riferisce.
Gli errori includono:
- Due archi tra la stessa coppia di nodi o un arco da un nodo a sé stesso.
- Un arco in entrata nel nodo iniziale o in uscita da un nodo finale.
- Un arco da un nodo strumento che non è un arco di successo o fallimento, oppure un arco di successo o fallimento da qualsiasi altro tipo di nodo.
- Due nodi con lo stesso ID o un arco verso un nodo inesistente.
I nodi non raggiungibili dal nodo iniziale vengono segnalati come avvisi, tramite on_warning / onWarning, e non bloccano la build.
Tipi di nodo più recenti del tuo SDK
Un workflow caricato dall’API o da un file può contenere tipi di nodo che la versione del tuo SDK non conosce ancora. Passano invariati attraverso from_json() / fromJSON() e to_json_string() / toJSONString(), mentre build() segnala ciascuno di essi come avviso. Il modello di richiesta tipizzato non può includerli, quindi aggiorna l’SDK oppure invia direttamente il formato wire: