Cómo convertir tareas puntuales de un agente en workflows reutilizables

Para que una tarea de varios pasos de un agente de IA sea reutilizable, guarda sus pasos como definiciones de modelos tipadas y un archivo de workflow declarativo en tu repositorio. Así, la siguiente sesión ejecuta el proceso guardado en lugar de reconstruirlo a partir de un prompt.

Seguramente te ha pasado: un agente realiza una verificación de release impecable (tests, build y smoke test, todo en el orden correcto), luego la sesión se cierra y el proceso desaparece con ella. Al día siguiente vuelves a describirlo y obtienes una versión ligeramente distinta.

Este artículo muestra cómo conservar ese proceso con Swamp. Explica qué se vuelve reutilizable y qué no, presenta un pequeño workflow de verificación de release y muestra cómo ese mismo workflow se ejecuta con Claude Code, Cursor, OpenCode o Codex.

Por qué desaparece una buena ejecución del agente

Una sesión de agente conserva su proceso de trabajo únicamente en el contexto de la conversación, por lo que el proceso termina cuando termina la sesión. Los comandos que ejecutó, el orden que eligió y las comprobaciones que añadió no se guardan en ningún lugar desde el que la siguiente sesión pueda ejecutarlos. Lo único que queda es la transcripción del chat y los archivos que se hayan modificado por el camino.

La solución es convertir el proceso del agente en archivos del repositorio que se ejecutan. Una vez que los pasos viven en el repositorio, dejas de explicar la tarea en cada sesión, y el tiempo del agente se dedica a hacer cambios en lugar de a reconstruir el procedimiento.

Workflows reutilizables de agentes de IA con Swamp: qué persiste y qué no

Swamp es una herramienta de línea de comandos que almacena la automatización funcional de un agente como modelos tipados, definiciones YAML, workflows, datos versionados y referencias a vaults en un directorio .swamp/ dentro de un repositorio Git. El README de Swamp enumera seis conceptos fundamentales: modelos, que describen sistemas externos como tipos; definiciones, que son archivos YAML que configuran un uso concreto de un tipo de modelo; workflows; datos; vaults; y etiquetas (tags).

Swamp hace repetible el proceso, no el razonamiento. Una vez que los pasos de un agente se guardan como definiciones de modelos y un archivo de workflow, las ejecuciones posteriores ejecutan esos pasos guardados. Sin embargo, cuando el agente los crea o los edita, su resultado puede variar de una sesión a otra.

Swamp y MCP cumplen funciones distintas. MCP conecta un agente con herramientas, como explica la guía para desarrolladores sobre el ecosistema MCP. Swamp almacena y ejecuta la automatización que el agente construye con esas herramientas, y puedes usar ambos a la vez. Swamp se ejecuta en tu propia máquina, y las credenciales que utiliza provienen del entorno de la shell que lo inicia.

Configuración de Swamp para tu harness

Instala el binario con el script oficial y luego inicializa el repositorio para tu harness. El script de instalación oficial es compatible con macOS y Linux, y también se publican binarios de release para Windows.

curl -fsSL https://swamp-club.com/install.sh | sh

swamp repo init                    # Claude Code (default)
swamp repo init --tool cursor      # or: opencode, codex

Claude Code lee las skills de Swamp desde .claude/skills/ y sus instrucciones desde CLAUDE.md. Cursor usa .cursor/skills/ y .cursor/rules/swamp.mdc. OpenCode y Codex usan ambos .agents/skills/ y AGENTS.md.

Swamp incluye las skills dentro de su binario y las escribe al ejecutar init, y así es como el agente las encuentra sin configuración adicional. El autocompletado para la shell está disponible mediante swamp completions <shell>.

Un workflow de verificación de release, de principio a fin

Un workflow de Swamp es un archivo YAML que organiza los jobs como un DAG, y cada step invoca un método de una definición de modelo. Como explica How Swamp Works, cada job espera a los jobs de los que depende, y los steps de un mismo job se ejecutan en paralelo salvo que uno dependa de otro.

