Transformer les tâches ponctuelles d'un agent en workflows réutilisables

Pour rendre réutilisable une tâche en plusieurs étapes réalisée par un agent IA, enregistrez ses étapes sous forme de définitions de modèles typées et d’un fichier de workflow déclaratif dans votre dépôt. La session suivante exécutera ainsi le processus enregistré au lieu de le reconstruire à partir d’un prompt.

Cela vous est sans doute déjà arrivé : un agent effectue une vérification de release impeccable (tests, build, smoke test, le tout dans le bon ordre), puis la session se ferme et le processus disparaît avec elle. Le lendemain, vous le décrivez à nouveau et obtenez une version légèrement différente.

Cet article montre comment conserver ce processus avec Swamp. Il explique ce qui devient réutilisable et ce qui ne l’est pas, présente un petit workflow de vérification de release et montre comment ce même workflow s’exécute sous Claude Code, Cursor, OpenCode ou Codex.

Pourquoi une bonne exécution d’agent disparaît

Une session d’agent ne conserve son processus de travail que dans le contexte de la conversation ; le processus prend donc fin avec la session. Les commandes exécutées, l’ordre choisi et les vérifications ajoutées ne sont enregistrés nulle part où la session suivante pourrait les exécuter. Il ne vous reste qu’une transcription de chat et les fichiers qui ont été modifiés au passage.

La solution consiste à transformer le processus de l’agent en fichiers exécutables stockés dans le dépôt. Une fois les étapes versionnées dans le dépôt, vous n’avez plus à réexpliquer la tâche à chaque session, et l’agent consacre son temps aux modifications plutôt qu’à la reconstruction de la procédure.

Des workflows d’agents IA réutilisables avec Swamp : ce qui persiste et ce qui ne persiste pas

Swamp est un outil en ligne de commande qui stocke l’automatisation produite par un agent sous forme de modèles typés, de définitions YAML, de workflows, de données versionnées et de références à des vaults, dans un répertoire .swamp/ au sein d’un dépôt Git. Le README de Swamp énonce six concepts fondamentaux : les modèles, qui décrivent des systèmes externes sous forme de types ; les définitions, des fichiers YAML qui configurent une utilisation donnée d’un type de modèle ; les workflows ; les données ; les vaults ; et les tags.

Swamp rend le processus reproductible, pas le raisonnement. Une fois les étapes d’un agent enregistrées sous forme de définitions de modèles et d’un fichier de workflow, les exécutions ultérieures rejouent ces étapes enregistrées. En revanche, lorsque l’agent les crée ou les modifie, son résultat peut varier d’une session à l’autre.

Swamp et MCP remplissent des fonctions différentes. MCP connecte un agent à des outils, comme l’explique le guide du développeur sur l’écosystème MCP. Swamp stocke et exécute l’automatisation que l’agent construit avec ces outils, et vous pouvez utiliser les deux conjointement. Swamp s’exécute sur votre propre machine, et les identifiants qu’il utilise proviennent de l’environnement du shell qui le lance.

Configurer Swamp pour votre harness

Installez le binaire avec le script officiel, puis initialisez le dépôt pour votre harness. Le script d’installation officiel prend en charge macOS et Linux, et des binaires de release sont également publiés pour 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 lit les skills de Swamp dans .claude/skills/ et ses instructions dans CLAUDE.md. Cursor utilise .cursor/skills/ et .cursor/rules/swamp.mdc. OpenCode et Codex utilisent tous deux .agents/skills/ et AGENTS.md.

Swamp embarque les skills dans son binaire et les écrit sur disque lors de l’init : c’est ainsi que l’agent les trouve sans configuration supplémentaire. L’autocomplétion du shell est disponible via swamp completions <shell>.

Un workflow de vérification de release, de bout en bout

