Workflows sous forme de code
Concevez, modifiez et versionnez les workflows d’agents avec les SDK Python et JavaScript
Vue d’ensemble
Un workflow est stocké sous forme de graphe de nœuds et d’arêtes. Écrire ce graphe à la main signifie que vous devez vous-même maintenir la cohérence des ID d’arêtes, des listes edge_order et des objets de condition. Le générateur Workflow des SDK Python et JavaScript vous permet de décrire le même graphe avec des appels de méthode chaînés. Il produit ensuite la valeur workflow que agents.create() et agents.update() acceptent déjà.
Utilisez-le pour :
- Concevoir un workflow dans le code et le réviser comme toute autre modification de code.
- Charger le workflow d’un agent, modifier un nœud et le renvoyer sans perturber le reste du graphe.
- Stocker des workflows au format JSON dans un système de contrôle de version et les valider dans l’intégration continue.
Le générateur s’exécute entièrement dans le SDK. Il n’appelle aucun nouveau point de terminaison d’API, et tout ce qu’il génère peut être ouvert et modifié dans l’éditeur visuel du Dashboard.
Prérequis
- Python : le package
elevenlabs. Le générateur est importé depuiselevenlabs.agent_workflows. - JavaScript : le package
@elevenlabs/elevenlabs-js. Le générateur est exporté depuis la racine du package.
Concevoir un workflow
L’objet Workflow représente le nœud de départ. Chaque verbe ajoute un nœud et le renvoie, ce qui vous permet d’enchaîner l’étape suivante à partir de celui-ci :
Les méthodes de routage déterminent quelle arête mène au nœud suivant :
Les verbes appelés directement sur le workflow créent une branche depuis le nœud de départ avec une arête inconditionnelle. Cet exemple oriente les appelants vers une recherche de commande, réessaie l’identification si la recherche échoue et transfère les appelants VIP ou frustrés :
build() valide l’ensemble du graphe et renvoie le modèle de requête. Il effectue également les opérations suivantes :
- Attribue au nœud de départ l’ID
start_node, exigé par l’API. - Génère des ID d’arête sous la forme
source__target. - Renseigne l’
edge_orderde chaque nœud dans l’ordre où vous avez ajouté les arêtes. - Positionne tout nœud sans position, afin que le graphe soit organisé de gauche à droite dans l’éditeur visuel.
Écrire un workflow sous forme d’une seule chaîne
up() renvoie le nœud à partir duquel le nœud actuel a été enchaîné. Vous pouvez ainsi décrire un workflow entier dans une expression unique plutôt que de conserver chaque nœud dans une variable. Dans une seule chaîne, utilisez go_to() / goTo() avec un ID de nœud, car aucune variable n’est disponible à transmettre :
Pour un handle de nœud issu de wf.node(id), up() renvoie le nœud dont provient la première arête entrante. Pour le nœud de départ, il renvoie le nœud de départ.
Options des nœuds
Les paramètres facultatifs sont transmis sous forme d’arguments nommés en Python et dans un objet d’options final en JavaScript. Leurs noms correspondent aux champs du nœud dans l’API :
Chaque verbe accepte également position si vous souhaitez placer le nœud vous-même. Workflow(prevent_subagent_loops=True) en Python, ou new Workflow({ preventSubagentLoops: true }) en JavaScript, empêche la conversation de revenir dans un sous-agent qu’elle a déjà visité.
Destinations de transfert
Conditions
when() accepte une chaîne simple, une Condition ou un Expr :
- Une chaîne est une condition LLM : le LLM détermine si elle est remplie.
Condition.llm(text, label=...)fait la même chose, avec un libellé affiché sur l’arête dans l’éditeur visuel. UtilisezCondition.expr(expr, label=...)pour libeller une expression.- Un
Exprest évalué par rapport aux variables dynamiques, sans appeler le LLM.
Construisez des expressions à partir de Expr.variable(name) et Expr.literal(value). Comparez-les avec eq, neq, gt, gte, lt et lte, et effectuez des opérations arithmétiques avec add, sub, mul et div. Combinez-les avec all_of / allOf, any_of / anyOf et if_else / ifElse. Les valeurs simples sont automatiquement encapsulées dans Expr.literal(). Expr.llm(description) demande au LLM d’extraire une valeur de la conversation ; transmettez type et enum pour obtenir une chaîne, un nombre ou une valeur parmi un ensemble fixe plutôt qu’un booléen.
Boucles et arêtes de retour
L’API autorise une arête entre deux nœuds quelconques, dans un sens comme dans l’autre. Pour permettre à la conversation de revenir par le même chemin, attribuez à l’arête une condition de retour avec back :
go_to() / goTo() gère automatiquement le cas courant. Lorsque le nœud cible possède déjà une arête qui mène ici, la nouvelle arête devient la condition de retour de cette arête. Dans le premier exemple, failed.go_to(identify) est envoyé comme condition de retour de l’arête identify → lookup_order. Toute autre deuxième arête entre les deux mêmes nœuds, ainsi que toute arête d’un nœud vers lui-même, échoue à la validation.
Modifier un agent existant
Workflow.from_agent() / Workflow.fromAgent() charge le workflow d’un agent renvoyé par agents.get(). Les ID de nœud, les ID d’arête, les positions dans l’éditeur et l’ordre des arêtes sont conservés. Ainsi, lors de son renvoi, seuls vos changements sont appliqués.
insert_between() / insertBetween() transmet à votre fonction une branche qui porte la condition de l’arête remplacée. La fonction renvoie le dernier nœud qu’elle a ajouté, qui est ensuite connecté à la cible d’origine. La méthode renvoie ce nœud, ou None / undefined s’il n’existe aucune arête entre les deux nœuds.
Stocker les workflows dans le contrôle de version
to_json_string() / toJSONString() écrit le workflow au format de transmission de l’API : clés en snake_case, triées à tous les niveaux, avec une indentation de 2 espaces. Il s’agit de la même structure que celle utilisée par l’API REST et la CLI. Les deux SDK écrivent des fichiers identiques octet pour octet pour un même workflow, ce qui limite la taille des différences. Workflow.from_json() / Workflow.fromJSON() le relit et accepte également une configuration d’agent complète avec une clé workflow, comme un fichier dans le répertoire agent_configs/ de la CLI.
Configuration typique :
Initialiser le fichier
Chargez l’agent avec from_agent() / fromAgent() et écrivez-le dans un fichier, ou récupérez-le avec elevenlabs agents pull.
Modifier
Modifiez directement le JSON, ou chargez-le avec from_json() / fromJSON() et modifiez-le avec le
builder dans un script.
Visualiser un workflow
La CLI représente un fichier de workflow sous forme d’organigramme. Vous pouvez ainsi vérifier ce que votre code a généré sans ouvrir le Dashboard. Elle accepte un simple fichier de workflow écrit par to_json_string() / toJSONString(), ou une configuration d’agent avec une clé workflow :
Par défaut, elle dessine des boîtes et des flèches dans le terminal, avec chaque condition d’arête numérotée sur son arête et détaillée dans une légende en dessous. Utilisez --format mermaid pour afficher à la place le code source Mermaid, ou --format mermaid-md pour l’encapsuler dans un bloc de code délimité interprété par GitHub, par exemple dans un commentaire de pull request :
La commande lit uniquement des fichiers locaux. Elle ne nécessite donc aucune clé API et peut s’exécuter dans l’intégration continue.
Validation
Les appels enchaînés n’échouent jamais seuls. build(), to_json() / toJSON() et to_json_string() / toJSONString() vérifient l’ensemble du graphe et lèvent ou génèrent une unique WorkflowValidationError, dont la liste issues répertorie chaque problème avec son code, son message et le node_id / nodeId concerné.
Les erreurs incluent :
- Deux arêtes entre la même paire de nœuds, ou une arête d’un nœud vers lui-même.
- Une arête vers le nœud de départ, ou partant d’un nœud de fin.
- Une arête depuis un nœud d’outil qui n’est pas une arête de succès ou d’échec, ou une arête de succès ou d’échec depuis tout autre type de nœud.
- Deux nœuds avec le même ID, ou une arête vers un nœud inexistant.
Les nœuds inaccessibles depuis le nœud de départ sont signalés comme des avertissements, via on_warning / onWarning, et n’empêchent pas la génération.
Types de nœud plus récents que votre SDK
Un workflow chargé depuis l’API ou depuis un fichier peut contenir des types de nœud que votre version du SDK ne connaît pas encore. Ils transitent sans modification via from_json() / fromJSON() et to_json_string() / toJSONString(), et build() signale chacun d’eux comme un avertissement. Le modèle de requête typé ne peut pas les prendre en charge. Mettez donc à niveau le SDK ou envoyez directement le format de transmission :