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.

Accès à l'éditeur collaboratif

Ouvrez le flow depuis le workspace auquel vous avez accès. Une session collaborative est liée à ce workspace et à ce flow, même si un autre utilisateur a déjà ouvert le document. Connaître ou modifier l'identifiant d'un autre flow ne donne aucun droit d'accès.

Si la connexion est refusée, vérifiez le workspace sélectionné, puis rouvrez le flow pour obtenir une nouvelle session. Reconnectez-vous si nécessaire. Si le refus persiste, contactez l'administrateur du workspace; ne désactivez pas l'authentification pour le contourner.

Les identifiants de nodes, de parents ou d'edges appartenant à un autre flow sont refusés lors de la persistance. Une écriture refusée n'enregistre pas une partie du graphe: ne considérez pas des modifications encore visibles dans l'éditeur comme enregistrées tant que la synchronisation n'a pas réussi. Les identifiants de workspace contenus dans le document ne remplacent jamais les droits de votre session.

Cette protection ne constitue pas une garantie de révocation immédiate d'une connexion déjà établie lorsque son jeton expire ou que ses droits changent. Les mises à jour de persistance revérifient le propriétaire du flow; la révocation des connexions actives reste une limite distincte.

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]

Contrôler ce que l'AI Agent publie

Le node AI Agent effectue toujours l'exécution configurée (appel LLM, appels d'outils, ou boucle ReAct) - cela ne change jamais. Ce qui change, c'est si sa réponse est publiée auprès de l'utilisateur final, contrôlé par l'option Envoyer la réponse au canal (sendToChannel, activée par défaut).

Modèle A - Réponse directe de l'AI Agent (par défaut) : laissez Envoyer la réponse au canal activée. La réponse de l'AI Agent est publiée directement dans la conversation.

AI Agent (Envoyer la réponse au canal : activé)
  -> la réponse est publiée

Modèle B - AI Agent comme étape de génération interne : désactivez Envoyer la réponse au canal et ajoutez un node Direct Message après. L'AI Agent s'exécute toujours et sa sortie reste disponible pour les nodes en aval (par ex. via {{ agent_1.output }}), mais seul l'envoi du node Direct Message publie quelque chose à l'utilisateur - utile lorsqu'un node ultérieur doit reformater, combiner, ou finaliser la réponse avant qu'elle n'atteigne la conversation.

AI Agent (Envoyer la réponse au canal : désactivé)
  -> sortie disponible uniquement pour les nodes en aval
     |
     v
Direct Message
  -> publie la réponse finale

Utiliser les variables efficacement

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

Pour une valeur propre à l'installation, un node API peut référencer {{$env.NAME}}, par exemple ORDERS_URL ou ORDERS_TOKEN. Dans System > Promote, consultez les exigences de paramètres et préparez les valeurs dans le workspace cible. Les valeurs sont en écriture seule: la console affiche leur état et, pour une URL configurée, uniquement son origine normalisée; elle ne renvoie jamais la valeur.

Les références de paramètres sont limitées aux champs autorisés des requêtes API, pas aux prompts, au code ou aux messages. Une variable ordinaire dont le texte contient {{$env.NAME}} n'est pas réinterprétée comme une référence. Le caractère $ est réservé dans les noms de variables. Un paramètre référencé mais absent empêche l'appel externe, même si sa définition est optionnelle; aucune valeur source, valeur par défaut ou substitution en texte brut n'est inventée.

Utilisez le workflow source de System pour inspecter et convertir explicitement un identifiant source connu en indiquant le chemin du champ et la révision courante de la configuration. Les valeurs ambiguës et les révisions périmées sont refusées; une valeur configurée entre-temps n'est pas écrasée. La conversion ne réaffiche pas le littéral. Ne publiez pas une ancienne version de l'éditeur qui le rétablit; examinez séparément les prompts et textes libres, car cette analyse ne prouve pas l'absence de secrets.

Si une opération externe déjà dispatchée a un résultat inconnu, vérifiez son état courant et suivez l'action de reprise documentée avant toute nouvelle tentative. Ne déduisez pas la réussite d'une demande acceptée et ne soumettez pas une nouvelle demande pour contourner un résultat ambigu.

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.

