D1 — Architecture et orchestration des agents (27 %)

Un seul appel à la Messages API produit une réponse. Une vraie tâche — retrouver le client, consulter la commande, décider d'un remboursement — demande plusieurs actions, chacune choisie à la lumière de ce que la précédente a retourné. L'agentic loop est ce mécanisme : requête, réponse, exécution d'outil, nouvelle requête, jusqu'à ce que le modèle signale qu'il a terminé.

Le cycle, en cinq étapes :

1. Vous envoyez une requête avec l'historique de conversation et le paramètre tools.
2. Claude répond. La réponse peut porter du texte, un ou plusieurs blocs tool_use, ou les deux.
3. Votre code exécute chaque outil demandé et collecte les résultats.
4. Vous ajoutez à l'historique la réponse de l'assistant et les blocs tool_result.
5. Vous renvoyez tout l'historique. On recommence jusqu'à ce que stop_reason soit terminal.

stop_reason est le champ de la réponse qui dit pourquoi la génération s'est arrêtée ; l'ensemble de ses valeurs est catalogué en D0. Deux seulement pilotent cette boucle :

while True:
    response = client.messages.create(
        model="claude-sonnet-5",
        messages=messages,
        tools=tools,
    )
    # Toute la réponse repart : blocs de texte et blocs tool_use ensemble.
    messages.append({"role": "assistant", "content": response.content})

    if response.stop_reason != "tool_use":
        break                      # terminal — D0 catalogue les autres valeurs

    tool_results = execute_tools(response.content)
    messages.append({"role": "user", "content": tool_results})

Deux lignes portent tout le task statement. Le break s'appuie sur stop_reason, sur rien d'autre. Et le second append est ce qui fait de l'itération suivante une étape de raisonnement plutôt qu'une répétition : les résultats d'outils entrent dans l'historique de conversation, donc le prochain choix d'outil se fait à la lumière de ce que le dernier a retourné. Une boucle qui exécute les outils sans jamais ajouter leurs résultats repose éternellement la même question.

Plusieurs appels dans une même réponse

Une même réponse peut aussi porter plusieurs blocs tool_use, par exemple deux recherches que le modèle veut mener ensemble. Exécutez-les toutes, puis renvoyez chaque tool_result dans un seul message user, un bloc par appel. C'est le mécanisme par lequel un coordinateur lance plusieurs subagents à la fois, développé en 1.3.

Les plafonds sont des garde-fous, pas des conditions d'arrêt

Les plafonds ont leur place, tant qu'ils restent des plafonds. L'Agent SDK expose max_turns / maxTurns (allers-retours agentiques) et max_budget_usd / maxBudgetUsd (dépense) ; les deux sont sans limite par défaut, et poser un budget est un bon défaut de production sur un prompt ouvert. Ni l'un ni l'autre n'est une condition de terminaison, et le SDK marque une exécution qui en a atteint un comme un subtype d'erreur, pas comme un succès.

Déléguer à un subagent est une décision qui vient avant toute architecture. Un subagent tourne dans sa propre fenêtre de contexte, fait son travail et ne renvoie qu'un résumé ; les lectures, recherches et appels d'outils intermédiaires sont jetés avec lui. Ce compromis tient en une question : le travail intermédiaire intéresse-t-il l'appelant ? Si seule la réponse compte, déléguez. S'il faut voir et réagir à chaque étape, gardez la main dans le thread principal.

La forme hub-and-spoke

Quand une tâche est vraiment trop large pour un seul agent — un rapport de recherche qui demande recherche web, analyse documentaire et synthèse — on obtient une architecture hub-and-spoke : un coordinateur (le hub) pilote plusieurs subagents spécialisés (les spokes), et tout le trafic passe par le hub.

              Coordinateur (hub)
             /        |         \
   subagent recherche  analyse    synthèse
        (web)        (documents)  (rapport)

   chaque résultat, chaque erreur, chaque retry
   passe hub ↔ spoke — jamais spoke ↔ spoke

Rien dans le SDK n'impose cette forme. C'est un choix de conception, et le guide en nomme les trois motifs : l'observabilité (un seul endroit voit toute l'exécution), la cohérence du traitement d'erreur (une politique, pas une par agent) et le contrôle du flux d'information (le hub décide de ce que chaque spoke apprend).

