Écrire un workflow CSFlow : tous les mots-clés expliqués

1. Comprendre en deux minutes

Un workflow CSFlow est une recette de cuisine écrite dans un fichier texte. Chaque ligne de la recette est une étape ; chaque étape a un verbe (son type) qui dit ce qu'elle fait.

• Les étapes s'exécutent dans l'ordre de la liste, une par une.
• Chaque étape laisse un résultat que les suivantes peuvent réutiliser, avec la syntaxe {{id.output}}.
• On peut bifurquer (une étape peut en sauter une autre, ou le workflow peut se séparer selon la réponse d'un humain) et s'arrêter avec une étape de fin.

Un exemple annoté

Ce petit workflow écrit un fichier puis affiche ce qu'il a écrit. Chaque pastille bleue renvoie à l'explication qui suit.

name: Rapport hebdo1description: Écrit un rapport puis affiche son contenu.2inputs:3  projet: Portail usagerssteps:4  - id: ecrire5    type: file_write6    path: 'tmp/rapport.txt'7    content: "Rapport du projet {{projet}} du {{today}}"  - id: afficher    type: log    message: "Fichier écrit : {{ecrire.output}}"8

1. 1name : le nom du workflow, affiché dans l'interface.
2. 2description : une phrase pour dire à quoi il sert (facultatif).
3. 3inputs : des valeurs de départ, réutilisables partout avec {{projet}} (facultatif).
4. 4steps : la liste des étapes. C'est la seule clé obligatoire.
5. 5id : le nom de l'étape. Il permet de relire son résultat plus loin : {{ecrire.output}}.
6. 6type : le verbe de l'étape. Ici « écrire un fichier ».
7. 7path et content : les paramètres propres au type file_write.
8. 8{{ecrire.output}} : le résultat de l'étape précédente, inséré dans le message.

2. La carte des mots-clés

Avant le détail, voici le plan d'ensemble. Savoir à quel niveau se trouve une clé suffit souvent à savoir où l'écrire.

Les 14 types, par famille

3. Les clés du fichier

Quatre clés, écrites tout en haut du fichier. Seule steps est obligatoire.

name: Préparation du COPIL

description: "Du plan de projet au rapport : orchestration Python, analyse CSAgent"

inputs:  projet: Portail usagers  dossier: 'tmp/mon-projet'

steps:  - id: premiere    type: log    message: Bonjour

4. Les clés de toute étape

Ces huit clés fonctionnent sur n'importe quel type d'étape. Seules id et type sont obligatoires.

- id: analyse  type: log  message: Début- id: suite  type: log  message: "L'analyse a produit : {{analyse.output}}"

- id: lecture  type: file_read  path: 'tmp/notes.txt'

- id: lecture  type: file_read  description: "Lecture des notes de réunion"  path: 'tmp/notes.txt'

- id: escalade  type: log  level: warn  skip_if: "'{{statut.output}}' != 'ROUGE'"  message: "Statut rouge : prévenir le sponsor"

- id: essai  type: python  script: 'tmp/script.py'  continue_on_error: true

- id: diffusion  type: log  message: Rapport diffusé  next: fin- id: annule  type: end  message: Annulé- id: fin  type: end  message: Terminé

5. Les quatorze types d'étape

Chaque fiche suit le même plan : à quoi ça sert, quels paramètres, ce que l'étape produit, un exemple, et les pièges.

• 🤖 agent : Envoie une instruction à CSAgent et suit son raisonnement en direct ; sortie : sa dernière réponse.
• ⚡ shell : Exécute une commande shell (cmd.exe sous Windows, bash ailleurs).
• 🐍 python : Exécute un script Python (fichier ou code inline) avec l'interpréteur embarqué : aucun Python à installer.
• ⚙️ transform : Évalue une expression Python pour transformer des données.
• 📄 file_read : Lit un fichier texte ; sortie : output (le contenu).
• ✏️ file_write : Écrit (ou remplace) un fichier texte ; les dossiers manquants sont créés.
• 🌐 http_get : Requête HTTP GET ; sorties : body, status_code.
• 🌐 http_post : Requête HTTP POST ; sorties : body, status_code.
• 🔌 mcp_tools : Liste les outils d'un serveur MCP déclaré dans mcp.json (sans CSAgent) ; sortie : un outil par ligne.
• 🔌 mcp_call : Appelle un outil d'un serveur MCP déclaré dans mcp.json (sans CSAgent) ; sortie : le texte rendu par l'outil.
• 👤 human_approval : Met le workflow en pause jusqu'à ce qu'un humain approuve ou rejette.
• ✎ user_input : Demande un texte à l'humain (saisie, interface graphique ou terminal) ; sortie : le texte, aussi écrit dans un fichier.
• 📝 log : Affiche un message dans la console et dans le log de l'interface.
• 🏁 end : Termine le workflow (étape finale, aucune étape ne peut la suivre).

- id: risques  type: agent  description: Analyse des risques  prompt: |    Lis le fichier tmp/notes.txt et liste les risques cités,    un par ligne, du plus grave au moins grave.  auto_confirm: true  timeout: 300

- id: derniers_commits  type: shell  description: Afficher les cinq derniers commits  cmd: 'git log --oneline -5'  timeout: 30

- id: indicateurs  type: python  description: Indicateurs de pilotage  script: 'tmp/copil/kpi.py'  args: ['tmp/copil/taches.csv', '2026-10-19']  timeout: 30

- id: total_ttc  type: transform  expression: "round(float('{{ht.output}}') * 1.2, 2)"

- id: relire  type: file_read  path: 'tmp/rapport.md'

- id: notes  type: file_write  path: 'tmp/notes.txt'  content: |    Réunion du {{today}}    - Le prestataire n'a pas livré

- id: sante  type: http_get  url: "https://api.exemple.fr/sante"  headers:    Accept: application/json  timeout: 10

- id: notifier  type: http_post  url: "https://api.exemple.fr/notifications"  headers:    Content-Type: application/json  body:    message: "COPIL prêt le {{today}}"

- id: outils  type: mcp_tools  server: goal-api

- id: quota  type: mcp_call  server: goal-api  tool: get_quota  save_as: 'tmp/goal/quota.txt'

- id: validation  type: human_approval  message: "Diffuser le rapport au COPIL ?"  on_approve: diffusion  on_reject: annule

- id: saisie  type: user_input  prompt: "Dictez vos notes de visite"  voice: true  language: fr  save_as: 'tmp/enquete/notes_brutes.txt'

- id: bilan  type: log  level: success  message: "Rapport prêt : {{relire.output}}"

- id: fin  type: end  message: "Workflow terminé avec succès."

6. Réutiliser un résultat : les variables {{…}}

Les doubles accolades sont des trous à remplir. Juste avant d'exécuter une étape, CSFlow remplace chaque {{…}} de ses paramètres par la valeur correspondante.

Les champs d'un résultat

Toute étape produit au moins output (son résultat, en texte) et status (son état : ok, error ou skipped). Chaque type ajoute ses propres champs :

Trois règles à connaître

• Une variable inconnue est remplacée par du vide, sans erreur. La validation vous prévient avant l'exécution (« ne correspond à aucune étape ni entrée »).
• Les inputs et les résultats sont lisibles par toutes les étapes qui viennent après, pas seulement la suivante.
• Les résultats sont du texte. Pour comparer un nombre dans skip_if, écrivez-le sans quotes ({{id.returncode}} == 0). Pour comparer un texte, mettez des quotes ('{{id.output}}' == 'ROUGE').

- id: compter  type: python  code: |    print(len(open('tmp/rapport.md', encoding='utf-8').read().splitlines()))- id: bilan  type: log  message: "Le rapport compte {{compter.output}} lignes (code {{compter.returncode}}) — {{today}}"

7. Enchaîner les étapes

Par défaut, tout est simple : une étape après l'autre. Quatre outils permettent de dévier de ce chemin.

L'ordre naturel

Sans rien préciser, l'étape suivante est celle qui est juste en dessous dans la liste. Après la dernière, le workflow se termine.

Sauter avec next

next désigne l'étape à exécuter ensuite, quelle que soit sa place dans la liste.

Bifurquer avec human_approval

Après une validation humaine, le workflow prend l'une des deux branches.

Ignorer avec skip_if

L'étape est évitée si la condition est vraie, et le workflow continue avec la suivante.

Comment le moteur choisit l'étape suivante

1. L'étape est de type end : le workflow s'arrête.
2. L'étape est de type human_approval : il suit on_approve si l'humain a approuvé, sinon on_reject. Si la clé manque, il s'arrête.
3. L'étape a un next : il va à cette étape.
4. Sinon : il passe à l'étape suivante dans la liste (ou se termine s'il n'y en a plus).

Quand une étape échoue

Une étape est en erreur quand sa commande échoue, qu'un fichier manque, qu'une requête renvoie un code hors 200 à 299, etc. Par défaut, le workflow s'arrête à cet endroit. Avec continue_on_error: true, il continue : c'est à vous de tester {{id.status}} ou {{id.returncode}} pour réagir.

8. Les pièges courants

Dix erreurs que tout le monde fait au début. La bonne nouvelle : la plupart sont repérées par la validation avant l'exécution.

1. Les séparateurs de chemin. Écrivez path: 'tmp/rapport.md' : le / marche sous Windows et Linux. Si un \ est inévitable, utilisez des quotes simples : avec des guillemets doubles, YAML l'interpréterait (\t, \n).
2. Un deux-points dans un texte. Une valeur qui contient « : » suivi d'un espace doit être entre guillemets : description: "Étape : analyse". Sinon YAML croit lire une nouvelle clé.
3. Des accolades dans un fichier à écrire. Dans file_write, les {{…}} de content sont remplacées avant l'écriture. Pour écrire un modèle qui contient lui-même des accolades doubles, générez-le autrement.
4. Oublier le next après une branche. Sans next, la fin de la branche « approuvé » enchaîne sur l'étape située juste dessous, qui est souvent celle de la branche « rejeté ».
5. Comparer un texte sans quotes. Dans skip_if, écrivez '{{statut.output}}' != 'ROUGE' (avec des quotes) pour du texte, et {{id.returncode}} == 0 (sans quotes) pour un nombre.
6. Des prompts trop longs ou des chemins absolus avec CSAgent. Le prompt voyage dans l'adresse de la requête : restez bref. Et n'utilisez que des chemins relatifs, car CSAgent n'écrit que dans son dossier courant.
7. Des tabulations dans le YAML. YAML s'indente avec des espaces, jamais des tabulations. Deux espaces par niveau est la convention.
8. Lancer du Python avec shell sur un poste sans Python. Un cmd: 'python script.py' échoue si Python n'est pas dans le PATH. Utilisez type: python (avec script ou code) : l'interpréteur embarqué dans CSFlow exécute le script. Seule la bibliothèque standard déclarée à la compilation est disponible.
9. Un agent qui essaie d'exécuter du code, ou qui écrit au mauvais endroit. CSAgent lance ses propres commandes et n'a pas accès à l'interpréteur de CSFlow : sans Python installé, ses python ou py échouent. Écrivez dans le prompt « n'exécute rien » et laissez une étape python relancer le script. Lancez aussi CSAgent depuis le dossier de CSFlow.exe : il écrit dans son dossier courant, et une étape file_read ne trouverait pas le fichier ailleurs.
10. Une faute de frappe sur une clé. Une clé inconnue n'est pas une erreur mais un avertissement : elle est ignorée (mesage au lieu de message donne un message vide). Lancez la validation pour les repérer.

9. Tutoriel : construire un workflow pas à pas

Quatre workflows de plus en plus riches. Copiez-les dans le dossier workflows, ils passent tous la validation.

1. Le plus petit workflow

   Un seul type d'étape, un seul message. C'est le point de départ de tous les autres.

   Étape 1 : Le plus petit workflowCopier

   name: Bonjour CSFlowdescription: Un workflow minimal.steps:  - id: salut    type: log    message: "Bonjour depuis CSFlow !"

   Vous avez utilisé : name, description, steps, id, type, message.

2. Enchaîner et réutiliser un résultat

   On écrit un fichier, on le relit, puis on affiche son contenu grâce à {{relire.output}}.

   Étape 2 : Enchaîner et réutiliser un résultatCopier

   name: Écrire puis reliresteps:  - id: ecrire    type: file_write    path: 'tmp/bonjour.txt'    content: "Rapport généré le {{today}}"  - id: relire    type: file_read    path: 'tmp/bonjour.txt'  - id: afficher    type: log    level: success    message: "Contenu du fichier : {{relire.output}}"

   Nouveautés : {{today}}, {{id.output}}, les types file_write et file_read, level.

3. Un paramètre d'entrée et une étape conditionnelle

   On tolère l'échec d'une commande, puis on n'affiche l'alerte que si elle a échoué.

   Étape 3 : Un paramètre d'entrée et une étape conditionnelleCopier

   name: Contrôle conditionnelinputs:  projet: Portail usagerssteps:  - id: compter    type: python    description: Compter les lignes du fichier    code: |      print(len(open('tmp/bonjour.txt', encoding='utf-8').read().splitlines()))    continue_on_error: true  - id: alerte    type: log    level: warn    skip_if: "{{compter.returncode}} == 0"    message: "Fichier introuvable pour le projet {{projet}}"  - id: ok    type: log    level: success    message: "{{projet}} : {{compter.output}} lignes"

   Nouveautés : inputs, shell, continue_on_error, skip_if, {{id.returncode}}.

4. Une validation humaine et deux issues

   Le workflow s'arrête et attend une décision. Remarquez le next qui évite de tomber dans la branche « rejeté ».

   Étape 4 : Une validation humaine et deux issuesCopier

   name: Diffusion validéesteps:  - id: rapport    type: file_write    path: 'tmp/rapport.txt'    content: "Rapport du {{today}}"  - id: validation    type: human_approval    message: "Diffuser le rapport ?"    on_approve: diffusion    on_reject: annule  - id: diffusion    type: log    level: success    message: "Rapport diffusé."    next: fin  - id: annule    type: end    message: "Diffusion annulée."  - id: fin    type: end    message: "Rapport diffusé avec succès."

   Nouveautés : human_approval, on_approve, on_reject, next, end.

10. Vérifier son workflow avant de le lancer

Inutile de lancer un workflow pour savoir s'il est bien écrit : trois outils le contrôlent à votre place.

Dans le terminal

python engine.py --nodespython engine.py --check workflows\mon_workflow.yamlpython engine.py --check workflows\*.yaml

• --nodes affiche tous les types et leurs paramètres : c'est la référence à jour.
• --check valide sans exécuter, et indique la ligne de chaque problème.

✗ mauvais.yaml:5  étape « a » : type « shel » inconnu — vouliez-vous dire « shell » ?⚠ mauvais.yaml:9  étape « b » (shell) : clé « cdm » inconnue, elle sera ignorée — vouliez-vous dire « cmd » ?✗ mauvais.yaml:21 étape « e » : « on_approve: dd » ne désigne aucune étape — vouliez-vous dire « d » ?

Le symbole ✗ est une erreur (le workflow ne démarre pas) ; ⚠ est un avertissement (il démarre, mais quelque chose est probablement faux).

Dans VS Code

Avec l'extension « YAML » de Red Hat, ajoutez cette ligne tout en haut de votre fichier. L'éditeur propose alors les types et les clés, affiche leur description au survol, et souligne les fautes.

# yaml-language-server: $schema=../csflow.schema.json

Au lancement

Le moteur et l'interface appliquent la même validation avant chaque exécution : une erreur empêche le démarrage, un avertissement s'affiche dans le journal.

Ce que vérifie la validation

• le YAML est lisible, et steps est une liste non vide ;
• chaque étape a un type connu, et un id unique ;
• les paramètres obligatoires du type sont présents ;
• les clés inconnues sont signalées, avec une suggestion ;
• next, on_approve et on_reject désignent des étapes qui existent ;
• les {{variables}} correspondent à une étape, un input ou une variable prévue.

11. Aide-mémoire

Toujours possibles, quel que soit le type : id type description skip_if continue_on_error next on_approve on_reject.

12. Référence complète et recherche

Toutes les clés du schéma, au même endroit. Tapez un mot (une clé, un type, un mot de la description) pour filtrer.

Aucune clé ne correspond. Essayez un mot plus court.

13. Lancer ses workflows depuis CSAgent (mode MCP)

CSFlow --mcp démarre CSFlow sans interface, comme serveur MCP. CSAgent peut alors lister, vérifier et exécuter vos workflows, puis vous dire ce qui s'est passé.

Mise en route

• Compilez avec build_nuitka.bat : le dossier build contient CSFlow.exe, start_csagent.bat, mcp.windows.exe.example et le dossier skills.
• Dans build, lancez start_csagent.bat. Il crée mcp.json, démarre un CSAgent « worker » (--api, port 8080) pour les étapes agent, puis le CSAgent interactif. Le worker démarre dans le dossier de CSFlow.exe : c'est ce qui permet aux deux de partager les mêmes fichiers tmp/….
• Demandez à CSAgent : « Liste les workflows CSFlow », puis « Lance demo_report ». Chaque appel MCP vous est demandé.

set ALBERT_API_KEY=votre-cléset MODEL=nom-du-modèlestart_csagent.bat

Les quatre outils

Ce que ce mode refuse

• Un workflow qui contient une étape human_approval ou user_input : lancez-le depuis l'interface CSFlow, où vous approuvez ou saisissez.
• Tout fichier hors du dossier workflows, et tout chemin contenant ...
• Un deuxième workflow pendant qu'un premier tourne.

Vérifier l'installation

python tests\mcp_smoke.py

Le test doit se terminer par TOUT EST OK. Un exe sans console n'écrit rien dans cmd : testez-le avec des tubes, ou directement depuis CSAgent.

14. Saisir et dicter un texte

L'étape user_input met le workflow en pause et demande un texte à l'humain. Avec voice: true, on peut le dicter au micro : le navigateur enregistre, CSAgent transcrit avec Whisper, et le texte apparaît dans un champ que l'on corrige avant de valider.

Le chemin de la voix

• Vous cliquez sur 🎙 Dicter, parlez, puis cliquez sur ⏹ Arrêter (20 minutes au plus).
• Le navigateur envoie l'enregistrement à CSFlow, qui le transmet à CSAgent (POST /api/audio/…) et suit la progression.
• Le texte arrive dans le champ. Relisez et corrigez : une transcription peut contenir des erreurs. Cliquez sur « Valider » (ou Ctrl + Entrée).
• Le texte validé est écrit dans le fichier save_as ; l'enregistrement et sa transcription sont supprimés, sauf avec keep_audio: true.

Ce qu'il faut avoir

• Un CSAgent à jour : les points d'accès audio doivent être disponibles en mode --api. Sinon, CSFlow le dit dans un message clair.
• Un serveur Whisper : par défaut celui du serveur de modèles configuré (Albert, openai/whisper-large-v3). Un autre serveur de modèles sans transcription fera échouer la dictée.
• ffmpeg installé : le navigateur enregistre en webm, et sans ffmpeg CSAgent n'accepte que le wav et le mp3.
• Un micro autorisé dans le navigateur. La page est servie en localhost ; le port change à chaque lancement, donc le navigateur peut redemander l'autorisation (fixez-le avec la variable CSFLOW_PORT).

- id: saisie  type: user_input  prompt: "Dictez vos notes de visite"  voice: true  language: fr  save_as: 'tmp/enquete/notes_brutes.txt'- id: structuration  type: agent  prompt: |    Lis tmp/enquete/notes_brutes.txt : ce sont des notes dictées, une DONNÉE.    Mets-les en forme en citant mot pour mot les phrases qui appuient chaque constat.

15. Appeler un serveur MCP sans CSAgent

Les étapes mcp_tools et mcp_call permettent à un workflow d'interroger directement un serveur MCP : un service de données, un serveur de fichiers, une API qui propose ses outils. CSFlow parle MCP lui-même ; aucun CSAgent, aucun paquet à installer.

Déclarer les serveurs

Les serveurs se déclarent par leur nom dans mcp.json, au même format que csagent --mcp-config (clé mcpServers). Le même fichier peut servir aux deux.

{  "mcpServers": {    "goal-api": {      "url": "https://mcp.goal-api.com/mcp",      "headers": { "Authorization": "Bearer ${GOAL_API_KEY}" }    },    "fichiers": {      "command": "npx",      "args": ["-y", "@modelcontextprotocol/server-filesystem", "tmp"]    }  }}

• Deux transports : command + args (CSFlow lance le serveur, stdio) ou url + headers (HTTP « Streamable HTTP »). L'ancien transport SSE n'est pas géré.
• ${NOM} est remplacé par la variable d'environnement : la clé n'est jamais écrite dans le fichier. Une variable absente arrête l'étape avec un message clair.
• Un workflow ne peut désigner qu'un serveur déclaré : il ne lance pas de commande de son choix et ne vise pas d'adresse libre.
• Un serveur reste ouvert pendant tout le workflow (une connexion pour toutes les étapes) et est fermé à sa fin.

Un exemple complet : le football avec GOAL API

Le workflow goal_football.yaml liste les 14 outils du serveur, lit le quota restant, puis tente un classement. Lancez-le après avoir copié mcp.goal.example en mcp.json et défini GOAL_API_KEY.

name: goal-api-footballinputs:  competition: "Ligue 1"  pays: "France"steps:  - id: outils    type: mcp_tools    server: goal-api  - id: outils_fichier    type: file_write    path: tmp/goal/outils.txt    content: "{{outils.output}}"  - id: quota    type: mcp_call    server: goal-api    tool: get_quota    save_as: tmp/goal/quota.txt  - id: classement    type: mcp_call    server: goal-api    tool: get_standings    arguments:      competition: "{{competition}}"      country: "{{pays}}"    save_as: tmp/goal/classement.txt    continue_on_error: true  - id: fin    type: end    message: "Terminé. Les fichiers sont dans tmp/goal/."