Applied AI — Niveau Avancé

Session 4 : Architecture multi-agents

Programme : Applied AI — Formation professionnelle en intelligence artificielle Instructeur : Yann Isola Niveau : Avancé — Architectes solutions préparant la certification Claude Certified Architect Durée recommandée : 3 h 30 (2 h de cours magistral + 1 h 30 d’exercices pratiques) Prérequis : Sessions 1 à 3 du niveau avancé (orchestration, outils/function calling, gestion de contexte)

Objectifs pédagogiques

À l’issue de cette session, les participants seront capables de :

Choisir et justifier une stratégie de décomposition de tâches (verticale, horizontale, récursive) selon la complexité, le budget de tokens et le bénéfice de spécialisation.
Concevoir une politique d’escalade complète avec Human-in-the-Loop (HITL — humain dans la boucle) : déclencheurs, motifs d’escalade, intégration du feedback humain et gestion des SLA (Service Level Agreement — accord de niveau de service).
Implémenter les patrons de gestion d’erreurs propres aux systèmes multi-agents : retry idempotent, checkpointing d’état, circuit breaker (disjoncteur logiciel), dégradation gracieuse et files de lettres mortes (DLQ — Dead Letter Queue).
Instrumenter un système multi-agents avec du traçage distribué et des identifiants de corrélation.

Plan de la session

Bloc	Durée	Contenu
1	40 min	Stratégies de décomposition de tâches (Chapitre 8)
2	40 min	Escalade et Human-in-the-Loop (Chapitre 9)
3	40 min	Gestion d’erreurs multi-agents (Chapitre 10)
4	90 min	Exercices pratiques + démonstration interactive (page web)
5	10 min	Quiz de validation et synthèse

Bloc 1 — Stratégies de décomposition de tâches

1.1 Pourquoi décomposer ?

Un agent unique confronté à une tâche complexe rencontre trois murs :

Le mur du contexte : la fenêtre de contexte (quantité de texte que le modèle peut traiter en une fois) est finie. Une tâche massive sature le contexte et dégrade la qualité des réponses.
Le mur de la cohérence : plus une tâche est longue, plus le risque de dérive (perte de fil, contradictions internes) augmente.
Le mur de la spécialisation : un prompt système généraliste est moins performant qu’un prompt spécialisé sur chaque sous-domaine.

La décomposition transforme un problème monolithique en un graphe de sous-tâches confiées à des agents dédiés, coordonnés par un orchestrateur.

Point pédagogique : insistez sur le fait que la décomposition n’est pas gratuite. Chaque agent supplémentaire ajoute de la latence, du coût en tokens et de la complexité opérationnelle. La question n’est jamais « peut-on décomposer ? » mais « le gain dépasse-t-il le coût ? ».

1.2 Décomposition verticale (par profondeur)

Principe : découper le flux de travail en étapes séquentielles de nature différente. Le motif canonique :

Planification → Exécution → Vérification

Agent planificateur : analyse la demande, produit un plan structuré (liste ordonnée de sous-tâches, dépendances, critères de succès).
Agent exécutant : réalise chaque étape du plan (appels d’outils, génération de contenu, transformations).
Agent vérificateur : contrôle le résultat contre les critères de succès, détecte les incohérences, déclenche des corrections.

Avantages :

Chaque agent a un prompt système court et ciblé.
Le vérificateur, indépendant de l’exécutant, réduit les biais d’auto-évaluation (un agent qui vérifie son propre travail est notoirement indulgent avec lui-même).
Le plan sert de contrat : il est auditable et modifiable par un humain avant exécution.

Limites :

Latence cumulée : chaque étage attend le précédent.
Le plan peut devenir obsolète en cours d’exécution si l’environnement change (nécessite une boucle de replanification).

Exemple d’implémentation (pseudocode Python) :

class VerticalPipeline:
    def __init__(self, planner, executor, verifier, max_repairs=2):
        self.planner = planner        # Agent LLM avec prompt "planificateur"
        self.executor = executor      # Agent LLM avec accès aux outils
        self.verifier = verifier      # Agent LLM avec prompt "auditeur"
        self.max_repairs = max_repairs

    def run(self, task: str) -> Result:
        plan = self.planner.plan(task)          # → liste d'étapes + critères
        result = self.executor.execute(plan)    # → artefacts produits
        for attempt in range(self.max_repairs):
            report = self.verifier.check(result, plan.success_criteria)
            if report.ok:
                return Result(status="success", artifacts=result)
            # Le rapport d'audit devient une consigne de réparation
            result = self.executor.repair(result, report.issues)
        return Result(status="needs_human_review", artifacts=result)

Notez la sortie needs_human_review : la décomposition verticale s’articule naturellement avec l’escalade (Bloc 2).

1.3 Décomposition horizontale (par domaine)

Principe : découper par domaine de compétence. Chaque agent est propriétaire d’un domaine et le traite de bout en bout.

Exemple — analyse d’un dossier de conformité financière :

                    ┌──────────────────┐
                    │  Orchestrateur   │
                    └────────┬─────────┘
         ┌──────────────┬────┴─────────┬───────────────┐
         ▼              ▼              ▼               ▼
  Agent juridique  Agent fiscal   Agent risque   Agent rédaction
  (réglementation) (imposition)   (scoring)      (synthèse finale)

Les agents juridique, fiscal et risque travaillent en parallèle (gain de latence majeur).
L’agent de rédaction fusionne les analyses (étape de fan-in, convergence des résultats).

Avantages :

Parallélisme natif → latence proche de celle de l’agent le plus lent, pas de la somme.
Spécialisation maximale : chaque agent embarque le vocabulaire, les outils et les garde-fous de son domaine.
Isolation des pannes : l’échec de l’agent fiscal n’empêche pas l’agent juridique de livrer.

Limites :

Risque d’incohérences inter-domaines (deux agents tirent des conclusions contradictoires) → nécessite une étape de réconciliation.
L’orchestrateur doit savoir router : mal découper les frontières de domaines crée des zones grises où aucun agent ne se sent responsable.

1.4 Décomposition récursive

Principe : chaque agent peut lui-même décomposer sa sous-tâche et déléguer à des sous-agents, formant un arbre de délégation.

Orchestrateur racine
├── Agent A (sous-tâche 1)
│   ├── Sous-agent A1
│   └── Sous-agent A2
│       └── Sous-sous-agent A2a
└── Agent B (sous-tâche 2)

Règles de sécurité indispensables :

Profondeur maximale (max_depth) : sans limite, un agent peut créer une récursion infinie de délégations. Valeur typique : 2 à 3 niveaux. ⚠ (valeur indicative, à calibrer selon votre charge)
Budget de tokens hérité : chaque niveau reçoit une fraction du budget parent. Si le parent a 100 000 tokens, il n’en délègue par exemple que 30 000 par enfant.
Contrat de résultat : chaque sous-agent retourne un format structuré (JSON avec statut, artefacts, coût consommé), jamais du texte libre non contraint.

Quand la récursion brille : les problèmes à structure fractale — revue de code d’un monorepo (chaque module se décompose en fichiers), due diligence documentaire (chaque dossier se décompose en pièces), génération de sites (chaque page se décompose en sections).

1.5 Quand décomposer ? Les trois critères de décision

Critère	Question à poser	Seuil indicatif
Seuil de complexité	La tâche comporte-t-elle plus de N étapes hétérogènes ? Un seul prompt système peut-il couvrir tous les cas ?	> 5–7 étapes distinctes ⚠
Budget de tokens	Le contexte nécessaire (documents + historique + outils) dépasse-t-il ~60–70 % de la fenêtre ? ⚠	Saturation prévisible → décomposer
Bénéfice de spécialisation	Des prompts spécialisés amélioreraient-ils mesurablement la qualité par domaine ?	Gain qualité > surcoût orchestration

Arbre de décision à présenter au tableau :

La tâche tient-elle confortablement dans un seul contexte avec une qualité acceptable ? → Ne décomposez pas. (L’architecture la plus robuste est celle qui n’existe pas.)
Les étapes sont-elles de natures différentes (planifier vs exécuter vs vérifier) ? → Verticale.
Les sous-problèmes relèvent-ils de domaines différents et parallélisables ? → Horizontale.
La structure est-elle imprévisible ou fractale ? → Récursive, avec garde-fous stricts.
Cas réels : souvent hybride — un pipeline vertical dont l’étape d’exécution est horizontale.