Ce dont le coordinateur a la charge

Le travail du coordinateur, tel que le guide l'énonce :

Deux savoir-faire sur lesquels portent les questions

Deux compétences méritent d'être énoncées à part, parce que ce sont elles que les questions de scénario mettent en jeu.

Partitionner le périmètre avant de déléguer. Donnez à chaque subagent de recherche un sous-thème distinct ou un type de source distinct. Des briefs qui se recouvrent produisent du travail dupliqué et, pire, des angles morts corrélés.

Raffiner par itération. Le coordinateur lit la sortie de synthèse, y cherche les manques, re-délègue aux subagents de recherche et d'analyse avec des requêtes ciblées, et relance la synthèse jusqu'à couverture suffisante. C'est une boucle de qualité posée au-dessus de la boucle d'exécution de 1.1, et c'est le remède que le guide nomme contre une couverture incomplète.

Une décomposition trop étroite

Le risque que le guide nomme explicitement est une décomposition trop étroite par le coordinateur, et il se voit dans le rapport plutôt que dans les journaux. Un coordinateur à qui l'on demande un panorama de l'IA générative dans les industries créatives assigne « l'IA dans l'art visuel », « l'IA dans la génération d'images », « l'IA en photographie ». Chaque subagent exécute correctement sa consigne. Le rapport ne couvre que l'art visuel ; la musique, la littérature et le cinéma sont simplement absents. Rien n'a échoué en aval. L'assignation était déjà incomplète.

Les erreurs passent aussi par le hub

Les erreurs voyagent de la même façon. Le pattern attendu est la récupération locale d'abord : le subagent traite lui-même les échecs transitoires et ne propage au coordinateur que ce qu'il ne peut pas résoudre, accompagné de ses résultats partiels et de ce qu'il a déjà tenté. Le coordinateur continue avec des résultats partiels et annote la sortie finale de ce qui est resté non couvert. La forme de ces réponses d'erreur — catégories, caractère réessayable, échec métier contre échec de permission — relève de la conception des erreurs structurées, développée en D2.2.

Le mécanisme de lancement est un outil : un coordinateur lance un subagent en appelant l'outil Task, et son allowedTools doit inclure "Task" pour que ces invocations soient auto-approuvées. Omettez-le et l'appel retombe dans le flux de permission : en mode par défaut, sans callback canUseTool pour y répondre, il est refusé. Le coordinateur ne délègue pas, quoi que dise son prompt.

Ce qui franchit la frontière, et ce qui ne la franchit pas

Ce qu'un subagent reçoit, et ce qu'il ne reçoit pas, est le fait le plus testé de ce domaine :

La conséquence est décisive : le seul contenu qui passe du parent au subagent est la chaîne de prompt de l'appel qui le lance. Si les chemins de fichiers, les messages d'erreur, les résultats de recherche antérieurs ou les décisions déjà prises ne sont pas dans cette chaîne, le subagent ne les a pas.

Mauvais  Task: « Analyse le document. »
         → quel document ? aucun résultat antérieur, aucun format de sortie attendu.

Bon      Task: « Analyse le document ci-dessous et renvoie le tableau des clauses.
              DOCUMENT (source: vendor-contract-2026.pdf, pages 4-9) :
                <texte intégral>
              RÉSULTATS ANTÉRIEURS (du subagent de recherche) :
                - claim: 'net-45 payment terms'
                  source_url: https://…  retrieved: 2026-08-14
              FORMAT DE SORTIE : une ligne par clause — clause_type, text, page. »

Notez ce que la bonne version fait au-delà d'être longue. Elle emploie un format structuré qui sépare le contenu des métadonnées. URL source, nom du document, numéro de page et date de collecte vivent dans leurs propres champs, pas fondus dans la prose. C'est ce qui préserve l'attribution jusqu'au rapport final, et le guide le nomme parmi les compétences de ce task statement.

Parallélisme : une réponse, plusieurs appels

Le parallélisme vient d'une réponse, plusieurs appels. Un coordinateur qui émet trois appels Task dans une seule réponse obtient trois subagents qui tournent en même temps ; les mêmes trois appels répartis sur trois tours consécutifs s'exécutent l'un après l'autre. C'est le même mécanisme que les appels d'outils parallèles de 1.1 — plusieurs blocs tool_use dans un même message assistant — appliqué à l'outil Task.

