Comment construire un système multi-agents : guide pratique du pattern supervisor

Une fois assimilé le concept de « coordonner plusieurs IA » dans Qu'est-ce qu'un système multi-agents ?, la question suivante est comment en construire un concrètement. Cet article détaille un processus pratique en 5 étapes pour les débutants, en s'appuyant sur le standard de fait de 2026 : le pattern supervisor.

Avant de parler de frameworks, voici le principe le plus important : « construisez d'abord avec un seul agent, et n'ajoutez des agents, au minimum, qu'après avoir atteint une limite. » Commencer d'emblée avec une foule d'agents relève presque toujours de la sur-ingénierie. La seconde moitié présente un code minimal et lisible qui suit la documentation officielle du Claude Agent SDK et de l'OpenAI Agents SDK, ainsi que la manière de répartir les rôles et les échecs qui surviennent vraiment. La même logique vaut si vous branchez des outils via MCP.

Note : le code suit la documentation officielle du Claude Agent SDK et de l'OpenAI Agents SDK (vérifiée le 4 octobre 2026). Ces SDK évoluent vite : vérifiez le nom des paramètres dans chaque documentation officielle avant d'exécuter quoi que ce soit. Chaque chiffre de l'article indique sa source.

1. Avant de construire : avez-vous vraiment besoin du multi ?

Le premier filtre n'est pas technique — c'est une question de jugement. Le multi-agents est puissant, mais il n'aide pas pour tous les travaux. Si aucun des points suivants ne s'applique, construisez d'abord avec un agent unique.

À l'inverse, comme vu dans l'article précédent, utiliser le multi-agents sur un processus linéaire coûte cher. Dans une étude de Google Research (publiée en janvier 2026, 180 configurations comparées), toutes les variantes multi-agents testées ont fait 39 à 70 % moins bien qu'un agent unique sur une tâche de raisonnement strictement séquentiel (PlanCraft). Les coûts grimpent aussi : dans sa présentation de son propre agent de recherche, Anthropic indique que les agents consomment environ 4 fois plus de tokens qu'un chat, et les systèmes multi-agents environ 15 fois plus. Partez du principe que plus d'agents ne veut pas dire plus d'intelligence.

2. La forme de base : le pattern supervisor

Si vous hésitez sur le pattern à construire, commencer par le pattern supervisor est le choix le plus sûr. Les principaux SDK le documentent comme pattern de base. Dans le Claude Agent SDK, l'agent principal appelle des sous-agents via l'outil Agent ; dans l'OpenAI Agents SDK, l'équivalent est « agents as tools » : un agent manager appelle des agents spécialisés comme des outils.

Le mécanisme est simple. Le supervisor reçoit la tâche globale, la découpe en sous-tâches, les délègue à des workers spécialisés et agrège les résultats. Le supervisor n'a pas besoin de savoir comment un worker fait son travail — seulement quel worker appeler et dans quel format de sortie. L'expertise réside dans les workers.

Attention : dans l'OpenAI Agents SDK, un handoff a un sens plus étroit que la passation générale de l'étape 4 : un agent de tri transmet la conversation elle-même à un spécialiste, qui répond ensuite directement à l'utilisateur. Aucun supervisor ne reste : traitez-le comme un pattern distinct (la section 6 explique quand choisir l'un ou l'autre).

3. Le construire en 5 étapes

Assemblez une configuration supervisor minimale en cinq étapes. La règle d'or : commencez avec 2-3 workers, puis n'en ajoutez d'autres que lorsque la mesure le justifie.

4. Code minimal ① : Claude Agent SDK (Python)

Commençons par monter un supervisor et deux workers (un chercheur et un relecteur) avec le Claude Agent SDK d'Anthropic. La préparation se limite à pip install claude-agent-sdk et à la variable d'environnement ANTHROPIC_API_KEY (quickstart officiel ; le SDK ne charge pas les fichiers .env automatiquement). Le code suit la page officielle Subagents. Pour le SDK dans son ensemble, voir notre guide du Claude Agent SDK.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition, ResultMessage