Piège de certification : les questions d’examen opposent souvent verticale et horizontale sur un cas ambigu. Le discriminant fiable : séquentialité de natures différentes → verticale ; parallélisme de domaines → horizontale.

Bloc 2 — Escalade et Human-in-the-Loop (HITL)

2.1 Pourquoi l’escalade est une exigence d’architecture, pas une option

Aucun système d’agents n’atteint 100 % d’autonomie fiable. L’architecte doit concevoir dès le départ les chemins par lesquels le système rend la main à l’humain. Un système sans escalade explicite escalade quand même — mais de façon chaotique : tickets support, incidents, perte de confiance.

HITL (Human-in-the-Loop — humain dans la boucle) désigne l’ensemble des mécanismes par lesquels un humain valide, corrige ou reprend le travail d’un agent.

2.2 Les trois déclencheurs d’escalade

a) Confiance sous le seuil

L’agent (ou un modèle évaluateur) produit un score de confiance sur sa propre sortie. Sous un seuil défini, la tâche est escaladée.

CONFIDENCE_THRESHOLD = 0.75  # ⚠ à calibrer sur données réelles, jamais au doigt mouillé

assessment = judge_agent.evaluate(answer, context)
if assessment.confidence < CONFIDENCE_THRESHOLD:
    escalate(task, reason="low_confidence", score=assessment.confidence)

Point critique à enseigner : les LLM (Large Language Models — grands modèles de langage) sont mal calibrés sur leur propre confiance auto-déclarée. Bonnes pratiques :

Utiliser un agent juge distinct plutôt que l’auto-évaluation.
Calibrer le seuil sur un jeu de validation étiqueté (courbe précision/taux d’escalade).
Surveiller la dérive du taux d’escalade en production (un taux qui chute brutalement peut signaler un juge devenu complaisant, pas un système devenu meilleur).

b) Détection hors périmètre (out-of-scope)

L’agent reconnaît que la demande sort de son domaine autorisé : sujet non couvert, langue non supportée, demande de conseil réglementé (juridique, médical, financier), tentative de contournement.

Implémentation typique : un classifieur de périmètre en amont (petit modèle rapide) + une consigne d’auto-détection dans le prompt système de l’agent (défense en profondeur — deux couches valent mieux qu’une).

c) Niveau de risque

Certaines actions sont escaladées par nature, indépendamment de la confiance : virement au-delà d’un montant, suppression de données, communication externe engageante, modification de production. On définit une matrice de risque :

Impact \ Réversibilité	Réversible	Irréversible
Faible	Autonome	Autonome + journalisation renforcée
Moyen	Autonome + revue a posteriori	Approbation humaine préalable
Élevé	Approbation humaine préalable	Approbation humaine + double validation

2.3 Les trois patrons d’escalade

Patron 1 — Pause-and-ask (pause et question)

L’agent suspend son exécution, pose une question précise à l’humain, attend la réponse, puis reprend. Synchrone du point de vue de la tâche.

Usage : ambiguïté bloquante en cours de tâche, décision ponctuelle (choix entre deux options).
Exigence technique : l’état de l’agent doit être sérialisable (sauvegardable) pour survivre à l’attente — l’humain peut répondre dans 4 heures.
Risque : accumulation de tâches suspendues si les humains ne répondent pas → prévoir un timeout (voir SLA, §2.5).

Patron 2 — Queue-for-review (file de revue)

L’agent termine son travail mais le résultat est placé dans une file de validation avant publication/exécution. Asynchrone, l’agent est libéré immédiatement.

Usage : production de contenu à enjeu (réponses clients, documents contractuels), actions batch.
Avantage : l’humain traite par lots, avec une interface de revue dédiée (diff, approuver/rejeter/corriger).
Métrique clé : le taux d’approbation sans modification. S’il dépasse durablement ~98 % ⚠, envisager de passer certaines catégories en autonome (avec échantillonnage de contrôle).

Patron 3 — Fallback-to-human (transfert à l’humain)

L’agent abandonne la tâche et la transfère intégralement à un humain, avec tout le contexte accumulé. C’est le filet de sécurité terminal.

Usage : échec répété, situation hors périmètre, détresse utilisateur détectée, risque juridique.
Règle d’or du transfert : l’humain ne doit jamais repartir de zéro. Le paquet de transfert contient : la demande initiale, l’historique des actions de l’agent, les hypothèses testées, la raison précise de l’escalade. Un transfert sans contexte détruit la valeur du travail agent.

2.4 Intégration du feedback humain

L’escalade n’est pas seulement un filet de sécurité — c’est un capteur d’apprentissage. Chaque correction humaine est une donnée.

Boucle de feedback en quatre temps :

Capture : chaque décision humaine (approbation, rejet, correction) est journalisée de façon structurée : {task_id, sortie_agent, action_humaine, sortie_corrigée, motif}.
Agrégation : analyse périodique des corrections par catégorie — quels types de tâches sont le plus souvent corrigés ? Quels motifs reviennent ?
Injection : les enseignements retournent dans le système par trois canaux, du plus léger au plus lourd :
- Prompt système : ajout de règles et contre-exemples tirés des corrections récurrentes.
- Exemples few-shot / base de connaissances : les paires (cas → correction validée) alimentent la récupération de contexte (RAG — Retrieval-Augmented Generation, génération augmentée par récupération).
- Fine-tuning (ajustement fin du modèle) : uniquement si le volume de corrections est suffisant et le comportement cible stable. ⚠ Coûteux, à réévaluer à chaque évolution de modèle de base.
Mesure : le taux de correction par catégorie doit baisser après injection. Sinon, la boucle ne boucle pas — c’est du théâtre de feedback.

Point d’insistance pédagogique : beaucoup d’organisations capturent le feedback mais ne l’injectent jamais. La question d’audit à poser : « montrez-moi la dernière modification de prompt motivée par une correction humaine, et sa date ».

2.5 Gestion des SLA d’escalade

Une escalade sans SLA (Service Level Agreement — accord de niveau de service) est une escalade vers un trou noir.

Composants d’une politique de SLA :

Timeout d’escalade : si aucun humain ne répond dans le délai, une action par défaut s’applique. Trois stratégies de timeout :
- Fail-safe (sécurité par défaut) : la tâche est annulée ou mise en attente prolongée — pour les actions risquées.
- Fail-operational : l’agent applique l’option conservatrice pré-approuvée — pour les tâches à faible enjeu.
- Ré-escalade : la demande monte d’un niveau (n+1 hiérarchique, équipe d’astreinte).
Files de priorité : toutes les escalades ne se valent pas. File typique à trois niveaux :

Priorité	Exemple	Délai cible ⚠ (indicatif)
P1 — Critique	Transaction bloquée, client en détresse, risque légal	< 15 min
P2 — Standard	Validation de contenu, ambiguïté non bloquante	< 4 h
P3 — Différable	Revue par échantillonnage, amélioration continue	< 48 h

Routage par compétence : l’escalade juridique va au juriste, pas au support généraliste. Le paquet d’escalade porte des étiquettes (domaine, langue, urgence) exploitées par le routeur.
Tableaux de bord : taux d’escalade, temps de première réponse humaine, taux de dépassement de SLA, répartition par motif. Ce sont des métriques d’architecture, pas seulement d’exploitation.

Bloc 3 — Gestion d’erreurs dans les systèmes multi-agents

3.1 La propagation d’erreurs : l’effet domino

Dans un système multi-agents, une erreur locale devient systémique par cascade à travers l’orchestrateur :

Sous-agent C échoue
      ↓
Agent B attend C → timeout → B échoue
      ↓
L'orchestrateur reçoit deux échecs corrélés → abandonne la mission entière
      ↓
Résultat : 45 minutes de travail des agents A, D, E jetées à la poubelle

Trois principes anti-cascade :

Isolation (bulkheads — cloisons étanches) : l’échec d’une branche ne doit pas invalider les branches indépendantes. L’orchestrateur agrège les résultats partiels : « 4 analyses sur 5 livrées, l’analyse fiscale a échoué ».
Timeouts systématiques : tout appel inter-agents porte un délai maximal. Un agent qui attend indéfiniment est une panne silencieuse.
Typologie d’erreurs : distinguer les erreurs réessayables (timeout réseau, rate limit — limite de débit d’API, surcharge temporaire) des erreurs fatales (entrée invalide, permission refusée, contrainte métier violée). Réessayer une erreur fatale gaspille du budget et retarde l’escalade.