Lo habitual es pedirle al agente que cree las definiciones run-tests, build-artifact y smoke-test. Aun así, revisa el workflow resultante, porque es el archivo que estás aprobando. La estructura siguiente se basa en la referencia de workflows. Los marcadores <method> se han dejado a propósito: sustitúyelos por los nombres de los métodos que exponen realmente tus definiciones.

id: <keep the generated id>
name: release-check
tags:
  purpose: release
jobs:
  - name: checks
    description: Run tests and build in parallel
    steps:
      - name: tests
        task:
          type: model_method
          modelIdOrName: run-tests
          methodName: <method>
      - name: build
        task:
          type: model_method
          modelIdOrName: build-artifact
          methodName: <method>
  - name: smoke
    dependsOn:
      - job: checks
        condition:
          type: succeeded
    steps:
      - name: smoke
        task:
          type: model_method
          modelIdOrName: smoke-test
          methodName: <method>
version: 1

En el workflow de verificación de release, los tests y el build se ejecutan al mismo tiempo. condition.type: succeeded retiene el job de smoke test hasta que ambos se completen con éxito. Valida el archivo con swamp workflow validate release-check y luego ejecútalo:

swamp workflow run release-check
swamp workflow run release-check --tag env=staging
swamp data query 'attributes.ok == false'   # example query from the Swamp manual

swamp workflow run espera hasta que la ejecución termina (con éxito, con error o por cancelación) o se detiene en una puerta manual_approval. Una ejecución correcta finaliza con código 0 y cualquier otro resultado devuelve un código distinto de cero, por lo que el CI puede condicionar sus etapas a ese resultado. El flag --tag sobrescribe las etiquetas en tiempo de ejecución. Cada ejecución guarda sus salidas como datos versionados que no se pueden modificar después, y puedes recuperarlos por etiqueta, de modo que una sesión posterior puede consultar lo que ocurrió en lugar de reconstruirlo a partir del historial del chat. La expresión de data query procede del ejemplo de How Swamp Works y debe adaptarse a los campos de tu modelo.

Que el step de smoke test pase solo demuestra que el endpoint respondió. No demuestra que la página se renderizara ni que los usuarios pudieran completar un flujo. Reproducir sesiones sobre el build desplegado en staging es la forma de hacer visibles ese tipo de regresiones de front-end.

Llevar el mismo workflow a otros harnesses

Cuando un equipo lleva un workflow de Swamp de un harness a otro, lo que comparte son los archivos de modelos, definiciones y workflows. El directorio de skills de cada harness está incluido en .gitignore y lo escribe el propio Swamp, y swamp repo upgrade --tool <name> permite a un desarrollador cambiar de harness o usar varios en paralelo. El README indica que cada herramienta tiene su propia carpeta de skills, que se mantiene fuera de Git.

Supongamos que el repositorio se inicializó para Claude Code y que un compañero usa Cursor. El harness del agente cambia, pero el archivo de workflow sigue siendo el mismo:

# same checkout, teammate on Cursor
swamp repo upgrade --tool cursor
swamp workflow run release-check

swamp workflow run no depende de qué agente lo haya invocado. La parte que corresponde al agente es escribir y editar definiciones, y esa parte sí cambia según el harness. OpenCode y Codex comparten .agents/skills/ y AGENTS.md, por lo que ambas herramientas leen las skills desde la misma ubicación.

De forma predeterminada, Swamp guarda los datos de ejecución, como los datos de modelos, las ejecuciones de workflows, las salidas y los registros de auditoría, en .swamp/. Los equipos que necesitan el mismo estado en varias máquinas pueden cambiar a otro backend de almacenamiento de datos, como una ruta de sistema de archivos compartida o S3. El checkout también viaja contigo: en una máquina remota configurada para programación agéntica, el mismo workflow se ejecuta siempre que esa shell tenga las credenciales que necesitan los modelos. Usa --repo-dir o SWAMP_REPO_DIR para indicar a Swamp un repositorio fuera del directorio actual.

Madurez y limitaciones de Swamp

Swamp es una herramienta en fase temprana. Se mantiene activamente en los repositorios de swamp-club y publica releases continuas identificadas por fecha. Cuenta con que habrá cambios.

• Contribuciones cerradas. Solo el personal de Elder Swamp Club escribe código para Swamp. Los pull requests procedentes de forks se cierran automáticamente, así que los bugs y las propuestas de funcionalidades se envían mediante swamp issue bug o swamp issue feature, y los mantenedores implementan las que aceptan.
• Telemetría. Swamp recopila telemetría de uso salvo que la desactives. Puedes desactivarla para un solo comando con --no-telemetry, para una shell con SWAMP_NO_TELEMETRY=1, para un repositorio con telemetryDisabled: true en .swamp.yaml, o para todas las ejecuciones en tu máquina con swamp config set telemetry.collection disabled, que escribe la configuración en ~/.config/swamp/telemetry.yaml.
• Alcance. Un script de una línea o un cron job no necesitan modelos, un DAG ni datos versionados. Swamp compensa cuando una tarea abarca varios sistemas, necesita un historial o la comparte un equipo.
• Las extensiones ejecutan código. Revisa las extensiones de terceros antes de confiar en ellas.
• Licencia. AGPL-3.0 con la Swamp Extension and Definition Exception.

Un ejecutor determinista repite un workflow defectuoso con la misma fidelidad que uno bueno. Las aserciones y la revisión humana siguen siendo necesarias.

Conclusión

Swamp conserva el procedimiento, no el razonamiento del agente. Las definiciones y los workflows guardados te ofrecen los mismos pasos y las mismas puertas de control en cada ejecución, mientras que el agente sigue siendo libre (y variable) cada vez que los escribe o modifica. Un buen siguiente paso es elegir un proceso que tu agente ya haga bien, como una verificación de release o una pasada de revisión, y pedirle que lo guarde como workflow de Swamp. Revisa el YAML, haz commit y ejecútalo desde un segundo harness para confirmar que también funciona allí.

Preguntas frecuentes

¿Cómo ejecuto un workflow de Swamp en el CI de GitHub Actions?

Usa swamp-club/setup-swamp, la GitHub Action oficial. Instala Swamp con el script de instalación oficial y también puede iniciar sesión en swamp.club si le pasas un input api-key. Establece repo-init en true para ejecutar swamp repo init después de la instalación. Un step posterior invoca swamp workflow run con el nombre del workflow. Si la ejecución falla, el comando devuelve un código distinto de cero y el job falla. La action se encuentra todavía en una release temprana v0.1.

¿Dónde deben almacenarse los secretos de un workflow de Swamp?

Guárdalos en un vault de Swamp y haz referencia a ellos por su nombre en las definiciones y los workflows. Swamp obtiene el valor real en el momento en que se ejecuta un step. Así se mantiene fuera de tus archivos YAML y de tus datos de .swamp, y no se conserva nada para la siguiente ejecución. El proveedor de cifrado local integrado no requiere configuración adicional. Otros proveedores de vault guardan los secretos en servicios externos como AWS Secrets Manager, Azure Key Vault o 1Password.

¿Un workflow de Swamp necesita un agente de IA para ejecutarse?

No. swamp workflow run es un comando de CLI corriente, así que un desarrollador, un job de CI o un script pueden ejecutar un workflow guardado sin ningún agente. Solo necesitas el agente para crear o editar modelos, definiciones y workflows. Para ejecuciones que nadie inicia manualmente, swamp serve puede ejecutar un workflow mediante un disparador cron. También puede ejecutarlo cuando llega un webhook firmado desde GitHub, Jira, Linear, Stripe, Slack o un endpoint genérico.

¿Se puede instalar Swamp en Windows?

Sí. Las releases de Swamp en la página de releases de GitHub de swamp-club/swamp incluyen un archivo swamp-windows-x86_64.zip que contiene swamp.exe, junto con los builds para macOS y Linux. El comando de una línea con curl canaliza el script de instalación hacia sh, por lo que no funciona en Windows. Los usuarios de Windows descargan el archivo de la release, extraen swamp.exe y lo colocan en un directorio incluido en su PATH.