Blog · Guía · 29 de octubre de 2026

Estados y transiciones de un workflow de AEGIS, paso a paso

También en: English, Português, 日本語, Deutsch, Français, 한국어, 简体中文, Italiano, हिन्दी · Todas las guías en español

Aviso: en 100monkeys.ai construimos AEGIS, así que lee esta guía como el relato de quien lo fabrica. La redactó uno de nuestros agentes de IA a partir de la documentación pública de AEGIS, sobre todo la Workflow Manifest Reference y la CLI Reference, y la revisó la empresa; esta versión en español es una traducción de la guía original en inglés. Cada línea de YAML y cada comando de abajo están copiados de esas páginas, y ninguno se ejecutó para esta guía. Las citas van en inglés con la traducción al lado. Donde la documentación deja una pregunta abierta, la última sección lo dice.

AEGIS by 100monkeys.ai, in beta, ejecuta un workflow como una máquina de estados finitos escrita en un único archivo YAML. La referencia lo llama "a durable, restartable sequence" (una secuencia duradera y reiniciable) que coordina agentes, contenedores, comandos del sistema y puertas de aprobación humana. Esta guía escribe un estado cada vez y muestra cómo el motor elige el siguiente.

Paso 1. Escribe la cabecera

apiVersion: 100monkeys.ai/v1
kind: Workflow

metadata:
  name: dev-pipeline
  version: "1.0.0"

apiVersion debe ser exactamente 100monkeys.ai/v1 y kind exactamente Workflow. name sigue ^[a-z0-9][a-z0-9-]{0,62}$, y el par de nombre y versión debe ser único: sobrescribir una versión existente necesita el parámetro force. metadata.input_schema es opcional; si está presente, la entrada de quien llama se valida antes de que empiece la ejecución, y una carga que no pasa queda "rejected with HTTP 422; no workflow execution is created." (rechazada con HTTP 422; no se crea ninguna ejecución del workflow).

Paso 2. Nombra el primer estado y los límites

Bajo spec, initial_state es obligatorio y debe existir en spec.states. Dos límites detienen un bucle que nunca acaba. spec.max_total_transitions vale 50 por defecto, con un tope de 100, después del cual "the workflow terminates" (el workflow termina). El max_state_visits de cada estado vale 5 por defecto, con un tope de 20. Cada estado tiene además un timeout, 300s por defecto. spec.context guarda constantes que todo estado lee como {{workflow.context.KEY}}, como un límite de iteraciones o un umbral.

Paso 3. Elige un tipo para cada estado

Cada estado nombra un kind. La referencia enumera ocho:

Agent ejecuta un agente desplegado y escribe su status, output, score e iterations bajo el nombre del estado.
System ejecuta un command de shell y registra stdout, stderr y exit_code.
Action ejecuta una de las operaciones propias del workflow, como update_blackboard o repository_commit: "no agent chooses or calls it, and no shell runs." (ningún agente la elige ni la llama, y no se ejecuta ningún shell).
Human suspende la ejecución hasta que una persona responde.
ParallelAgents ejecuta varios jueces y combina sus puntuaciones con una estrategia de consenso.
ContainerRun y ParallelContainerRun ejecutan pasos en contenedores, para trabajo de CI y CD.
Subworkflow inicia otro workflow, bloqueante o sin esperar respuesta, hasta una profundidad máxima de 10.

Paso 4. Escribe las transiciones en el orden en que quieres que se prueben

Las transiciones se "evaluated top-to-bottom. The first matching transition is taken." (evalúan de arriba abajo. Se toma la primera transición que coincide). Cada una nombra un estado target y, opcionalmente, una condition. Este estado System, del propio ejemplo de la referencia, se ramifica según el código de salida:

    EXECUTE:
      kind: System
      command: python main.py
      env:
        CODE: "{{GENERATE.output}}"
        PYTHONPATH: /workspace
      transitions:
        - condition: exit_code_zero
          target: VALIDATE
        - condition: exit_code_non_zero
          target: REFINE
          feedback: "Execution failed: {{EXECUTE.output.stderr}}"

Las condiciones que puede usar cada tipo: on_success y on_failure para la mayoría; exit_code_zero, exit_code_non_zero y exit_code con un value para System y ContainerRun; input_equals, input_equals_yes e input_equals_no para Human; consensus, all_approved y any_rejected para ParallelAgents; custom con una expression de Handlebars para cualquier tipo; y always, o ninguna condición, como respaldo incondicional. El consejo de la referencia: "Always include an unconditional fallback as the last transition." (Incluye siempre un respaldo incondicional como última transición).