class AgentError(Exception):
    retryable: bool

class RateLimitError(AgentError):   retryable = True
class ToolTimeoutError(AgentError): retryable = True
class InvalidInputError(AgentError): retryable = False
class PolicyViolationError(AgentError): retryable = False

3.2 Stratégies de retry (nouvelle tentative)

a) La condition préalable : l’idempotence des outils

Un outil est idempotent si l’exécuter deux fois produit le même effet qu’une fois. Sans idempotence, le retry est dangereux : rejouer « créer une facture » après un timeout ambigu peut créer un doublon (le timeout ne dit pas si la première tentative a abouti côté serveur).

Technique standard : la clé d’idempotence — le client génère un identifiant unique par intention d’opération ; le serveur déduplique.

import uuid

def create_invoice(client_id: str, amount: float) -> Invoice:
    idem_key = f"inv-{uuid.uuid4()}"          # générée UNE fois par intention
    for attempt in range(3):
        try:
            return api.post("/invoices",
                            json={"client_id": client_id, "amount": amount},
                            headers={"Idempotency-Key": idem_key})
        except TransientError:
            sleep(backoff(attempt))            # backoff exponentiel + jitter
    raise ToolFailedError("create_invoice", idem_key)

def backoff(attempt: int) -> float:
    """Backoff exponentiel avec jitter (gigue aléatoire) pour éviter
    que tous les agents ne réessaient au même instant (thundering herd)."""
    import random
    return min(30, (2 ** attempt)) * random.uniform(0.5, 1.5)

Règle d’architecte : dans la spécification de chaque outil exposé aux agents, documenter explicitement idempotent: true/false. L’orchestrateur n’autorise le retry automatique que sur les outils marqués idempotents.

b) Checkpointing d’état (points de sauvegarde)

Pour les tâches longues, sauvegarder l’état à chaque jalon permet de reprendre après échec sans tout rejouer :

class CheckpointedMission:
    def run(self, mission_id: str):
        state = self.store.load(mission_id) or MissionState.initial()
        for step in self.plan.steps:
            if step.id in state.completed_steps:
                continue                       # déjà fait : on saute
            result = self.execute(step, state)
            state.record(step.id, result)
            self.store.save(mission_id, state)  # checkpoint après CHAQUE jalon

Le checkpoint contient : étapes accomplies, artefacts produits, budget consommé, et le contexte minimal nécessaire à la reprise (pas tout l’historique de conversation — le résumer).

c) Rollback partiel (annulation partielle)

Quand une étape échoue au milieu d’une séquence avec effets de bord, on annule les effets de la séquence en cours sans détruire le travail des séquences validées. Patron : compensation (chaque action possède une action inverse enregistrée). Inspiré du patron Saga des architectures microservices :

Étape 1 : réserver stock       → compensation : libérer stock
Étape 2 : débiter compte       → compensation : recréditer compte
Étape 3 : créer expédition ✗ ÉCHEC
→ Rejouer les compensations 2 puis 1 (ordre inverse), état cohérent restauré.

3.3 Le patron Circuit Breaker (disjoncteur logiciel)

Problème : un service externe (API d’outil, sous-agent) tombe en panne. Sans protection, chaque tâche continue de l’appeler, subit le timeout complet, gaspille tokens et latence, et surcharge le service déjà agonisant.

Solution : un disjoncteur avec trois états, comme un disjoncteur électrique :

                 N échecs consécutifs
   ┌─────────┐ ─────────────────────► ┌─────────┐
   │  FERMÉ  │                        │ OUVERT  │
   │(closed) │ ◄──── succès ────┐     │ (open)  │
   └─────────┘                  │     └────┬────┘
   appels passent               │          │ après délai de refroidissement
   normalement                  │          ▼ (cooldown)
                          ┌─────┴───────────┐
                          │   SEMI-OUVERT   │──── échec ────► retour à OUVERT
                          │   (half-open)   │
                          └─────────────────┘
                          laisse passer UN appel d'essai

FERMÉ (closed) : fonctionnement normal ; on compte les échecs consécutifs.
OUVERT (open) : après N échecs (ex. : 5 ⚠, à calibrer), les appels sont rejetés immédiatement sans être tentés. Le système échoue vite (fail fast) et le service en panne souffle.
SEMI-OUVERT (half-open) : après un délai de refroidissement (ex. : 30 s ⚠), un unique appel d’essai passe. Succès → retour à FERMÉ. Échec → retour à OUVERT.