agents = {
    "code-reviewer": AgentDefinition(
        description="Spécialiste de la revue de code. À utiliser pour la "
                    "qualité, la sécurité et la maintenabilité. Indique à "
                    "l'agent précisément quels fichiers relire.",
        prompt="Tu es un spécialiste de la revue de code…\n"
               "Rends : 1. Résumé  2. Problèmes critiques  3. Problèmes majeurs  "
               "4. Problèmes mineurs  5. Verdict  6. Obstacles rencontrés",
        tools=["Read", "Grep", "Glob"],
        model="sonnet",
    ),
}

Les quatre champs d'une définition de subagent

Quatre champs, quatre décisions :

La description a ce double rôle, et il est facile de le manquer. Le nom et la description de chaque subagent disponible sont placés dans le system prompt de l'agent principal : ils décident donc quand la délégation a lieu ; l'agent principal se sert ensuite de la description comme guide pour rédiger le prompt d'entrée, si bien qu'elle façonne aussi ce qu'on dit au subagent de faire. Une description qui dit « vous devez indiquer à l'agent précisément quels fichiers relire » produit des prompts de délégation qui listent des fichiers. Une description vague produit des délégations vagues.

Deux autres leviers de conception. Le premier vient du cours Subagents ; le second est la quatrième compétence que le guide liste sous ce task statement :

• Définissez un format de sortie dans le system prompt. Il donne au subagent une liste à remplir, donc il sait quand il a fini ; sans lui, les subagents peinent à décider quand la recherche a assez duré et tournent bien plus longtemps que nécessaire. Une section « Obstacles rencontrés » vaut d'être ajoutée exprès : les contournements et bizarreries d'environnement découverts par le subagent meurent sinon avec son contexte, et le thread principal doit les redécouvrir.
• Rédigez les prompts de coordinateur en objectifs et critères de qualité, pas en procédures. « Le rapport doit couvrir au moins cinq secteurs avec des sources datées » laisse le subagent libre de s'adapter ; un script pas-à-pas non.

Restreindre les outils d'un subagent

Les restrictions d'outils relèvent aussi d'ici, puisque le guide les liste parmi les connaissances de ce task statement. Un subagent de recherche en lecture seule reçoit Read, Grep, Glob ; un relecteur y ajoute Bash pour lancer git diff ; seul un agent dont le métier est de modifier du code reçoit Edit et Write. Un outil que vous laissez de côté n'est pas du tout dans la session du subagent : ni prompt de permission, ni erreur, l'agent travaille simplement sans. Pourquoi une grande surface d'outils dégrade la fiabilité de sélection, et comment répartir les outils entre agents, relève de la distribution des outils, développée en D2.3.

Forker une session pour donner à deux subagents une base d'analyse commune relève de la gestion des sessions, développée en 1.7 ci-dessous. Définir des subagents comme fichiers markdown sous .claude/agents/, et la commande /agents qui les crée, relève de la configuration Claude Code, développée au domaine 3.

Certains ordonnancements dans un workflow doivent tenir à chaque fois qu'il s'exécute : vérifier l'identité du client avant de traiter un remboursement ; contrôler les interactions médicamenteuses avant de délivrer. Vous pouvez l'écrire dans le system prompt, et une instruction de prompt est une demande que le modèle honore généralement. La formulation du guide est nette : quand une conformité déterministe est requise, les instructions de prompt seules ont un taux d'échec non nul. Sur des milliers d'interactions, ce reliquat, ce sont des remboursements versés au mauvais client.

Le gate de prérequis

Le programmatic enforcement referme cet écart en rendant la violation impossible par le code plutôt qu'improbable par la prose. Sa forme concrète est un prerequisite gate : un appel d'outil en aval est bloqué tant qu'une étape amont n'a pas retourné.

async def require_verified_customer(input_data, tool_use_id, context):
    if input_data["tool_name"] != "process_refund":
        return {}
    if not session_state.get("verified_customer_id"):
        return {"hookSpecificOutput": {
            "hookEventName": "PreToolUse",
            "permissionDecision": "deny",
            "permissionDecisionReason":
                "Appelez d'abord get_customer : process_refund exige un ID "
                "client vérifié pour cette session.",
        }}
    return {}

