Flujos de trabajo en las instrucciones
En palabras sencillas: un flujo de trabajo es un proceso escrito como pasos con nombre. Cada paso dice qué ocurre (un agente redacta, se llama a una herramienta, una persona decide) y qué pasos deben terminar antes. Las dos primeras secciones muestran toda la idea; el resto es el lenguaje completo, para cuando lo necesites.
Esta es una traducción de la referencia de la especificación. El texto normativo es el inglés; las palabras clave, los nombres de los campos y los ejemplos se dejan como en el original.
Dialecto: instruction/workflow. Revisión: 1.
Estado: borrador de trabajo de la primera edición. Es una parte nativa de instruction.md.
Fecha: 2026-10-28.
Los flujos de trabajo en las instrucciones (Instruction Workflows) describen procesos reutilizables como pasos tipados con nombre. El lenguaje abarca disparadores, flujo de datos, llamadas a modelos y herramientas, rutas condicionales, trabajo en paralelo, decisiones humanas, esperas duraderas, recuperación y resultados finales. AgentD aportó el lenguaje inicial; ahora se especifica aquí con independencia de cualquier entorno de ejecución. Una implementación anuncia qué tipos de nodo y qué capacidades de expresiones, identidad, almacenamiento e integración admite.
El esquema del flujo de trabajo y el registro de nodos son partes normativas de esta referencia, legibles por máquinas. El registro conserva los 74 tipos importados, incluidos los 11 tipos de disparador. La validación con el esquema es solo una capa de validación; los requisitos del grafo y de comportamiento que siguen también se aplican. Un renderizador no es un host de flujos de trabajo.
Declarar un flujo de trabajo
:::workflow{id=brief dialect="instruction/workflow"}
name: morning-brief
steps:
start:
kind: manual
draft:
kind: agent
depends_on: [start]
instruction: Prepare a concise daily brief. Preserve uncertainty.
review:
kind: human
depends_on: [draft]
question: Accept this brief?
schema: { type: string, enum: [accept, revise] }
route:
kind: switch
depends_on: [review]
on: "{{ steps.review.output }}"
cases: { accept: accepted, revise: revision }
accepted:
kind: finish
depends_on: [route]
output: "{{ steps.draft.output }}"
revision:
kind: finish
depends_on: [route]
status: cancelled
reason: The reviewer requested a revision.
:::
El id exterior es la identidad de un objeto de la instrucción; name es la
identidad del flujo de trabajo dentro de su host. dialect selecciona este
contrato. YAML y JSON son representaciones equivalentes del mismo modelo. Las
claves de asignación duplicadas son errores. El cuerpo estructurado de un flujo
de trabajo es literal: las directivas de Markdown y las sustituciones
${parameter} de la instrucción no se activan dentro de él. Las plantillas
{{ … }} del flujo de trabajo tienen los significados que se describen más
abajo.
Abrir, analizar, resolver, compilar o renderizar la instrucción MUST NOT (no debe) armar disparadores, registrar herramientas, exponer rutas, enviar mensajes ni iniciar una ejecución. La activación es una operación explícita del host, posterior a la validación y la autorización.
Campos de la definición
| Campo | Significado |
|---|---|
name |
Identificador obligatorio, de 1 a 64 caracteres, que coincide con [A-Za-z_][A-Za-z0-9_-]* |
steps |
Asignación obligatoria de identificadores de pasos a definiciones tipadas |
description |
Propósito legible para las personas; también puede servir como descripción de una herramienta registrada |
armed |
Si una definición activada de forma explícita puede armar sus disparadores; por defecto, true |
inputs.schema, outputs.schema |
Esquemas de los datos de entrada de la ejecución y del resultado final |
concurrency |
max_runs, on_overflow (queue, drop, replace) y scope (workflow, key) |
key |
Plantilla del momento del disparo que identifica la entidad a la que se refiere una ejecución; obligatoria para la concurrencia por clave |
limits |
Pasos, tokens, plazo y presupuesto por ejecución |
priority |
low, normal o high; una preferencia de planificación, nunca una concesión de permisos |
durable |
Si el estado de la ejecución sobrevive al proceso del host; false permite de forma explícita ejecuciones solo en memoria |
state |
Esquemas declarados de las variables de la ejecución y reductores para escrituras concurrentes |
unload |
Política de retirada: drain, cancel o detach, con un tiempo de espera opcional |
tool |
Interfaz propuesta de flujo de trabajo invocable: nombre, modo síncrono o asíncrono y permisos para quienes lo llaman |
act_for |
Principal delegado y mecanismo de consentimiento propuestos; se requiere la aprobación del operador |
Los campos estándar desconocidos y los nombres de tipo desconocidos son
errores. Los campos con espacio de nombres x-* pueden llevar datos de
extensión declarados. Un host MUST (debe) informar de una extensión no admitida
que afecte al comportamiento, en lugar de descartarla en silencio. Las
directivas de configuración que cargan un archivo, una URL, una carpeta o un
recurso de MCP pertenecen a la configuración del host; no son definiciones
alternativas de flujos de trabajo.
Los datos de entrada se validan antes de la admisión. Unos datos de entrada no
válidos no crean una ejecución. Los resultados completados deben cumplir
outputs.schema; un fallo del esquema no es una finalización correcta. Los
límites de recursos y la admisión por concurrencia deben registrarse en el
perfil de ejecución, para que el resultado pueda revisarse.
Grafos, ámbitos y validación
El grafo de dependencias es acíclico. Los identificadores de los pasos son
únicos dentro de un ámbito. Cada paso de nivel superior debe ser alcanzable
desde un disparador a través de dependencias o de aristas de enrutamiento
explícitas. Un grafo de nivel superior necesita al menos un disparador y un
finish. Los nombres de las dependencias, los destinos del conmutador, los
destinos de error y los destinos de tiempo agotado deben existir en el mismo
ámbito. Los valores de los casos del conmutador nombran un paso como cadena,
no una lista.
foreach, batch, iterate y subgraph contienen body: {steps: …}.
parallel y race contienen branches con nombre, cada una con sus propios
steps. Las dependencias dentro de un cuerpo nombran pasos hermanos. Los
ámbitos anidados no pueden contener disparadores ni finish; su resultado son
sus pasos terminales. El anidamiento máximo es de cuatro niveles de cuerpo, y
las definiciones de nivel superior contienen como máximo 512 pasos. Los
identificadores de instancia generados indican la iteración o la rama, por
ejemplo each[0].draft, parallel{research}.fetch o sub.review.
Una implementación debe validar los tipos, los campos obligatorios de cada tipo, los ámbitos, las referencias, la alcanzabilidad, los ciclos, las capacidades de expresiones y los límites antes de la activación. El JSON Schema deja abiertos a propósito algunos valores de datos de los adaptadores; no valida los argumentos de una herramienta remota, todas las rutas de las expresiones, la autorización ni el comportamiento durante la ejecución. Esas comprobaciones requieren los contratos del host y de las integraciones correspondientes. Los tipos obligatorios no admitidos son un error, no una operación vacía.
Disparadores
El registro incluye once, manual, loop, schedule, subscribe,
stream, correlate, signal, event, a2a y webhook.
Un disparador produce un evento para la admisión, en lugar de realizar
directamente el trabajo posterior. Sus datos se convierten en el resultado del
paso del disparador que se activó. En una ejecución se dispara exactamente un
disparador; los disparadores hermanos pasan a skipped y satisfacen las
dependencias. Las asignaciones inputs de un disparador usan los espacios de
nombres payload y env del momento del disparo; los datos de entrada
resultantes se comprueban con inputs.schema.
schedule acepta cron, every o at, con exactamente una fuente de tiempo.
El dialecto cron heredado de cinco campos funciona en UTC. No obtiene un campo
tz implícito: para las repeticiones según el calendario local se puede usar
el dialecto de planificación explícito del bloque schedule independiente. Los
hosts registran la política sobre los disparos perdidos y la reanudación.
loop combina intervalo, retraso y espera creciente con condiciones de
finalización y un número máximo de iteraciones. once y manual distinguen la
activación automática de una ejecución solicitada por el operador.
subscribe lee un recurso de MCP con nombre tras las notificaciones de cambio
y puede aplicar un antirrebote (debounce), filtrar y recoger una ventana
acotada de muestras. stream consume eventos persistidos con filtrado por
tema, desplazamientos y controles de frecuencia y de tamaño de lote.
correlate agrupa eventos relacionados en una ventana acotada, con un límite
para el estado pendiente. signal es una notificación que se dispara por
flanco: la reciben quienes ya están esperando, y una señal enviada antes de que
se registre quien espera no se guarda en un búfer. Cuando haga falta
conservarla, usa un flujo persistido. Los eventos y las suscripciones requieren
una capacidad explícita del host y vinculaciones autenticadas con las fuentes.
a2a vincula los comandos aceptados, los roles de los principales y un esquema
de entrada. webhook describe una ruta de entrada, los métodos, la
autenticación, la frecuencia y la política de respuesta. Declarar cualquiera de
los dos nunca crea un receptor sin autenticar. El host los autoriza y los
vincula durante la activación.
Campos comunes de los pasos
Cada paso tiene kind. Los campos comunes son depends_on, description,
when, timeout, retry, on_error, on_replay, idempotent,
output_schema, budget, cache, skills y otel. Que estén disponibles no
implica que un host admita todos los nodos o integraciones.
timeout limita un intento o una espera propia del nodo. retry.max cuenta
los reintentos posteriores al primer intento, vale entre cero y veinte, y
retry.backoff indica el retraso inicial, que crece de forma exponencial. La
espera entre intentos es duradera, con crecimiento acotado y variación
aleatoria. on_error es fail (por defecto), continue o goto:<step>.
on_replay es retry (por defecto), skip o fail. Un host registra los
valores por defecto y las restricciones vigentes de modelo, herramientas, red y
presupuesto en el perfil de la ejecución.
Los campos de los nodos de red pueden declarar además breaker: {failures, cooldown},
rate e idempotency. Los reintentos atienden el fallo de un intento; los
cortacircuitos (breakers) comparten el estado de una interrupción entre
ejecuciones; los controles de frecuencia posponen el trabajo sin gastar un
intento; la idempotencia permite reconocer una entrega repetida. Estos
controles tienen significados distintos y MUST NOT (no deben) reducirse a un
único contador de reintentos.
Plantillas y expresiones
Una cadena que consta exactamente de un {{ path }} da el valor tipado al que
hace referencia. Una cadena con texto alrededor interpola el valor: conserva
las cadenas y codifica los demás valores como JSON. {{ path | fallback }}
proporciona un valor alternativo solo para una ruta que falta; un null
existente no usa el valor alternativo. Una / inicial selecciona una ruta de
JSON Pointer, útil para los identificadores generados que contienen puntos. Las
rutas que faltan y no tienen valor alternativo hacen fallar el intento.
| Espacio de nombres | Significado |
|---|---|
inputs |
Datos de entrada validados de la ejecución |
run |
Identidad de la ejecución y del flujo de trabajo, inicio, principal, tarea, intento y estado |
steps.<id> |
Estado, resultado, error e intento de un paso; dentro de un cuerpo, los identificadores de los pasos hermanos |
vars |
Variables de la ejecución declaradas o escritas |
env |
Contexto del host y de la ejecución; para cada paso, step, attempt y un idempotency_key estable |
memory |
Claves de memoria duradera vinculadas de forma explícita |
item, index, alias as |
Elemento actual de la colección y su índice |
batch, iteration, branch |
Contexto de ejecución anidada |
CEL: … evalúa una expresión CEL. La condición when, las condiciones de las
aserciones, las expresiones map/filter/reduce, las condiciones de iteración y
los filtros de suscripción usan sus contextos de evaluación documentados. Los
body y branches anidados, los esquemas, los mapas de destinos del
conmutador y los campos que llevan expresiones siguen siendo literales hasta
que su propio nodo los evalúa. Un host que no tenga una capacidad CEL necesaria
debe rechazar la activación. No puede sustituir la expresión por verdadero.
when también puede usar {noul: "statement", state?, model?, confidence?}
para una decisión que toma un modelo. El host representa esa decisión como un
paso <id>.when duradero y con su propio presupuesto. Una respuesta insegura o
con confianza insuficiente significa que la condición no se cumple. El umbral
de decisión vigente debe constar de forma explícita en el perfil de la
ejecución. La condición de una regla escrita en prosa en la instrucción que la
rodea es distinta de esta condición ejecutable del flujo de trabajo.
Los marcadores de secretos como {{secret:NAME}} y {{secret-file:PATH}} solo
se resuelven en los campos de integración autorizados que llevan credenciales.
En cualquier otro lugar siguen siendo literales. Los secretos no se convierten
en resultado ordinario de un paso, en metadatos del documento ni en contenido
de los registros. La resolución de la instrucción no lee el almacén de secretos
del host.
Ramificación y unión
Un when falso de nivel superior o una ruta del conmutador no elegida deja el
paso en estado pruned. Un paso en estado pruned no satisface las
dependencias. Un paso cuyas rutas de entrada están todas en estado pruned
también lo queda; al menos una ruta viva mantiene la unión apta para
ejecutarse. Un paso en estado skipped sí satisface las dependencias. Esta
distinción permite unir ramas desiguales.
Una ruta del conmutador elegida, on_error: goto:… o on_timeout pueden
activar su destino sin esperar a la lista de dependencias de ese destino, pero
no pueden saltarse su condición when. Las aristas de enrutamiento pueden
volver a un paso; el grafo de dependencias debe seguir siendo acíclico y la
ejecución sigue acotada por sus límites. Una ruta de recuperación cuya
condición no se cumple no borra el fallo original.
Dentro de un cuerpo, un when falso produce skipped, lo que permite que los
pasos hermanos siguientes continúen. Los casos del conmutador no elegidos
dentro de los cuerpos siguen quedando en estado pruned. Los hosts y los
visualizadores deben conservar la diferencia en lugar de presentar todos los
nodos inactivos como equivalentes. Una imagen de Mermaid no puede redefinir
este comportamiento.
Trabajo en paralelo, repetido y delegado
parallel ejecuta ramas con nombre; race elige el primer resultado que
cumple los requisitos y cancela el trabajo que pierde. foreach ejecuta un
cuerpo por cada elemento, con tamaño de batch, paralelismo y frecuencia
acotados. batch da un grupo a cada cuerpo. iterate repite según
while/until, con un número máximo de iteraciones. La política de recogida
de resultados se indica de forma explícita con collect. Un cuerpo no puede
heredar en silencio una dispersión sin límite.
workflow invoca un flujo hijo con nombre en modo sync, async o
detached; async devuelve un identificador. join espera esos identificadores
con una política de tiempo de espera, mínimo y resultados parciales. cascade
controla la cancelación de los hijos. subagent delega un trabajo acotado con
herramientas, servidores, habilidades, contexto y presupuestos explícitos. Los
nodos A2A vinculan pares con nombre, contratos de tareas y mensajes, y esperas
de finalización. La delegación puede reducir la autoridad; declarar un hijo no
debe ampliar los permisos vigentes de quien lo llama.
Esperas y decisiones humanas
wait, sleep, human, las esperas de los hijos y las pausas entre
reintentos suspenden el trabajo mediante registros de espera duraderos, no
mediante un hilo bloqueado en memoria. Una espera puede nombrar un recurso, un
evento, una señal, una ejecución, un subagente, una conversación, un webhook,
una tarea u otra condición de espera registrada. on_timeout es un destino de
enrutamiento explícito. Un paso de decisión humana nombra una pregunta, un
esquema de respuesta opcional y el destinatario previsto. Las respuestas se
validan y se vinculan a un principal autorizado; mostrar una etiqueta de
aprobación o marcar una casilla en la documentación no es una aprobación.
Una implementación que declare ejecución duradera debe restaurar las esperas suspendidas y sus plazos. Debe distinguir una declaración guardada de una ejecución activa, y un punto de control del autor de una decisión humana registrada.
Estados de la ejecución y de los pasos
Los estados de la ejecución son running, paused, completed, failed,
refused, cancelled y stalled. Los dos primeros no son finales. Un
finish determina el estado y el resultado finales; si no queda trabajo listo,
ni trabajo en curso, ni un finish, el estado es stalled, o failed cuando
un error anterior causó el bloqueo.
Los estados de los pasos son pending, running, suspended, done,
skipped, pruned, failed, timeout y cancelled. Solo done y skipped
satisfacen una dependencia ordinaria. Un error con on_error: continue
completa el paso con el error registrado. Terminar una ejecución cancela los
pasos sin terminar. Los códigos de salida, los sistemas de persistencia y los
protocolos de cliente son asunto de los adaptadores del entorno de ejecución, y
no sintaxis nueva de Markdown.
Durabilidad, idempotencia y actualizaciones
Un paso con efectos registra el punto de control running antes del efecto.
Los pasos de datos deterministas pueden reproducirse desde el punto de control
anterior. Tras una caída, un efecto que se completó en el lado remoto pero
perdió su confirmación puede entregarse de nuevo. El contrato es de entrega al
menos una vez; no es ejecución remota exactamente una vez.
La clave de idempotencia por defecto son los primeros 32 caracteres
hexadecimales de sha256(run_id + "." + step_instance_id), estables en los
reintentos y las reproducciones de esa instancia. Una clave de negocio
declarada puede eliminar duplicados entre ejecuciones. Para que los duplicados
se eliminen de verdad, las herramientas y los servicios remotos deben respetar
la clave. on_replay controla si el trabajo de estado incierto se reintenta,
se omite o se da por fallido. Un host no debe afirmar que la reproducción es
segura solo porque se envió una clave.
Una ejecución registra el resumen (digest) de su definición y el perfil de
ejecución. Actualizar una definición activa afecta a las admisiones
posteriores; las ejecuciones existentes conservan su definición fijada. La
restauración requiere la definición correspondiente y no debe sustituirla por
el texto más reciente. La retirada aplica unload y registra la cancelación o
la finalización de lo iniciado. La memoria, los artefactos, los desplazamientos
de los flujos de eventos y los puntos de control de los disparadores tienen
duraciones distintas. Los artefactos sensibles conservan los controles de
acceso del host y no se copian en silencio en los paquetes de instrucciones.
Catálogo de nodos y puntos de extensión
La referencia de nodos completa se genera a partir del registro nativo y enumera los campos obligatorios y opcionales de cada tipo importado. Abarca disparadores, control de flujo, transformaciones de datos, memoria, artefactos, conocimiento, búsqueda, MCP, HTTP, A2A, mensajería, ciclo de vida de los flujos de trabajo, operaciones con modelos, agentes y decisiones humanas. Los proveedores de nodos pueden ser integraciones del host independientes; que algo esté en el lenguaje no promete que un host tenga una cuenta o una implementación.
Los hosts de flujos de trabajo publican un perfil de capacidades con los tipos de nodo, las funciones de expresiones, los límites de recursos, las vinculaciones de credenciales e identidad y la compatibilidad con la durabilidad. El comportamiento personalizado usa extensiones declaradas con espacio de nombres, con requisitos explícitos de esquema y de capacidades. Un comportamiento ejecutable desconocido nunca debe resolverse ejecutando una aproximación. Los renderizadores conservan el código fuente y muestran de forma visible la semántica no admitida; el uso solo para visualización puede seguir siendo útil sin un entorno de ejecución.
Un nodo personalizado usa kind: alias:node. Su vinculación exterior de
extensión de la instrucción selecciona un manifiesto y una versión exactos; un
flujo de trabajo independiente obtiene vinculaciones equivalentes del perfil de
su host. provides.workflow_nodes en el manifiesto de la extensión asigna los
nombres de los nodos a un role (trigger o step), un schema del nodo, un
contrato semantics y capacidades requires opcionales. El esquema base del
flujo de trabajo puede conservar el nodo con espacio de nombres, pero la
activación valida además ese manifiesto y su proveedor instalado. Los metadatos
del código fuente nunca instalan código ni autorizan a un proveedor. El
comprobador de grafos nativo y acotado del repositorio rechaza esos nodos como
no admitidos, en lugar de declarar la conformidad de un host de extensiones.
Migración y procedencia
El registro inicial y los campos comunes se importaron, a petición del
propietario, de la instantánea del esquema de AgentD con SHA-256
40f1d4a06967af70705d1b6aa508ebcc7defc7693ad3e8d8570eb02637ac5f23.
La instantánea exacta se conserva en los datos de procedencia.
El esquema de instruction.md añade comprobaciones de campos para cada tipo y
una estructura recursiva explícita del cuerpo. Las comprobaciones del grafo y
de comportamiento siguen siendo independientes.
agentd/workflow sigue siendo un identificador de compatibilidad del
adaptador. Los documentos nativos nuevos usan instruction/workflow; el perfil de AgentD
puede exportar definiciones compatibles a AgentD sin reescribir los datos de
sus pasos. Esta migración no cambió ninguna instalación de AgentD,
configuración de servidor, sitio publicado ni entorno de ejecución. Este
borrador de trabajo y sus nuevos casos de conformidad aún requieren una
revisión independiente de la implementación del entorno de ejecución antes de
una publicación final.