import time

class CircuitBreaker:
    def __init__(self, failure_threshold=5, cooldown_s=30):
        self.failure_threshold = failure_threshold
        self.cooldown_s = cooldown_s
        self.failures = 0
        self.state = "closed"
        self.opened_at = None

    def call(self, fn, *args, **kwargs):
        if self.state == "open":
            if time.time() - self.opened_at >= self.cooldown_s:
                self.state = "half_open"       # tentative d'essai autorisée
            else:
                raise CircuitOpenError("appel rejeté : circuit ouvert")
        try:
            result = fn(*args, **kwargs)
        except TransientError:
            self._on_failure()
            raise
        self._on_success()
        return result

    def _on_failure(self):
        self.failures += 1
        if self.state == "half_open" or self.failures >= self.failure_threshold:
            self.state = "open"
            self.opened_at = time.time()

    def _on_success(self):
        self.failures = 0
        self.state = "closed"

Spécificité multi-agents : placer un disjoncteur par dépendance (un par outil externe, un par sous-agent), jamais un disjoncteur global. Quand un disjoncteur s’ouvre, l’orchestrateur doit le savoir pour activer la dégradation gracieuse (§3.4) plutôt que de laisser les tâches s’écraser contre lui.

3.4 Dégradation gracieuse

Principe : face à une panne partielle, réduire la capacité plutôt qu’échouer complètement. Le système livre un service diminué mais honnête.

Échelle de dégradation (à concevoir a priori, pas dans la panique) :

Niveau	Situation	Comportement
0 — Nominal	Tout fonctionne	Service complet
1 — Dégradé léger	Un outil d’enrichissement en panne	Réponse sans l’enrichissement, mention explicite du manque
2 — Dégradé fort	Sous-agent spécialisé indisponible	Réponse générique par l’agent principal + avertissement + proposition d’escalade
3 — Minimal	Modèle principal indisponible	Bascule sur modèle de secours plus petit, périmètre restreint ⚠
4 — Refus honnête	Rien ne fonctionne	Message d’indisponibilité + capture de la demande pour traitement différé

Deux règles absolues :

Transparence : ne jamais livrer une réponse dégradée en la présentant comme complète. « L’analyse fiscale n’a pas pu être réalisée (service indisponible) ; voici les 4 autres volets » — c’est acceptable. Le silence sur le manque ne l’est pas.
Dégradation ≠ baisse de sécurité : les garde-fous (filtres, validations, escalades) ne se dégradent jamais. On dégrade la capacité, pas le contrôle.

3.5 Dead Letter Queue (DLQ — file de lettres mortes)

Principe : une tâche qui a épuisé ses retries et ne peut être traitée n’est jamais silencieusement supprimée. Elle est déposée dans une file dédiée — la file de lettres mortes — avec tout son contexte de diagnostic.

Contenu d’une entrée DLQ bien formée :

{
  "task_id": "task-8842",
  "correlation_id": "corr-a1b9f3",
  "deposited_at": "2026-07-02T14:31:07Z",
  "attempts": 3,
  "last_error": {"type": "ToolTimeoutError", "tool": "search_registry", "timeout_s": 60},
  "agent_chain": ["orchestrator", "agent-juridique", "sub-agent-registre"],
  "payload": { "...la tâche originale intacte..." },
  "state_checkpoint_ref": "ckpt://missions/8842/step-3"
}

Exploitation de la DLQ :

Alerte : un dépôt en DLQ déclenche une notification (la DLQ qui grossit en silence est un anti-patron classique).
Rejeu : après correction de la cause racine, les entrées sont rejouées — d’où l’importance des clés d’idempotence et des checkpoints.
Analyse de tendance : la composition de la DLQ est un miroir des faiblesses du système. 80 % de ToolTimeoutError sur le même outil = problème d’infrastructure, pas d’agents.

3.6 Observabilité : traçage distribué et identifiants de corrélation

Dans un système où une demande traverse un orchestrateur, trois agents et sept appels d’outils, répondre à « pourquoi cette réponse est-elle fausse ? » sans traçage relève de l’archéologie.