process_refund ne peut pas s'exécuter tant que get_customer n'a pas retourné un identifiant vérifié. Pas « a peu de chances de » — ne peut pas. La chaîne de raison compte autant que le blocage : le modèle la lit, donc il réessaie la bonne chose au lieu de réessayer à l'aveugle. L'API des hooks elle-même — événements, matchers, champs de décision — est en TS 1.5, ci-dessous.

La demande à plusieurs objets

Un second pattern de ce task statement est la demande multi-sujets. Un client écrit : « Je veux un remboursement sur la commande #1234 et l'adresse de livraison a changé sur la commande #5678. » Traiter cela séquentiellement et répondre en deux blocs déconnectés est l'échec. Le geste attendu : décomposer en items distincts, investiguer chacun en parallèle sur le contexte client partagé, puis synthétiser une résolution unifiée.

Le handoff structuré

Le troisième est le structured handoff. Quand l'agent escalade en cours de traitement, l'humain qui reprend n'a pas accès au transcript de la conversation. Le résumé doit donc se tenir seul :

{
  "customer_id": "CUST-12345",
  "order_id": "ORD-67890",
  "issue_summary": "Demande de remboursement pour article endommagé",
  "root_cause": "Article arrivé endommagé ; photos jointes",
  "actions_taken": [
    "Identité vérifiée via get_customer",
    "Commande confirmée via lookup_order",
    "Remplacement proposé — le client insiste pour un remboursement"
  ],
  "refund_amount": "$89.99",
  "recommended_action": "Approuver le remboursement intégral",
  "escalation_reason": "Le client a demandé à parler à un responsable"
}

Identité du client, cause racine, montant, action recommandée : les quatre que le guide nomme. Un handoff qui suppose que l'humain lira la conversation est un handoff raté.

Quand escalader — les critères, le respect d'une préférence explicite du client, la détection d'un trou dans la politique — relève de la décision d'escalade, développée en D5.2.

Un hook est une fonction de rappel à vous que le SDK exécute quand un événement de l'agent se déclenche. Elle tourne dans le process de votre application, pas dans la fenêtre de contexte de l'agent — elle ne coûte donc aucun token, et c'est du code ordinaire avec des garanties ordinaires.

Deux événements portent ce task statement :

PreToolUse — rendre une action impossible

PreToolUse est le primitif d'application de règles. Son callback retourne un hookSpecificOutput portant permissionDecision ("allow", "deny", "ask", "defer"), un permissionDecisionReason que le modèle lit, et éventuellement updatedInput pour réécrire l'appel plutôt que le refuser.

async def cap_refunds(input_data, tool_use_id, context):
    if input_data["tool_name"] != "process_refund":
        return {}
    if input_data["tool_input"].get("amount", 0) > 500:
        return {"hookSpecificOutput": {
            "hookEventName": "PreToolUse",
            "permissionDecision": "deny",
            "permissionDecisionReason":
                "Un remboursement au-dessus de 500 $ exige un validateur "
                "humain. Appelez escalate_to_human avec le résumé du dossier.",
        }}
    return {}

Le blocage est la moitié du travail ; la raison redirige l'agent vers le workflow alternatif au lieu de le laisser deviner. Quand plusieurs hooks et règles de permission divergent, le SDK tranche par priorité — deny l'emporte sur defer, qui l'emporte sur ask, qui l'emporte sur allow — donc un seul deny suffit.

PostToolUse — changer ce que le modèle lit

PostToolUse est le primitif de normalisation. Son champ updatedToolOutput remplace la sortie de l'outil avant que Claude ne la voie ; additionalContext la complète sans la remplacer.

async def normalize_dates(input_data, tool_use_id, context):
    if input_data["tool_name"] not in ORDER_TOOLS:
        return {}
    raw = json.loads(input_data["tool_response"]["content"])
    return {"hookSpecificOutput": {
        "hookEventName": "PostToolUse",
        "updatedToolOutput": json.dumps({
            **raw,
            "shipped_at": to_iso8601(raw["shipped_at"]),   # 1743800400 → "2025-04-04"
            "status": STATUS_NAMES[raw["status"]],          # 2 → "shipped"
        }),
    }}