Date du jour : {{ now | date:'YYYY-MM-DD' }} insère la date (UTC) au moment où l'étape s'exécute. Le format accepte YYYY, YY, MM, DD, HH, mm et ss, par exemple {{ now | date:'DD/MM/YYYY HH:mm' }}. Sans format, {{ now | date }} donne YYYY-MM-DD. Pour changer le format d'une balise insérée, double-cliquez dessus (ou sélectionnez-la et appuyez sur Entrée), puis choisissez un préréglage ou saisissez le vôtre. Le même geste permet de modifier à la main le contenu de n'importe quelle balise de variable.

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.

Limites de la comparaison portable

La fondation de comparaison System v1 conserve les différences entre champ absent, null, entier et nombre décimal, les alias, les espaces et les fins de ligne. Elle traduit uniquement les références déclarées avec une correspondance portable explicite; les identifiants locaux ne sont pas utilisés comme identités portables. Seuls les champs déclarés sans effet portable sont exclus.

Une référence non résolue ne peut pas produire de hash de comparaison. Les champs inconnus, les types non pris en charge et les identifiants d'authentification littéraux connus sont refusés; un export partiel silencieux n'est pas une solution. Les prompts, le code et les autres textes libres restent du contenu à vérifier: cette comparaison ne prouve pas l'absence de secrets.

System fournit le workflow de release et de promotion en création seule décrit ci-dessous. La comparaison portable ne crée ni correspondance ni configuration cible et ne met pas à jour les flows existants. Une comparaison réussie n'est pas une analyse de secrets; examinez séparément les prompts et textes libres.

Promouvoir un flow avec System

System est accessible à /system dans la console d'administration. Utilisez-le avec les droits d'administration du workspace actif. Le workflow L1A approuvé reste en place et en création seule : le précontrôle ne doit trouver dans la cible aucun flow, canal, modèle PPTX, intention ou compétence existant à promouvoir. Les réglages et paramètres existants sont préservés; la promotion ne fusionne ni ne met à jour le contenu existant.

1. Précontrôler la source. Dans Releases, choisissez le workspace source et lancez le précontrôle du contenu pris en charge. Résolvez les blocages et examinez les avertissements. Acquitter un avertissement sur du texte libre ne prouve pas que les prompts ou les autres textes sont sans secret. Ne convertissez un identifiant littéral connu qu'après avoir inspecté le chemin du champ et la révision courante de la configuration; la conversion est explicite et ne réaffiche pas le littéral.
2. Publier et télécharger. Demandez la publication et attendez que la release soit PUBLISHED; ACCEPTED signifie uniquement que la demande a été enregistrée. Téléchargez l'archive publiée avec le téléchargement natif du navigateur et protégez-la.
3. Valider et analyser la cible. Dans Promote, choisissez le workspace cible actif, téléversez l'archive et attendez l'état VALIDATED. Lancez l'analyse en lecture seule, puis examinez les conflits, les créations prévues, les avertissements et les exigences de paramètres de la cible avant de planifier.
4. Confirmer et appliquer. Créez un plan à partir de l'analyse courante, inspectez ses impacts exacts et confirmez cette révision. L'apply est en création seule; il ne fusionne ni ne met à jour les objets existants. ACCEPTED ne signifie pas que l'opération a réussi. Attendez son état terminal et consultez le rapport dans Reports. En cas de conflit, de plan périmé ou de résultat inconnu, arrêtez-vous; ne relancez pas à l'aveugle.
5. Terminer la configuration cible. Préparez les valeurs requises dans le workspace cible avec les contrôles en écriture seule; l'apply ne renvoie ni ne remplace une valeur déjà configurée. Émettez l'identifiant d'un canal une seule fois et activez-le séparément; protégez son affichage unique. Les nœuds prédictifs exigent un premier entraînement explicite après l'apply. Pour un résultat d'entraînement ambigu, suivez l'action de vérification manuelle et ne redispatchez pas.
6. Interpréter l'état avec prudence. SUPPORTED_CONTENT_READY couvre le contenu pris en charge dont les paramètres et identifiants sont prêts et dont les entraînements prédictifs sont confirmés. Ce n'est pas une déclaration de préparation complète du produit ou de la production. Le workflow UI ne vérifie ni le stockage de production, ni le déploiement, ni la livraison des alertes. Pour la télémétrie locale uniquement, consultez le README observabilité.

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.