a) Identifiant de corrélation (correlation ID)

Un identifiant unique est généré à l’entrée de la demande et propagé à travers chaque agent, chaque appel d’outil, chaque message de file. Toute ligne de journal le porte.

import contextvars, uuid

correlation_id = contextvars.ContextVar("correlation_id")

def handle_request(request):
    cid = request.headers.get("X-Correlation-ID") or f"corr-{uuid.uuid4().hex[:8]}"
    correlation_id.set(cid)
    log.info("request.received", cid=cid, task=request.task)
    return orchestrator.run(request, cid=cid)   # propagation explicite aux sous-agents

Règle : grep corr-a1b9f3 logs/* doit reconstituer l’intégralité du parcours d’une demande. Si un composant « perd » l’identifiant, l’observabilité est cassée à cet endroit précis.

b) Traçage distribué (distributed tracing)

Au-delà des logs : chaque opération devient un span (segment chronométré) rattaché à une trace (l’arbre complet de la demande). Standard de facto : OpenTelemetry (spécification ouverte d’observabilité).

Trace corr-a1b9f3 (durée totale : 42,3 s)
└── span orchestrator.run                    [42,3 s]
    ├── span planner.plan                    [3,1 s]  ✓
    ├── span agent-juridique.analyze         [18,2 s] ✓
    │   ├── span tool.search_registry        [12,0 s] ✓  ← goulot identifié
    │   └── span llm.generate                [5,9 s]  ✓
    ├── span agent-fiscal.analyze            [17,8 s] ✗ TIMEOUT
    │   └── span tool.tax_api                [15,0 s] ✗  ← cause racine
    └── span redactor.merge                  [2,4 s]  ✓ (mode dégradé niveau 1)

Attributs de span spécifiques aux agents LLM à capturer : modèle utilisé, tokens entrée/sortie, coût estimé, nom de l’outil, décision d’escalade, état du disjoncteur, version du prompt système. Ces attributs transforment le traçage en outil d’optimisation de coûts et de qualité, pas seulement de débogage.

Question d’audit d’architecture (à poser telle quelle en entretien de certification) : « Montrez-moi la trace complète d’une demande qui a échoué la semaine dernière, du point d’entrée jusqu’à la DLQ. » Si l’équipe ne peut pas, l’observabilité est déclarative, pas réelle.

Synthèse : la grille de l’architecte

Domaine	Question de conception	Artefact livrable
Décomposition	Verticale, horizontale, récursive — et pourquoi ?	Diagramme d’architecture + justification des 3 critères
Escalade	Quels déclencheurs, quels patrons, quels SLA ?	Politique d’escalade + matrice de risque
Erreurs	Que se passe-t-il quand X tombe ? (pour chaque X)	Carte des modes de panne + échelle de dégradation
Retry	Quels outils sont idempotents ?	Spécification d’outils annotée
Observabilité	Peut-on rejouer l’histoire d’une demande ?	Schéma de propagation du correlation ID

Message final aux futurs certifiés : un système multi-agents n’est pas jugé sur son comportement quand tout va bien — n’importe quelle démo y arrive. Il est jugé sur son comportement quand un outil timeout, quand un agent hallucine, quand un humain ne répond pas. La certification évalue précisément cela : l’architecture des mauvais jours.

Notes pour l’instructeur

Démo interactive (webpage/index.html) : utilisez le simulateur de circuit breaker en direct — basculez les échecs et faites constater les transitions d’états par la classe. C’est le concept le plus abstrait de la session ; la simulation le rend tangible.
Erreur fréquente des participants : confondre queue-for-review (l’agent finit, l’humain valide après) et pause-and-ask (l’agent s’arrête, l’humain débloque pendant). Insistez avec un exemple chronologique.
Lien certification : les chapitres 8–10 pèsent lourd dans l’examen Claude Certified Architect ⚠ (pondération susceptible d’évoluer — vérifier le syllabus officiel en vigueur). Les questions croisent souvent deux chapitres (ex. : « un sous-agent échoue 5 fois : circuit breaker ou escalade ? » — réponse : les deux, dans cet ordre).
Timing : si le temps manque, sacrifiez le §3.2c (rollback partiel/Saga) plutôt que l’observabilité — le traçage est systématiquement évalué.