Guide de conception de flows

Un flow est une séquence de traitements visuels qui transforme une entrée (message, document, événement) en un résultat (réponse, action, notification). Ce guide couvre les patterns de conception éprouvés, de la structure la plus simple aux architectures complexes.

Principes fondamentaux

Un flow = un objectif

Chaque flow doit répondre à un seul objectif clairement identifiable. Si vous ne pouvez pas résumer le flow en une phrase, il fait probablement trop de choses.

Exemples de bons objectifs :

• "Répondre aux questions de support niveau 1"
• "Extraire les montants et dates des factures PDF"
• "Qualifier un prospect et créer une opportunité CRM"

Signaux d'alarme :

• Un flow avec plus de 15-20 nodes → envisager de le découper.
• Un flow qui fait "support ET qualification ET extraction" → trois flows séparés.

Lire le flow comme une histoire

Un flow bien conçu se lit de gauche à droite comme un récit : "L'utilisateur envoie un message → l'agent analyse → si c'est une question technique, on répond directement → sinon, on escalade."

Si un collègue ne comprend pas le flow en 30 secondes en le regardant, il faut le simplifier.

Patterns de conception

Pattern 1 : Linéaire

Le plus simple. Une séquence d'étapes sans branchement.

Trigger → Traitement → Réponse

Quand l'utiliser : Cas simples où le traitement est toujours le même.

Exemples concrets :

• Avec IA : Un assistant de traduction (Trigger → Agent → Réponse).
• Sans IA : Une passerelle de données (Trigger → Code → HTTP Request).

Pattern 2 : Branchement conditionnel

Le flow se divise selon un critère.

Trigger → Condition
  → branche A → traitement A
  → branche B → traitement B

Quand l'utiliser : Quand le traitement dépend du contenu ou du contexte (type de requête, catégorie, seuil).

Exemples concrets :

• Sans IA : Routage de tickets par catégorie — la Condition branche selon un mot-clé ou une métadonnée.
• Avec IA : Classification sémantique — un Agent classifie la demande, puis la Condition route vers le bon service.

Bonnes pratiques :

• Toujours prévoir une branche "sinon" (else/fallback).
• Limiter à 3-4 branches maximum. Au-delà, utiliser un Agent pour router plutôt qu'un arbre de conditions.

Pattern 3 : Avec validation humaine (HITL)

Un humain intervient pour valider, corriger ou compléter à un moment critique du flow.

Trigger → Agent → Human Input → Agent (suite) → Réponse

Quand l'utiliser : Quand les conséquences d'une erreur sont importantes (réponses juridiques, engagements financiers, communications officielles).

Exemple concret : Un agent rédige une réponse à une réclamation client. Un superviseur la valide avant l'envoi.

Bonnes pratiques :

• Placer le HITL au point de décision critique, pas partout.
• Fournir au validateur tout le contexte nécessaire (question initiale + réponse proposée).
• Prévoir un timeout : que se passe-t-il si personne ne valide ?

Pattern 4 : Boucle itérative

Le flow traite une liste d'éléments un par un.

Trigger → Loop (sur liste)
  → Agent (traitement d'un élément)
  → Set Variable (accumuler les résultats)
→ Fin de boucle → Réponse agrégée

Quand l'utiliser : Traitement par lot (batch) — analyser N documents, classifier N tickets, enrichir N fiches.

Exemple concret : Analyser une liste de 20 CV et extraire les compétences clés de chacun.

Bonnes pratiques :

• Attention au coût en tokens : chaque itération = un appel LLM.
• Tester d'abord sur 2-3 éléments, pas sur 200.
• Prévoir le cas de la liste vide.

Pattern 5 : Enrichissement en cascade

Plusieurs traitements séquentiels enrichissent progressivement le contexte.

Trigger → Parse Document → Agent (extraction) → Agent (analyse) 
  → HTTP Request (envoi) → Réponse

Quand l'utiliser : Quand le résultat final nécessite plusieurs étapes de traitement (extraction → transformation → action).

Exemple concret : Un document est parsé, les informations clés sont extraites, puis analysées pour détecter des anomalies, puis envoyées à un système aval.

Bonnes pratiques :

• Chaque étape doit enrichir le contexte, pas le réécrire.
• Utiliser Set Variable pour structurer les données entre les étapes.
• Nommer clairement les variables à chaque étape.

Bonnes pratiques de conception

Nommer les nodes

Chaque node doit avoir un nom explicite dans le canvas. Ne laissez pas les noms par défaut ("Agent 1", "Condition 2").

Documenter avec des annotations

Utilisez les annotations du canvas pour :

• Expliquer le contexte métier d'une section du flow.
• Indiquer les contraintes ou hypothèses ("suppose que l'utilisateur est authentifié").
• Marquer les points à revoir ("TODO : ajouter l'escalade ici").

Gérer les erreurs

Chaque node qui peut échouer (HTTP Request, Agent, Code) doit avoir un chemin d'erreur.

Questions à se poser :

• Que se passe-t-il si l'API externe ne répond pas ?
• Que se passe-t-il si le LLM renvoie une réponse inattendue ?
• Que se passe-t-il si le document est vide ou corrompu ?

Strategies :

• Condition après le node — Vérifier que la réponse est valide avant de continuer.
• Message d'erreur clair — L'utilisateur final doit savoir ce qui s'est passé ("Désolé, je n'ai pas pu accéder au système. Pouvez-vous réessayer ?").
• Fallback humain — En dernier recours, basculer vers un opérateur.

Structurer les prompts

Le prompt du node Agent est l'élément le plus important du flow. Traitez-le comme du code : structuré, versionné, testé.

Structure recommandée d'un prompt :

Rôle : Tu es un assistant [domaine] de [entreprise].

Contexte : [Ce que l'utilisateur essaie de faire]

Instructions :
1. [Première instruction]
2. [Deuxième instruction]
3. [Troisième instruction]

Contraintes :
- [Ce que tu ne dois PAS faire]
- [Limites de ton périmètre]
- [Format de réponse attendu]

Exemples :
Utilisateur : [exemple de question]
Assistant : [exemple de réponse attendue]

Utiliser les variables efficacement

Les expressions {{ variable }} permettent de passer des données entre nodes.

Conventions de nommage :

• {{ trigger.message }} — Le message initial de l'utilisateur.
• {{ agent_1.output }} — La sortie du premier agent.
• {{ http_request.response.body }} — Le corps de la réponse HTTP.

Piège courant : Référencer une variable qui n'existe pas encore (un node en amont n'a pas encore été exécuté). Vérifiez toujours l'ordre d'exécution.

Anti-patterns à éviter

Checklist avant mise en production

• Le flow a un nom et une description clairs.
• Chaque node est nommé de manière explicite.
• Les prompts sont structurés (rôle, contexte, instructions, contraintes).
• Les chemins d'erreur sont gérés (API down, réponse inattendue, document vide).
• Le flow a été testé avec des données réalistes (pas uniquement le cas nominal).
• Les variables sont correctement référencées (pas de référence circulaire).
• La complexité est raisonnable (< 15-20 nodes ; au-delà, justifier).
• Les annotations expliquent le contexte métier pour un nouveau venu.