Un workflow Swamp est un fichier YAML qui organise des jobs sous forme de DAG, chaque étape appelant une méthode d’une définition de modèle. Comme l’explique How Swamp Works, chaque job attend les jobs dont il dépend, et les étapes d’un même job s’exécutent en parallèle, sauf si l’une dépend d’une autre.

En temps normal, vous demanderiez à l’agent de créer les définitions run-tests, build-artifact et smoke-test. Relisez tout de même le workflow obtenu, car c’est le fichier que vous validez. La structure ci-dessous suit la référence des workflows. Les placeholders <method> sont laissés volontairement : remplacez-les par les noms des méthodes réellement exposées par vos définitions.

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

Dans ce workflow de vérification de release, les tests et le build s’exécutent simultanément. condition.type: succeeded bloque le job de smoke test jusqu’à ce que les deux réussissent. Vérifiez le fichier avec swamp workflow validate release-check, puis exécutez-le :

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 attend la fin de l’exécution (succès, échec ou annulation) ou s’interrompt au niveau d’une étape de validation manual_approval. Une exécution réussie renvoie le code de sortie 0 et tout autre résultat un code non nul, ce qui permet à la CI de s’en servir comme condition de passage. L’option --tag remplace les tags à l’exécution. Chaque exécution enregistre ses sorties sous forme de données versionnées non modifiables a posteriori, que vous pouvez retrouver par tag : une session ultérieure peut ainsi consulter ce qui s’est passé au lieu de le reconstituer à partir de l’historique du chat. L’expression data query est tirée de l’exemple de How Swamp Works et doit être adaptée aux champs de votre modèle.

Un smoke test réussi prouve seulement que l’endpoint a répondu. Il ne prouve pas que la page s’est affichée correctement ni que les utilisateurs ont pu mener un parcours à son terme. C’est en rejouant des sessions sur le build de staging que ce type de régression front-end devient visible.

Utiliser le même workflow d’un harness à l’autre

Lorsqu’une équipe utilise un workflow Swamp avec plusieurs harnesses, ce qu’elle partage, ce sont les fichiers de modèles, de définitions et de workflows. Le répertoire de skills de chaque harness est ignoré par Git et généré par Swamp lui-même, et swamp repo upgrade --tool <name> permet à un développeur de changer de harness ou d’en utiliser plusieurs en parallèle. Le README précise que chaque outil dispose de son propre dossier de skills, tenu à l’écart de Git.

Supposons que le dépôt ait été initialisé pour Claude Code et qu’un collègue utilise Cursor. Le harness d’agent change, mais le fichier de workflow reste identique :

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

swamp workflow run ne dépend pas de l’agent qui l’a invoqué. Le rôle de l’agent consiste à écrire et modifier les définitions, et c’est cette partie qui varie selon le harness. OpenCode et Codex partagent .agents/skills/ et AGENTS.md : les deux outils lisent donc les skills au même emplacement.

Par défaut, Swamp conserve les données d’exécution, comme les données de modèles, les exécutions de workflows, les sorties et les journaux d’audit, dans .swamp/. Les équipes qui ont besoin du même état sur plusieurs machines peuvent basculer vers un autre backend de stockage, comme un chemin sur un système de fichiers partagé ou S3. Le checkout est également portable : sur une machine distante configurée pour le développement agentique, le même workflow s’exécute dès lors que le shell dispose des identifiants nécessaires aux modèles. Utilisez --repo-dir ou SWAMP_REPO_DIR pour pointer Swamp vers un dépôt situé hors du répertoire courant.

Maturité et limites de Swamp

Swamp est un outil encore jeune. Il est activement maintenu dans les dépôts swamp-club et publie des releases continues, identifiées par leur date. Attendez-vous à des évolutions.

