Le problème et l'architecture

Un agent unique à qui l'on confie « compare ces trois serveurs d'inférence à partir des 40 documents » lit, lit encore, et chaque tour renvoie au modèle tout ce qu'il a déjà lu. L'invite grossit à chaque tour, le modèle confond la fiche fournisseur de février et le banc d'essai de juillet, et la facture de chaque tour croît avec l'historique. Découper ne règle ce problème que si le découpage est fait proprement : contextes réellement séparés, plafond de dépense par branche, et une étape qui recolle les morceaux sans perdre les désaccords.

Le mécanisme : trois rôles, trois contextes

Le contexte isolé d'un sous-agent se définit par ce qu'il ne reçoit pas : ni la demande globale, ni les questions des autres sous-agents, ni leurs documents. L'isolation n'est pas une phrase dans l'invite, c'est l'outil lire qui refuse un document hors périmètre.

sequenceDiagram
  participant O as Orchestrateur
  participant P as Planificateur
  participant S as Sous-agents (x5)
  participant Y as Synthèse
  O->>P: demande + catalogue (40 lignes)
  P-->>O: Plan (JSON validé)
  par une branche par sous-tâche
    O->>S: question + périmètre + budget
    S-->>O: Constat ou échec
  end
  O->>Y: dossier de preuves
  Y-->>O: contradictions + dossier
  O->>O: contrôles (citations, arbitrages)

Le corpus : 40 documents, quatre pièges

Les documents (files/corpus/doc-01.md à doc-40.md) sont fictifs mais construits comme un vrai fonds documentaire : 31 documents utiles sur cinq axes (performances, coûts, sécurité, exploitation, pérennité) et 9 documents d'autres projets (messagerie, habilitations électriques, imprimante du site de Lens). Quatre contradictions sont plantées, chacune avec une bonne réponse défendable :

Ces pièges servent la grille de qualité de la leçon 5 : un dossier qui recopie 120 ms comme latence de Kestrel est faux, même s'il cite sa source.

Les contrats d'échange

Tout ce qui circule entre les rôles est un modèle pydantic. C'est ce qui permet de valider, de journaliser et de tester sans modèle réel.

class SousTache(BaseModel):
    id: str = Field(description="st-1, st-2, ...")
    question: str = Field(description="La question précise à instruire, autonome")
    doc_ids: list[str] = Field(description="Documents attribués (doc-XX), 8 au maximum")

class Affirmation(BaseModel):
    sujet: str = Field(description="Ex. 'Kestrel - latence p95'")
    enonce: str = Field(description="Le fait, chiffré si possible")
    sources: list[str] = Field(description="doc-XX qui l'établissent")

class Contradiction(BaseModel):
    sujet: str
    retenu: str
    ecarte: str
    sources_retenues: list[str]
    sources_ecartees: list[str]
    regle: str

Le dépôt

Mise en route

cd files
make setup        # .venv, dépendances, .env copié depuis .env.example
make test         # 21 tests, sans clé ni réseau

Renseignez ensuite GOOGLE_API_KEY dans .env pour les leçons suivantes.

Résultat obtenu (2026-10-15)

$ make test
.....................                                                    [100%]
21 passed in 5.92s

Ce qui casse en production

• Découper ce qui n'avait pas besoin de l'être. Symptôme : le dossier coûte deux fois plus cher qu'un agent unique pour une qualité égale. Dans nos mesures (leçon 7), planification et synthèse occupent de 56 à 86 % du temps total. Parade : en dessous de quelques documents par axe, un seul agent avec un bon outil de recherche fait mieux.
• Une contradiction qui traverse deux sous-tâches. Si le bulletin d'avril part chez le sous-agent « sécurité » et les notes de version d'août chez « exploitation », aucun des deux ne voit le conflit. Parade : la consigne du planificateur regroupe les documents qui parlent du même sujet (leçon 2), et la synthèse reçoit les dates et types de source (leçon 5).
• Des sous-agents qui partagent un état mutable. Un dictionnaire partagé où chacun écrit « le dernier chiffre trouvé » ne garde que le dernier écrivain. Parade : chaque sous-agent rend une valeur ; seul l'orchestrateur agrège.

La règle de décision

Utilisez des sous-agents quand la tâche se découpe en axes indépendants, que chaque axe demande plusieurs lectures, et que le contexte d'un agent unique dépasserait ce que le modèle exploite bien. Ne le faites pas pour une question à une seule source, ni quand les axes dépendent les uns des autres en chaîne (un pipeline séquentiel suffit). Surveillez la part du temps et du coût hors sous-agents : si elle domine, le découpage ne paie pas.

Pratique

Exercice. Ouvrez files/corpus/ et repérez, sans regarder le tableau ci-dessus, un cinquième désaccord entre documents qui n'est pas dans la grille. Décidez quelle version retenir et selon quelle règle.

• Je sais dire ce qu'un sous-agent ne doit pas voir, et pourquoi
• Je sais justifier le choix de modèle par rôle
• Je sais reconnaître une tâche qui ne mérite pas de sous-agents
• make test passe sur ma machine