C'est le cas du guide, littéralement : plusieurs outils MCP renvoient des dates en timestamps Unix, d'autres en ISO 8601, des statuts en codes numériques. Les faire correspondre est une table fixe, pas un jugement — cela relève donc d'un code qui tourne sur chaque résultat, pas d'un prompt qui demande au modèle de composer avec trois formats.

Les hooks de Claude Code au niveau configuration, déclarés dans les settings plutôt que dans du code SDK, sont développés au domaine 3.

Toutes les tâches ne se découpent pas de la même façon, et se tromper de régime coûte soit de la rigidité, soit du chaos. Il y en a deux.

Pipeline séquentiel fixe — prompt chaining. Chaque étape est décidée à l'avance et s'exécute dans l'ordre. À utiliser quand la structure de la tâche est prévisible, que toutes les étapes sont connues et que vous voulez des résultats stables et comparables d'une exécution à l'autre.

Décomposition dynamique adaptative. Les sous-tâches émergent de ce que l'étape précédente a trouvé. À utiliser pour l'investigation ouverte, quand le périmètre est inconnu au départ.

Les deux exemples du guide

L'exemple de prompt chaining du guide lui-même est la revue de code multi-aspects. Une passe unique sur un gros diff produit une sortie inégale : commentaires détaillés sur certains fichiers, superficiels sur d'autres, et contradictions entre eux. Découpez :

Passe 1 — par fichier, une analyse ciblée chacun
          → bugs locaux, problèmes de qualité, vulnérabilités
Passe 2 — une passe d'intégration inter-fichiers sur les résultats de la passe 1
          → types incohérents, dépendances circulaires, flux de données cassés

Découper ainsi est ce qui évite la dilution de l'attention sur une grosse revue.

L'exemple de décomposition adaptative du guide est « ajouter une couverture de tests complète à un codebase legacy ». Vous ne pouvez pas lister les sous-tâches d'avance, parce qu'elles sont précisément ce que vous allez découvrir :

1. Cartographier la structure         (Glob, Grep)
2. Découverte : 3 modules sans tests, 2 partiellement couverts
3. Prioriser par impact               → le module de paiements d'abord (risque élevé)
4. Surprise : une dépendance vers une API externe non mockée
5. Adapter le plan                    → construire le mock, puis écrire les tests

La formulation du guide est : cartographier la structure, identifier les zones à fort impact, produire un plan priorisé qui s'adapte à mesure que les dépendances apparaissent. L'étape 4 est tout l'enjeu : le plan a changé à cause de ce que l'étape 1 a trouvé.

Une session est l'historique de conversation que le SDK accumule pendant le travail de l'agent — votre prompt, chaque appel d'outil, chaque résultat, chaque réponse — écrit sur disque automatiquement. Les longues investigations s'étalent sur plusieurs sessions de travail, et entre-temps les fichiers changent et les résultats d'outils enregistrés se périment.

Trois opérations, trois métiers différents :

# Forker la base d'analyse pour explorer une seconde approche.
async for message in query(
    prompt="Plutôt que Redux, décris comment la Context API fonctionnerait ici",
    options=ClaudeAgentOptions(
        resume=session_id,      # un fork branche toujours une session existante
        fork_session=True,
        max_turns=5,
    ),
):
    if isinstance(message, ResultMessage):
        forked_id = message.session_id     # distinct de session_id

Deux faits sur le fork

Deux faits sur le fork sur lesquels les questions se jouent. Il se combine toujours à la reprise, puisqu'on forke une session existante, jamais à partir de rien. Et il branche l'historique de conversation, pas le système de fichiers : deux agents forkés qui modifient des fichiers dans le même répertoire modifient les mêmes fichiers.

Choisir entre les trois

Choisir entre les trois est la compétence que le guide teste :

La troisième ligne est le jugement du guide lui-même, et il est assez contre-intuitif pour être testé : démarrer une session neuve avec un résumé structuré est plus fiable que reprendre avec des résultats d'outils périmés. Une session reprise transporte des réponses enregistrées qui décrivent un système qui n'existe plus, et l'agent raisonne dessus comme si elles étaient à jour. Un résumé écrit emporte les conclusions qui ont survécu et laisse derrière les payloads morts.