• Contributions fermées. Seule l’équipe d’Elder Swamp Club écrit le code de Swamp. Les pull requests provenant de forks sont automatiquement fermées : les bugs et les idées de fonctionnalités se soumettent via swamp issue bug ou swamp issue feature, et les mainteneurs implémentent celles qu’ils retiennent.
• Télémétrie. Swamp collecte des données de télémétrie d’utilisation, sauf si vous la désactivez. Vous pouvez la désactiver pour une commande avec --no-telemetry, pour un shell avec SWAMP_NO_TELEMETRY=1, pour un dépôt avec telemetryDisabled: true dans .swamp.yaml, ou pour toutes les exécutions sur votre machine avec swamp config set telemetry.collection disabled, qui écrit ce paramètre dans ~/.config/swamp/telemetry.yaml.
• Périmètre. Un script d’une ligne ou une tâche cron n’a pas besoin de modèles, d’un DAG et de données versionnées. Swamp devient rentable lorsqu’une tâche couvre plusieurs systèmes, nécessite un historique ou est partagée au sein d’une équipe.
• Les extensions exécutent du code. Examinez les extensions tierces avant de leur accorder votre confiance.
• Licence. AGPL-3.0 avec la Swamp Extension and Definition Exception.

Un exécuteur déterministe reproduit un mauvais workflow aussi fidèlement qu’un bon. Les assertions et la relecture humaine restent indispensables.

Conclusion

Swamp conserve la procédure, pas la réflexion de l’agent. Les définitions et workflows enregistrés vous garantissent les mêmes étapes et les mêmes points de contrôle à chaque exécution, tandis que l’agent reste libre (et variable) chaque fois qu’il les écrit ou les modifie. Pour aller plus loin, choisissez un processus que votre agent maîtrise déjà bien, comme une vérification de release ou une passe de revue, et demandez-lui de l’enregistrer sous forme de workflow Swamp. Relisez le YAML, commitez-le, puis exécutez-le depuis un second harness pour vérifier qu’il y fonctionne également.

FAQ

Comment exécuter un workflow Swamp dans une CI GitHub Actions ?

Utilisez swamp-club/setup-swamp, la GitHub Action officielle. Elle installe Swamp avec le script d'installation officiel et peut également se connecter à swamp.club si vous lui fournissez un input api-key. Définissez repo-init à true pour exécuter swamp repo init après l'installation. Une étape ultérieure appelle swamp workflow run avec le nom du workflow. Si l'exécution échoue, la commande renvoie un code de sortie non nul et le job échoue. L'action n'en est encore qu'à une première release v0.1.

Où stocker les secrets d'un workflow Swamp ?

Placez-les dans un vault Swamp et référencez-les par leur nom dans les définitions et les workflows. Swamp récupère la valeur réelle au moment où une étape s'exécute. Elle reste ainsi absente de vos fichiers YAML et de vos données .swamp, et rien n'est conservé pour l'exécution suivante. Le fournisseur de chiffrement local intégré ne nécessite aucune configuration supplémentaire. D'autres fournisseurs de vaults conservent les secrets dans des services externes tels qu'AWS Secrets Manager, Azure Key Vault ou 1Password.

Un workflow Swamp nécessite-t-il un agent IA pour s'exécuter ?

Non. swamp workflow run est une commande CLI ordinaire : un développeur, un job de CI ou un script peut exécuter un workflow enregistré sans aucun agent. L'agent n'est nécessaire que pour créer ou modifier les modèles, les définitions et les workflows. Pour les exécutions que personne ne lance manuellement, swamp serve peut exécuter un workflow sur un déclencheur cron. Il peut aussi en lancer un à la réception d'un webhook signé provenant de GitHub, Jira, Linear, Stripe, Slack ou d'un endpoint générique.

Peut-on installer Swamp sous Windows ?

Oui. Les releases de Swamp sur la page des releases GitHub de swamp-club/swamp incluent une archive swamp-windows-x86_64.zip contenant swamp.exe, aux côtés des builds macOS et Linux. La commande curl en une ligne redirige le script d'installation vers sh, elle ne fonctionne donc pas sous Windows. Les utilisateurs Windows téléchargent l'archive de la release, extraient swamp.exe et le placent dans un répertoire présent dans leur PATH.