Claude Architect, épisode 2 : systèmes multi-agents et coordinateur

Dans l’épisode 1, on a construit un agent : une boucle qui appelle Claude, exécute les outils demandés et s’arrête sur end_turn. Un agent seul fait déjà beaucoup. Mais dès que la tâche grossit, il touche un plafond.

Cet épisode explique comment le dépasser : plusieurs agents spécialisés, orchestrés par un coordinateur. C’est l’un des sujets les plus testés de l’examen, parce qu’il se prête bien aux questions de diagnostic : « ce système est lent », « ce sous-agent répond à côté », « le rapport final rate l’essentiel ». À la fin de l’épisode, vous saurez trouver la cause.

Objectifs de l’épisode

À la fin, vous saurez :

1. dire pourquoi un agent seul atteint ses limites, et quand passer à plusieurs ;
2. dessiner la topologie en étoile et justifier sa règle d’or ;
3. citer les quatre responsabilités du coordinateur ;
4. décrire les quatre champs d’une AgentDefinition et qui a le droit d’utiliser l’outil Task ;
5. lancer des sous-agents en parallèle, et reconnaître un système qui les lance un par un ;
6. expliquer l’isolation du contexte et comment transmettre l’information utile ;
7. écrire une consigne de sous-agent qui fixe un objectif, pas une procédure ;
8. diagnostiquer un résultat cloisonné et le corriger.

Prérequis : la boucle agentique de l’épisode 1 (stop_reason, paires tool_use / tool_result, API sans état). Tout ce qui suit s’appuie dessus.

1. Le plafond de l’agent unique

Un agent seul fait tout lui-même : il cherche, lit, compare, rédige. Sur une petite tâche, c’est parfait. Sur une grosse, trois problèmes apparaissent.

La réponse : confier chaque morceau à un agent spécialisé, qui travaille avec son propre contexte, réduit au strict nécessaire, et lancer ceux qui sont indépendants en parallèle.

2. La topologie en étoile

L’architecture de référence a une forme d’étoile (hub-and-spoke) : un coordinateur au centre, des sous-agents autour.

Pensez à une équipe de développement. Chaque développeur travaille sur sa fonctionnalité et rend compte à l’architecte. L’architecte assemble le tout et présente le résultat au client. Les développeurs ne se coordonnent pas entre eux dans le dos de l’architecte, et ce n’est pas eux qui présentent le produit final.

Pourquoi cette contrainte ? Parce qu’un seul point de passage apporte trois garanties :

• l’observabilité : tout ce qui se passe est visible au même endroit ;
• la gestion des erreurs centralisée : un seul acteur décide quoi faire d’un échec ;
• l’indépendance : les sous-agents ne dépendent pas les uns des autres, donc ils peuvent tourner en parallèle.

3. Les quatre responsabilités du coordinateur

Le coordinateur ne fait pas le travail de fond. Il fait tourner un cycle de quatre rôles.

1. Décomposer. Transformer une demande vaste en morceaux précis. C’est le coordinateur qui décide s’il faut des sous-agents, combien, et lesquels.
2. Déléguer. Lancer, pour chaque morceau, le sous-agent spécialisé qui convient : un chercheur, un analyste, un rédacteur.
3. Agréger. Récupérer les résultats indépendants et en tirer une réponse cohérente. Ce n’est jamais le travail d’un sous-agent ordinaire.
4. Gérer les erreurs. Un sous-agent peut échouer ou rendre un résultat inutilisable. Le coordinateur décide : réessayer, passer outre, ou signaler le problème.

Une remarque qui relie cet épisode au précédent : le coordinateur est lui-même un agent. Il tourne dans la même boucle agentique, et lancer un sous-agent n’est pour lui qu’un appel d’outil comme un autre. Toute la mécanique de l’épisode 1 reste valable.

4. L’outil Task : comment on lance un sous-agent

Un sous-agent se lance avec un outil dédié, l’outil Task. Le coordinateur le demande avec un bloc tool_use, exactement comme il demanderait lookup_order dans l’épisode 1. La différence, c’est ce que contient l’appel : non pas des paramètres de fonction, mais la définition complète d’un agent.

Configurer le coordinateur

Pour que le coordinateur puisse déléguer, deux conditions doivent être réunies : l’outil Task figure dans ses outils, et il figure dans sa liste d’outils autorisés.

# Configuration de l'agent coordinateur
coordinator_config = {
    "model": "claude-haiku-4-5",          # économique pour orchestrer
    "system": """You are a research coordinator.
Decompose tasks and delegate to specialized subagents.
Specify research goals and quality criteria.
Do NOT provide step-by-step procedures.""",

    "tools": [
        # L'outil Task permet de lancer des sous-agents
        {
            "type": "task",                # type d'outil Task intégré
            "name": "Task",                # doit s'écrire exactement "Task" (T majuscule)
        },
    ],
    # allowedTools DOIT inclure "Task" explicitement
    "allowedTools": ["Task", "compile_report"],
}

Sans "Task" dans allowedTools, le coordinateur ne peut lancer aucun sous-agent : il se retrouve à tout faire lui-même, et on revient au plafond de la section 1.

Le contenu de l’appel : l’AgentDefinition

Quand le coordinateur appelle Task, il doit fournir une AgentDefinition : quatre champs qui décrivent entièrement le sous-agent à créer. Cliquez sur chaque champ :

Assemblé, l’appel complet ressemble à ceci :

task_tool_call = {
    "type": "tool_use",
    "id":   "tu_web_search_001",
    "name": "Task",
    "input": {
        # Les champs de l'AgentDefinition
        "description": "Web Search Specialist",     # étiquette
        "prompt": """Research goal: Find 5-8 recent papers (2022-2025)
on offshore wind energy environmental impact in the EU.
Quality criteria: peer-reviewed, include key findings,
flag conflicting conclusions. Return as structured JSON.""",

        # Sous-agent limité à son rôle : PAS d'outil Task ici
        "allowed_tools": ["web_search", "read_url"],

        "model": "claude-haiku-4-5",
    },
}

from claude_agent_sdk import ClaudeAgentOptions, AgentDefinition

options = ClaudeAgentOptions(
    allowed_tools=["Agent", "WebSearch", "WebFetch"],  # "Task" dans les anciennes versions
    agents={
        "web-search": AgentDefinition(
            description="Web Search Specialist. Use for literature searches.",
            prompt="Find peer-reviewed sources. Flag conflicting conclusions.",
            tools=["WebSearch", "WebFetch"],
            model="haiku",
        ),
    },
)

5. Qui a le droit de lancer des sous-agents ?

Pourquoi interdire Task aux sous-agents ? Imaginez qu’un chercheur puisse lancer d’autres chercheurs, qui en lancent d’autres… On perd la forme en étoile, l’observabilité, le contrôle des coûts, et on s’expose à une boucle de délégation sans fin. Un seul acteur délègue : le coordinateur.

La seule exception est voulue et documentée : dans une architecture hiérarchique, un sous-coordinateur pilote sa propre équipe. Il reçoit Task parce que c’est son rôle, pas par accident.

6. Lancer en parallèle, pas les uns après les autres

C’est ici que le multi-agents devient vraiment intéressant. Le coordinateur peut lancer plusieurs sous-agents en même temps, à une condition précise.

La règle : pour lancer des sous-agents en parallèle, le coordinateur émet plusieurs appels Task dans une seule réponse, et non un appel par tour.

Voici la réponse d’un coordinateur qui lance trois chercheurs en parallèle. Les trois blocs tool_use sont dans le même tableau content :

coordinator_response = {
    "role": "assistant",
    "content": [
        {"type": "text", "text": "Researching in parallel across 3 domains."},

        # Tâche 1
        {"type": "tool_use", "id": "tu_env", "name": "Task",
         "input": {"description": "Environmental Researcher", "prompt": "...",
                   "allowed_tools": ["web_search"], "model": "claude-haiku-4-5"}},

        # Tâche 2
        {"type": "tool_use", "id": "tu_econ", "name": "Task",
         "input": {"description": "Economic Data Researcher", "prompt": "...",
                   "allowed_tools": ["web_search"], "model": "claude-haiku-4-5"}},

        # Tâche 3
        {"type": "tool_use", "id": "tu_policy", "name": "Task",
         "input": {"description": "EU Policy Analyst", "prompt": "...",
                   "allowed_tools": ["web_search"], "model": "claude-haiku-4-5"}},
    ],
    # ↑ Les TROIS dans le même tableau content = exécution PARALLÈLE
    # Un appel par tour = anti-pattern séquentiel
}

Rejouez le déroulé, étape par étape

7. L’isolation du contexte : le piège n° 1

C’est le point que l’examen teste le plus sur la tâche 1.3.

Un sous-agent démarre avec une mémoire vide. Il n’hérite de rien : ni de l’historique de conversation du coordinateur, ni des résultats d’outils précédents, ni d’aucun contexte implicite. Il ne sait que ce qu’on lui transmet explicitement.

Reprenons l’image de l’équipe. Une cheffe de projet est sur le dossier depuis trois semaines : elle connaît le problème, les contraintes, les préférences du client, ce qui a déjà été tenté. Vous embauchez un prestataire pour une tâche précise. Il arrive le matin sans rien savoir de tout ça. Si personne ne lui fait de briefing, il refera des choses déjà faites, ignorera les contraintes, et rendra un travail à côté.

Le sous-agent, c’est ce prestataire. Et le briefing, c’est le coordinateur qui le fait.

Franchir le sas : l’injection explicite

Si un sous-agent a besoin d’une information de l’historique, le coordinateur doit :

1. l’extraire lui-même de sa conversation ;
2. l’écrire explicitement dans le champ prompt de l’appel Task.

1. user → coordinateur
   Résume l'avancement du projet sur le 3ᵉ trimestre. Le client refuse toute dépense au-delà de 50 000 €.
2. coordinateur → Task
   prompt : « Objectif : synthèse de l'avancement du projet, T3 uniquement. Contrainte client : budget plafonné à 50 000 €, signaler tout dépassement. Rendre une liste à puces. »

Sans la deuxième bulle, le sous-agent ignorerait la période et le plafond de budget : il produirait une synthèse générique, hors sujet.

8. Consignes d’orchestration : l’objectif, pas la procédure

Dernier levier : la manière d’écrire le prompt d’un sous-agent.

Pourquoi ? Une procédure rigide casse au premier imprévu. Un objectif clair, assorti de critères pour juger le résultat, laisse le sous-agent trouver le meilleur chemin, tout en gardant le contrôle sur ce qui compte : la qualité de ce qu’il rend.

C’est d’ailleurs ce que dit la consigne système du coordinateur, en section 4 : « Specify research goals and quality criteria. Do NOT provide step-by-step procedures. »

9. Scénario d’examen : le rapport cloisonné

Mettons tout ensemble avec un cas typique.

La situation. Un coordinateur lance quatre sous-agents en parallèle pour un rapport complet : articles scientifiques, presse, rapports gouvernementaux, opinion sur les réseaux sociaux. Chacun fait parfaitement son travail. Le système est rapide. Pourtant, le rapport final passe à côté de l’essentiel : il juxtapose quatre résumés et ne dit rien de ce qui se passe à leurs intersections.

Les fausses pistes. Ce n’est pas une fenêtre de contexte trop petite, ni un mauvais outil, ni une consigne système trop longue : chaque sous-agent a bien fait son travail.

La vraie cause. Une décomposition trop étroite : quatre couloirs indépendants, et personne n’est chargé de la synthèse transversale.

La correction. Ajouter une étape d’agrégation explicite : un dernier passage du coordinateur, consacré à chercher les intersections, ou un cinquième sous-agent dédié à la synthèse, qui rend son résultat au coordinateur.

Fiche de révision

Glossaire

Quiz d’entraînement

Ces questions sont de moi, écrites dans le style de l’examen. Ce ne sont pas des questions officielles. Choisissez une réponse : la correction s’affiche aussitôt, et le score se calcule en bas. Connecté, votre meilleur score est gardé dans votre compte, et « Recommencer » efface seulement vos réponses à l’écran. Sans compte, rien n’est enregistré.

Pour la suite

On sait maintenant lancer, configurer et orchestrer des sous-agents, et diagnostiquer les quatre pannes typiques : délégation impossible, lenteur, sous-agent hors sujet, rapport cloisonné. L’épisode 3 explique comment transmettre ce contexte sans rien perdre, et comment gérer les sessions dans le temps.