options = ClaudeAgentOptions(
    model="claude-opus-5-5",  # le supervisor (agent principal)
    system_prompt=(
        "You coordinate a research report. Delegate research to researcher and fact-checking "
        "to reviewer, and write the final text yourself. When delegating, always state the "
        "goal, the output format, and the scope."
    ),
    allowed_tools=["Agent", "WebSearch", "WebFetch"],  # outils exécutés sans demande d'autorisation
    agents={
        "researcher": AgentDefinition(
            description="Gathers primary sources. Use when facts or figures are needed.",
            prompt="Find primary sources for the question and return bullet points with source URLs. Never fill gaps with guesses.",
            tools=["WebSearch", "WebFetch"],  # les seuls outils de ce rôle
            model="sonnet",
            maxTurns=15,
        ),
        "reviewer": AgentDefinition(
            description="Fact-checks drafts. Always use before finalizing text.",
            prompt="Check each claim in the draft against its source and list every sentence that lacks support.",
            tools=["WebFetch"],
            model="sonnet",
            maxTurns=10,
        ),
    },
    max_turns=30,         # plafond d'allers-retours pour toute l'exécution
    max_budget_usd=5.0,   # plafond de dépense (estimation du SDK)
    env={"CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "1"},  # les workers ne créent pas de sous-agents
)


async def main():
    try:
        async for message in query(
            prompt="Find three official statistics on workplace use of generative AI and write a short report",
            options=options,
        ):
            if isinstance(message, ResultMessage):
                print(message.subtype, message.total_cost_usd)
                print(message.result)
    except Exception as error:
        print(f"Stopped early: {error}")  # atteindre un plafond mène aussi ici


asyncio.run(main())

Cinq points à retenir :

• Les workers se déclarent dans agents sous forme d'entrées AgentDefinition. Le supervisor lit la description de chaque worker pour décider qui appeler et quand : décrivez donc concrètement ce que fait le rôle et quand l'utiliser.
• Si vous listez tools, le rôle n'a que ces outils. C'est pourquoi le relecteur n'a aucun outil d'écriture. allowed_tools, en revanche, liste les outils qui s'exécutent sans demande d'autorisation ; il ne restreint rien (référence Python officielle).
• Posez des plafonds à trois endroits. Un maxTurns par rôle, un max_turns global et un plafond de dépense avec max_budget_usd. Quand un plafond global est atteint, le sous-type du résultat devient error_max_turns ou error_max_budget_usd et l'exécution s'arrête (documentation de la boucle d'agent).
• Coupez l'imbrication. Les sous-agents peuvent créer leurs propres sous-agents. En réglant la variable d'environnement CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH sur 1, les workers font le travail eux-mêmes. CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS (20 par défaut) limite le nombre de sous-agents simultanés.
• Les champs d'AgentDefinition sont en camelCase. Écrire max_turns au lieu de maxTurns déclenche une TypeError dès la construction (note officielle). Le supervisor utilise le modèle actuel claude-opus-5-5 et les workers l'alias "sonnet", pour que le code continue de fonctionner à la sortie d'une nouvelle version.

La documentation officielle signale qu'Opus 5 délègue plus volontiers aux sous-agents que les modèles précédents, et recommande de fixer des limites de profondeur, de simultanéité et de dépense en plus des instructions du prompt. Une instruction ne change que la façon dont Claude demande de l'aide ; seules les limites arrêtent une exécution à coup sûr.

5. Code minimal ② : OpenAI Agents SDK (Python)

Dans l'Agents SDK d'OpenAI, la même forme transforme les agents spécialisés en outils avec as_tool() et les passe aux tools du supervisor (« agents as tools » officiel). La préparation : pip install openai-agents et la variable d'environnement OPENAI_API_KEY (quickstart officiel). Si vous omettez model, le SDK utilise son modèle par défaut ; celui-ci change selon les versions, vérifiez-le donc sur la page Models.

import asyncio
from agents import Agent, Runner, WebSearchTool

researcher = Agent(
    name="Researcher",
    instructions="Find primary sources for the question and return bullet points with source URLs. Never fill gaps with guesses.",
    tools=[WebSearchTool()],
)
reviewer = Agent(
    name="Reviewer",
    instructions="Check each claim in the draft you receive against its source and list every sentence that lacks support.",
)

manager = Agent(
    name="Manager",
    instructions=(
        "You coordinate a research report. Delegate research to research and fact-checking "
        "to review, and write the final text yourself."
    ),
    tools=[
        researcher.as_tool(
            tool_name="research",
            tool_description="Gather primary sources with citations",
            max_turns=10,  # plafond d'allers-retours de ce rôle
        ),
        reviewer.as_tool(
            tool_name="review",
            tool_description="Fact-check a draft",
        ),
    ],
)


async def main():
    result = await Runner.run(
        manager,
        input="Find three official statistics on workplace use of generative AI and write a short report",
        max_turns=10,  # au-delà : MaxTurnsExceeded
    )
    print(result.final_output)


asyncio.run(main())

Ce que les deux SDK ont en commun, et ce qui les distingue :

• Les workers ne connaissent pas la conversation du parent. Un agent appelé via as_tool() n'hérite pas automatiquement de l'état de conversation de l'exécution parente (documentation officielle). Le Claude Agent SDK fonctionne de même : la seule chose qu'un sous-agent reçoit du parent est le prompt de l'outil Agent. Écrivez les chemins de fichiers, les messages d'erreur et les décisions prises dans la demande elle-même.
• Le plafond, c'est Runner.run(..., max_turns=). Au-delà, MaxTurnsExceeded est levée. En passant error_handlers={"max_turns": ...}, vous pouvez renvoyer une réponse contrôlée au lieu d'une exception (Running agents).
• Avec des handoffs, vous écririez Agent(..., handoffs=[billing_agent, refund_agent]). L'agent qui reçoit prend la main sur la conversation et, par défaut, voit tout l'historique précédent. S'il ne doit pas recevoir certaines informations, filtrez-les avec un input_filter.

6. Répartir les rôles : bons et mauvais découpages

Le découpage est plus difficile que le code. Anthropic écrit que chaque sous-agent a besoin d'un objectif, d'un format de sortie, d'indications sur les outils et les sources à utiliser, et de limites claires à sa tâche (même présentation). Voici des découpages qui remplissent ces quatre conditions, et d'autres qui ne les remplissent pas.

La même présentation donne un repère sur le nombre d'agents. Anthropic a inscrit des règles de dimensionnement dans le prompt de son supervisor de recherche : une simple recherche de fait demande 1 agent et 3 à 10 appels d'outils, une comparaison directe 2 à 4 sous-agents avec 10 à 15 appels chacun, et une recherche complexe peut mobiliser plus de 10 sous-agents. Ces chiffres valent pour un travail de recherche : dans votre propre cas, partez du bas de la fourchette et n'augmentez qu'après avoir mesuré.

Pour choisir entre supervisor et handoff, la documentation d'OpenAI donne un critère clair. Si un seul agent doit porter la réponse finale ou s'il faut combiner les résultats de plusieurs spécialistes, prenez le supervisor (agents as tools). Si l'aiguillage est le travail lui-même et que le spécialiste choisi doit répondre directement à l'utilisateur (tri des demandes de support, par exemple), prenez un handoff. Les deux se combinent.

7. Échecs fréquents et solutions

Les points où l'on trébuche sont prévisibles. Voici les échecs qu'Anthropic dit avoir réellement rencontrés avec son agent de recherche, ainsi que les points sur lesquels la documentation officielle des deux SDK met en garde.

La leçon partagée : « les prompts, la conception des outils et le harnais d'evals décident du succès bien plus que le framework. » La documentation d'OpenAI cite elle aussi l'investissement dans de bons prompts, la surveillance et l'itération, des agents spécialisés et les evals. Plutôt qu'une architecture tape-à-l'œil, c'est la discipline de construire petit, mesurer et n'ajouter que lorsque ça rapporte qui est la plus rapide au final.

Résumé

Construire un système multi-agents n'a rien d'effrayant si l'on commence par le pattern supervisor à partir d'une configuration minimale. Récapitulons.

« Construire petit, mesurer, puis ajouter. » Gardez cette discipline et un système multi-agents devient un partenaire puissant pour le travail complexe. Pour le concept, voir Qu'est-ce qu'un système multi-agents ? ; pour en construire un seul, Comment construire un agent IA.

FAQ