Paso 5. Ramifica según una puntuación

    VALIDATE:
      kind: Agent
      agent: judge-v1
      transitions:
        - condition: score_above
          threshold: 0.95
          target: COMPLETE
        - condition: score_below
          threshold: 0.95
          target: REFINE
          feedback: "{{VALIDATE.output.reasoning}}"

Las dos comparaciones son estrictas, así que una puntuación de exactamente 0.95 no toma ninguna de las dos transiciones de arriba. La puntuación se lee del score del estado, si no de final_score, si no de consensus.score. Un estado sin puntuación no coincide con ninguna, y si nada más coincide la ejecución falla con State "<name>" carries no score for its score transitions. score_between toma min y max inclusivos para un estado Agent.

Paso 6. Lleva lo ocurrido al siguiente estado

La cadena feedback de una transición se convierte en {{state.feedback}} en el estado al que lleva; así llega un mensaje de fallo al agente que reintenta. Cada estado terminado se escribe en el Blackboard bajo su nombre, de modo que los estados posteriores leen {{EXECUTE.output.stdout}} o {{VALIDATE.score}}. Mantén separados dos espacios de nombres: {{input.KEY}} es lo que pasó quien llama y "is immutable" (es inmutable), mientras que {{blackboard.KEY}} crece a medida que avanza la ejecución. Una plantilla que nombra una clave que ningún estado ha escrito todavía muestra un marcador visible, ERROR: missing key con el nombre del estado, en lugar de una cadena vacía.

Paso 7. Haz un bucle con guarda y termina la ejecución

    REFINE:
      kind: System
      command: update_context
      env:
        ITERATION: "{{blackboard.iteration_number + 1}}"
        ERRORS: "{{state.feedback}}"
      transitions:
        - condition: custom
          expression: "{{blackboard.iteration_number < workflow.context.max_iterations}}"
          target: GENERATE
        - condition: custom
          expression: "{{blackboard.iteration_number >= workflow.context.max_iterations}}"
          target: FAILED

    COMPLETE:
      kind: System
      command: finalize
      transitions: []

Un estado con transitions: [] es final: "When reached, the workflow execution completes with status completed." (Al alcanzarlo, la ejecución del workflow termina con estado completed). Da al bucle su propia guarda en el Blackboard, como arriba, además de apoyarte en max_state_visits.

Paso 8. Valida, despliega, ejecuta y observa las transiciones

aegis workflow validate ./pipeline.yaml
aegis workflow deploy ./pipeline.yaml
aegis workflow run dev-pipeline --input '{"task": "..."}'
aegis workflow logs <execution_id> --transitions

validate comprueba el manifiesto en local; deploy lo registra y falla con un nombre y versión existentes salvo que añadas --force; logs --transitions muestra "state entries/exits only" (solo entradas y salidas de estados), que es la forma más rápida de ver qué rama tomó cada estado.

Lo que la documentación deja abierto

Palabras de la puerta. La Workflow Manifest Reference hace que input_equals_yes acepte "yes", "approve", "approved" o "true"; la página Human Approvals dice yes, y o 1. Prueba tu puerta antes de fiarte de cualquiera de las dos listas.
Una segunda sintaxis. El ejemplo de Blackboard de la misma página escribe kind: agent, input_template y transiciones como on: success con next:, donde el resto de la referencia escribe kind: Agent, input, condition y target. La página no dice si el motor acepta ambas.
Aritmética en plantillas. El ejemplo fija {{blackboard.iteration_number + 1}}, pero los operadores enumerados para expresiones son solo de comparación y lógica, sin +.
Sin coincidencia. Salvo en el caso de la puntuación, la referencia no dice qué ocurre cuando un estado termina y ninguna de sus transiciones coincide.
Cuántos tipos. El índice de la documentación habla de "all seven state kinds" (los siete tipos de estado); la tabla de la referencia enumera ocho.

Para el estado Human en detalle, con lo que ve quien revisa y lo que significa el silencio, lee Cómo dar a un orquestador un paso de aprobación. AEGIS se instala con el comando que aparece en 100monkeys.ai:

curl -fsSL https://get.100monkeys.ai | bash

Instala AEGIS desde 100monkeys.ai