Flujos de trabajo como código
Descripción general
Un flujo de trabajo se almacena como un grafo de nodos y aristas. Escribir ese grafo a mano implica mantener por tu cuenta la coherencia entre los ID de aristas, las listas edge_order y los objetos de condición. El constructor Workflow de los SDK de Python y JavaScript te permite describir el mismo grafo con llamadas a métodos encadenadas. Después genera el valor de workflow que agents.create() y agents.update() ya aceptan.
Úsalo para:
- Crear un flujo de trabajo en código y revisarlo como cualquier otro cambio de código.
- Cargar el flujo de trabajo de un agente, cambiar un nodo y volver a enviarlo sin alterar el resto del grafo.
- Almacenar flujos de trabajo como JSON en el control de versiones y validarlos en CI.
El constructor se ejecuta íntegramente en el SDK. No llama a nuevas rutas de API y todo lo que crea puede abrirse y editarse en el editor visual del panel de control.
Requisitos
- Python: el paquete
elevenlabs. El constructor se importa desdeelevenlabs.agent_workflows. - JavaScript: el paquete
@elevenlabs/elevenlabs-js. El constructor se exporta desde la raíz del paquete.
Crea un workflow
El objeto Workflow representa el nodo de inicio. Cada verbo añade un nodo y lo devuelve, para que puedas encadenar el siguiente paso desde él:
Los métodos de enrutamiento deciden qué arista lleva al siguiente nodo:
Los verbos llamados directamente en el workflow se ramifican desde el nodo de inicio con una arista incondicional. Este ejemplo dirige a quienes llaman a una consulta de pedidos, reintenta la identificación si la consulta falla y transfiere a quienes llaman que son VIP o están frustrados:
build() valida todo el grafo y devuelve el modelo de solicitud. También:
- Asigna al nodo de inicio el ID
start_node, que requiere la API. - Genera ID de aristas con el formato
source__target. - Completa el
edge_orderde cada nodo en el orden en que añadiste las aristas. - Posiciona cualquier nodo que no tenga posición, para que el grafo se distribuya de izquierda a derecha en el editor visual.
Escribe un workflow como una sola cadena
up() devuelve el nodo desde el que se encadenó el actual, para que puedas describir un workflow completo en una expresión en lugar de guardar cada nodo en una variable. Dentro de una sola cadena, usa go_to() / goTo() con un ID de nodo, ya que no hay ninguna variable que pasar:
Para un manejador de nodo de wf.node(id), up() devuelve el nodo del que procede la primera arista que entra en él. Para el nodo de inicio, devuelve el nodo de inicio.
Opciones de nodo
Los ajustes opcionales se indican como argumentos con nombre en Python y en un objeto de opciones final en JavaScript. Sus nombres coinciden con los campos del nodo en la API:
Cada verbo también acepta position si quieres colocar el nodo manualmente. Workflow(prevent_subagent_loops=True) en Python, o new Workflow({ preventSubagentLoops: true }) en JavaScript, evita que la conversación vuelva a entrar en un subagente que ya ha visitado.
Destinos de transferencia
Condiciones
when() acepta una cadena simple, un Condition o un Expr:
- Una cadena es una condición de LLM: el LLM decide si se cumple.
Condition.llm(text, label=...)es lo mismo, con una etiqueta que se muestra en la arista del editor visual. UsaCondition.expr(expr, label=...)para etiquetar una expresión.- Un
Exprse evalúa con variables dinámicas, sin llamar al LLM.
Crea expresiones con Expr.variable(name) y Expr.literal(value). Compáralas con eq, neq, gt, gte, lt y lte, y realiza operaciones aritméticas con add, sub, mul y div. Combínalas con all_of / allOf, any_of / anyOf e if_else / ifElse. Los valores simples se envuelven en Expr.literal() automáticamente. Expr.llm(description) pide al LLM que extraiga un valor de la conversación; pasa type y enum para obtener una cadena, un número o uno de un conjunto fijo en lugar de un booleano.
Bucles y aristas hacia atrás
La API permite una arista entre dos nodos cualesquiera, en cualquier dirección. Para permitir que la conversación vuelva por donde vino, asigna a la arista una condición hacia atrás con back:
go_to() / goTo() gestiona el caso habitual automáticamente. Cuando el nodo de destino ya tiene una arista que lleva hasta aquí, la nueva arista se convierte en la condición hacia atrás de esa arista. En el primer ejemplo, failed.go_to(identify) se envía como condición hacia atrás de la arista identify → lookup_order. Cualquier otra segunda arista entre los mismos dos nodos, y cualquier arista de un nodo a sí mismo, no supera la validación.
Edita un agente existente
Workflow.from_agent() / Workflow.fromAgent() carga el workflow de un agente devuelto por agents.get(). Se conservan los ID de nodos, los ID de aristas, las posiciones del editor y el orden de las aristas, por lo que al volver a enviarlo solo cambia lo que hayas modificado.
insert_between() / insertBetween() pasa a tu función una rama que contiene la condición de la arista reemplazada. La función devuelve el último nodo que añadió, que después se conecta al destino original. El método devuelve ese nodo, o None / undefined si no hay ninguna arista entre los dos nodos.
Guarda workflows en el control de versiones
to_json_string() / toJSONString() escribe el workflow en el formato de transmisión de la API: claves en snake_case, ordenadas en todos los niveles y con sangría de 2 espacios. Tiene la misma estructura que usan la API REST y la CLI, y ambos SDK escriben archivos idénticos byte a byte para el mismo workflow, por lo que los diffs se mantienen pequeños. Workflow.from_json() / Workflow.fromJSON() lo vuelve a leer y también acepta una configuración completa de agente con una clave workflow, como un archivo del directorio agent_configs/ de la CLI.
Una configuración habitual:
Genera el archivo inicial
Carga el agente con from_agent() / fromAgent() y escríbelo en un archivo, o extráelo con elevenlabs agents pull.
Edita
Modifica el JSON directamente, o cárgalo con from_json() / fromJSON() y edítalo con el
builder en un script.
Visualiza un workflow
La CLI dibuja un archivo de workflow como un diagrama de flujo, para que puedas comprobar lo que ha creado tu código sin abrir el panel. Acepta un archivo de workflow independiente escrito por to_json_string() / toJSONString(), o una configuración de agente con una clave workflow:
De forma predeterminada, dibuja cuadros y flechas en la terminal, con cada condición de arista numerada en su arista y desarrollada en una leyenda debajo. Usa --format mermaid para imprimir en su lugar código fuente de Mermaid, o --format mermaid-md para envolverlo en un bloque de código delimitado que GitHub renderiza, por ejemplo, en un comentario de pull request:
El comando solo lee archivos locales, por lo que no necesita una clave de API y puede ejecutarse en CI.
Validación
Las llamadas encadenadas nunca fallan por sí solas. build(), to_json() / toJSON() y to_json_string() / toJSONString() comprueban todo el grafo y generan o lanzan un único WorkflowValidationError cuya lista issues enumera cada problema, cada uno con un code, un message y el node_id / nodeId al que se refiere.
Los errores incluyen:
- Dos aristas entre el mismo par de nodos o una arista de un nodo a sí mismo.
- Una arista hacia el nodo de inicio o que sale de un nodo final.
- Una arista desde un nodo de herramienta que no sea una arista de éxito o fallo, o una arista de éxito o fallo desde cualquier otro tipo de nodo.
- Dos nodos con el mismo ID o una arista a un nodo que no existe.
Los nodos a los que no se puede llegar desde el nodo de inicio se notifican como advertencias, mediante on_warning / onWarning, y no detienen la compilación.
Tipos de nodo más recientes que tu SDK
Un workflow cargado desde la API o desde un archivo puede contener tipos de nodo que tu versión del SDK aún no conoce. Se conservan sin cambios al pasar por from_json() / fromJSON() y to_json_string() / toJSONString(), y build() notifica cada uno como una advertencia. El modelo de solicitud tipado no puede incluirlos, así que actualiza el SDK o envía directamente el formato de transmisión: