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

Markdown
:::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.