Comment ça marche ? Workflow d'agents
Code de l'exemple : src/exemplia/workflow_agents/ sur GitHub
WORKFLOW DÉTERMINISTE (le code fixe les étapes, 3 appels LLM)
controler ──(expéditeur inconnu ou email suspect)──────────────┐
(code) ▼
classer ─► extraire ─► verifier ─► rediger ─► validation_humaine ─► envoyer
(LLM) (LLM) (code) (LLM) (pause) └► cloturer
AGENT ORCHESTRATEUR (le superviseur choisit, 5 appels LLM en moyenne)
controler ─► superviseur ⇄ agents ─► completer_brouillon ─► validation_humaine ─► …
(LLM) │
agent_commandes (LLM + outils de lecture)
agent_documentation (LLM + politiques)
agent_redaction (LLM, à partir des faits recueillis)
proposer_action (éligibilité vérifiée par le code)
signaler_escalade
La pause avant l'envoi
Les deux graphes s'arrêtent avant tout envoi (interrupt de LangGraph) : le conseiller relit,
corrige, approuve ou rejette, et décide d'exécuter ou non l'action. L'état du traitement en pause
est enregistré dans PostgreSQL, donc il survit à un redémarrage de l'application.
Les garde-fous restent dans le code, quelle que soit l'architecture : identification du client par l'adresse d'expédition, éligibilité revérifiée, nombre d'étapes borné, escalade automatique sur menace de recours ou remboursement supérieur à 300 euros.
À justesse égale sur les emails d'exemple, l'orchestrateur consomme deux fois et demie plus d'appels au modèle : la souplesse se paie.
Briques
| Brique | Rôle |
|---|---|
| LangGraph | Graphes d'état, pause interrupt, reprise après validation |
PostgresSaver |
Checkpointer persistant des traitements en pause |
Ollama, qwen3.5:9b |
Classification, extraction, rédaction, supervision |
| PostgreSQL | Commandes, éligibilité, journal d'audit |
| MLflow | Autolog LangChain : un span par nœud du graphe |
Workflow déterministe
| Nœud | Rôle |
|---|---|
controler |
Identifie le client par l'adresse d'expédition, détecte les formulations d'injection et les menaces de recours (code). Un email d'expéditeur inconnu ou suspect va directement au conseiller avec une réponse d'attente écrite par le code |
classer |
Catégorie et urgence (sortie structurée) |
extraire |
Référence de commande, type de demande, résumé, menace juridique |
verifier |
Faits vérifiés par le code : commande du client, éligibilité, règles d'escalade du guide interne (menace juridique, montant > 300 €) |
rediger |
Brouillon à partir des faits vérifiés et des politiques |
validation_humaine |
Pause : le conseiller corrige, approuve ou rejette, et choisit d'exécuter ou non l'action |
envoyer |
Exécute l'action si demandée (idempotente), journalise la réponse |
Agent orchestrateur
Le superviseur choisit les agents à consulter. Les garde-fous restent dans le code :
- nombre d'étapes borné (
max_etapes) ; - sous-agent commandes limité aux données du client identifié ;
- action retenue seulement si le code confirme son éligibilité, avec la même règle d'escalade au-delà de 300 € que le workflow ;
- l'agent de rédaction reçoit les réponses des autres agents et les motifs d'escalade : sans elles, il invente l'issue de la demande (« votre commande a bien été annulée ») ;
completer_brouillonfait rédiger un brouillon si le superviseur s'est arrêté sans le demander.
Composants de l'exemple
flowchart TD
classDef externe fill:#fed7aa,stroke:#ea580c,color:#7c2d12
classDef code fill:#ffffff,stroke:#6b7280,color:#1f2937
classDef gpu fill:#fecaca,stroke:#dc2626,color:#7f1d1d
classDef disque fill:#dcfce7,stroke:#16a34a,color:#14532d
Nav["navigateur<br/>page /workflow, HTMX"]
subgraph Py["Processus Python : uv run exemplia"]
Web["web.py<br/>POST /workflow/traiter<br/>POST /workflow/valider"]
Graphe["workflow.py ou orchestrateur.py<br/>graphe LangGraph<br/>nœuds de commun.py"]
Garde["garde/controles.py<br/>ControleInjection, règles"]
end
Docs[("data/entreprise/documents<br/>3 politiques")]
Ollama["Ollama (hôte)<br/>qwen3.5:9b"]
PG[("PostgreSQL entreprise<br/>clients, commandes,<br/>journal_actions")]
Ckpt[("PostgreSQL entreprise<br/>tables checkpoint*<br/>PostgresSaver")]
MLflow[("MLflow<br/>conteneur Docker<br/>traces")]
Nav -- "① HTTP POST<br/>email, architecture" --> Web
Web -- "② appel Python<br/>construire, stream" --> Graphe
Graphe -- "③ lecture<br/>des fichiers" --> Docs
Graphe -- "④ ⑦ SQL SELECT<br/>client, commande, éligibilité" --> PG
Graphe -- "⑤ appel Python<br/>objet et corps" --> Garde
Graphe -- "⑥ HTTP POST<br/>/v1/chat/completions" --> Ollama
Graphe -- "⑧ SQL<br/>état à chaque nœud,<br/>pause interrupt" --> Ckpt
Web -- "⑨ ⑭ HTTP<br/>traces du graphe" --> MLflow
Web -- "⑩ ⑮ fragment HTML<br/>étapes, brouillon, action" --> Nav
Nav -- "⑪ HTTP POST<br/>texte, approuver, executer_action" --> Web
Ckpt -- "⑫ SQL<br/>état en pause, reprise" --> Graphe
Graphe -- "⑬ SQL INSERT, UPDATE<br/>action, journal d'audit" --> PG
class Nav externe
class Web,Graphe,Garde code
class Ollama gpu
class Docs,PG,Ckpt,MLflow disque
uv run exemplia démarre l'application FastAPI ; le routeur de web.py sert la page /workflow.
Les deux graphes lisent les commandes dans PostgreSQL (IACU_DATABASE_URL), les politiques dans
data/entreprise/documents, et appellent le serveur de modèles par l'API compatible OpenAI
(IACU_LLM_BASE_URL, IACU_MODELE_CHAT, qwen3.5:9b par défaut). Le checkpointer est le
PostgresSaver de LangGraph, sur la même base, créé une fois par dep_checkpointer.
- ① Traitement demandé. HTMX envoie l'expéditeur, l'objet, le corps et l'architecture
(
workflowouorchestrateur) àPOST /workflow/traiter, qui crée l'identifiant du traitement,<architecture>-<uuid>, utilisé commethread_id. - ② Construction et exécution. Sous
mesurer, qui enveloppe le client LLM dans unClientJournal,construire_workflowouconstruire_orchestrateurcompile le graphe ;_executerle déroule avecgraph.streamdans un span MLflowworkflow.executer, tagué avec l'exemple et l'architecture. - ③ Politiques. À la construction,
politique-de-retour,conditions-generales-de-venteetguide-interne-service-clientsont lus et encadrés pardelimiter. - ④ Identification. Le nœud
controlercherche le client par l'adresse d'expédition (tableclients). - ⑤ Contrôle d'injection.
ControleInjection, instancié sans classifieur, applique les règles de la garde à l'objet et au corps ;motif_recoursrepère les menaces de recours. Un expéditeur inconnu ou un email suspect va directement àvalidation_humaineavec la réponse d'attente écrite par le code, sans appel au LLM. - ⑥ Appels au LLM. Le workflow fait trois appels :
classeretextraireen sortie structurée JSON Schema,redigeren texte libre. L'orchestrateur appelle le superviseur avec cinq outils (agents commandes, documentation, rédaction,proposer_action,signaler_escalade), dans la limite demax_etapes(6), et chaque agent consulté fait ses propres appels ; l'agent commandes a jusqu'à trois tours d'appels d'outils.completer_brouillonfait rédiger un brouillon si le superviseur n'en a pas demandé. - ⑦ Vérifications par le code.
verifier_commandelit la commande du client identifié, puis l'éligibilité à l'annulation ou au retour (service_client/outils.py), et ajoute un motif d'escalade au-delà de 300 €. Dans l'orchestrateur,proposer_actionet les outils de l'agent commandes passent par les mêmes fonctions. - ⑧ Pause. LangGraph écrit l'état dans les tables
checkpoint*après chaque nœud ;validation_humaineappelleinterruptavec le brouillon, les motifs d'escalade et l'action proposée, et le graphe s'arrête. - ⑨ Traces. L'autolog LangChain trace chaque nœud et l'autolog OpenAI chaque appel au modèle,
sous le span
workflow.executer, envoyés dans l'expérienceexemplia. - ⑩ Affichage. Le fragment
traitement.htmlmontre les étapes exécutées, l'état de chaque nœud, le brouillon, l'action proposée, les motifs d'escalade, le nombre d'appels et la durée. - ⑪ Validation. Le conseiller corrige le texte, approuve ou rejette, et choisit d'exécuter ou
non l'action ;
POST /workflow/validerreçoit ces champs et l'identifiant. - ⑫ Reprise.
web.pyreconstruit le graphe de l'architecture tirée de l'identifiant, vérifie qu'un traitement est en attente, puis reprend avecCommand(resume=decision)depuis l'état enregistré. - ⑬ Envoi. Si le brouillon est approuvé,
envoyerexécute l'action demandée (annulation :UPDATE commandes; retour : demande enregistrée), chacune protégée par une clé d'idempotence dansjournal_actions, puis journalise la réponse. Sinon,cloturermarque le traitement rejeté. - ⑭ ⑮ Traces et réponse de la reprise, comme en ⑨ et ⑩.
Ce que fait le GPU. Seul Ollama calcule sur le GPU (⑥) : des passes avant de qwen3.5:9b,
sans entraînement. Le contrôle d'injection, l'identification, l'éligibilité, les règles d'escalade
et l'exécution des actions sont du code Python et du SQL, sur le CPU.