Quand un agent Claude doit accomplir une tâche complexe — analyser un code, écrire de la documentation, lancer des tests, et déployer — tenter de tout faire dans un seul agent monolithique mène à une perte de contexte, à des décisions confuses et à un coût en tokens explosé. La solution : utiliser des sub-agents. Chaque sub-agent est spécialisé, a son propre system prompt, ses propres outils, son propre contexte mémoire. Le Claude Agent SDK supporte ce pattern nativement et c’est l’une des clés pour construire des agents complexes vraiment efficaces. Voici le tutoriel pratique.

Ce tutoriel s’inscrit dans notre série Claude Agent SDK. Pour les bases, voir notre guide complet Claude Agent SDK 2026.

Pourquoi des sub-agents ?

Contexte protégé : un sub-agent qui lit 50 fichiers ne pollue pas le contexte de l’agent principal. Quand il termine, seule sa synthèse remonte.
Spécialisation : chaque sub-agent a un system prompt, des outils et des règles taillés pour sa tâche. Plus ciblé que prompt généraliste.
Économie : utiliser Sonnet pour l’agent principal et Haiku pour les sub-agents (recherche, formatage, summarisation) divise le coût par 3-5x.
Parallélisation : plusieurs sub-agents peuvent tourner en parallèle pour accélérer (ex : 5 recherches simultanées au lieu de séquentielles).
Réutilisabilité : un sub-agent bien défini peut être appelé par différents agents principaux.

Quand utiliser des sub-agents (et quand pas)

Bon cas : recherche large dans un codebase, analyse multi-fichiers, audit indépendant pour un second avis, exécution de tâches parallélisables, validation par un agent neutre
Mauvais cas : action courte (1-2 tool calls suffisent), tâche qui nécessite de garder le contexte de l’agent principal, action où la latence supplémentaire d’un sub-agent ralentit l’utilisateur

Règle pratique : déléguez à un sub-agent si la tâche peut prendre plus de 3-5 tool calls et si vous n’avez besoin que d’un résumé final.

Prérequis

Bun ou Node 20+, clef API Anthropic
Connaissance du Claude Agent SDK (voir le pilier)
TypeScript intermédiaire
Niveau attendu : avancé
Temps : 2 heures

Étape 1 — Définir des sub-agents avec settings.json

La méthode la plus simple : créer des fichiers de définition d’agents dans le dossier .claude/agents/ de votre projet, ou globalement dans ~/.claude/agents/. Chaque sub-agent est décrit en frontmatter Markdown :

# .claude/agents/code-explorer.md
---
name: code-explorer
description: Explore le codebase pour répondre aux questions architecturales et trouver des fonctions, classes ou patterns. Utiliser pour les recherches longues qui ne nécessitent pas de modifier le code.
tools: [Glob, Grep, Read]
model: claude-haiku-4-5
---

Tu es un agent spécialisé dans l'exploration de codebases.

Ton rôle est de répondre rapidement et précisément aux questions sur la structure d'un code : où est définie telle fonction, comment est utilisée telle classe, quel pattern est suivi.

Règles :
- Utilise Glob et Grep en parallèle pour aller vite
- Ne lis un fichier complet que si nécessaire
- Réponds par une synthèse courte (200-500 mots) avec les chemins exacts file:line
- Ne modifie jamais aucun fichier

Le frontmatter définit : name (slug), description (utilisée par l’agent principal pour décider quand déléguer), tools (whitelist des outils accessibles), model (Haiku pour économiser, Sonnet/Opus pour qualité).

Étape 2 — Plusieurs sub-agents complémentaires

# .claude/agents/test-runner.md
---
name: test-runner
description: Lance les tests du projet et analyse les échecs. Utiliser après une modification de code pour valider qu'on n'a rien cassé.
tools: [Bash, Read, Grep]
model: claude-sonnet-4-6
---

Tu lances les tests du projet et analyses les résultats.

Workflow :
1. Détecte le test runner (bun test, jest, vitest, pytest)
2. Lance les tests avec verbose minimal
3. Si échecs : lis les fichiers concernés pour comprendre, propose la correction (ne l'applique pas)
4. Synthèse finale : nombre de tests passés/échoués, liste des fichiers à corriger

# .claude/agents/security-reviewer.md
---
name: security-reviewer
description: Audit de sécurité indépendant d'un code modifié. Utiliser avant chaque PR pour second avis.
tools: [Read, Grep, Glob]
model: claude-sonnet-4-6
---

Tu fais un audit de sécurité strict du code fourni.

Vérifie :
- Injections SQL (requêtes concaténées sans paramètres)
- XSS (HTML non échappé)
- Secrets en clair (clefs, tokens)
- Validation manquante d'entrée utilisateur
- Auth/permissions oubliées sur les routes sensibles
- CSRF, headers sécurité

Verdict : OK / WARN / CRITIQUE avec ligne file:line pour chaque problème.

Étape 3 — Invoquer un sub-agent depuis un agent principal

L’agent principal voit l’outil Agent qui permet de déléguer à un sub-agent par son nom. Exemple de prompt côté utilisateur :

"Analyse le module auth.ts puis lance les tests avec un sub-agent dédié.
Si tout est vert, demande au security-reviewer un second avis avant que je merge."

L’agent principal va :

Lire auth.ts (lui-même, dans son contexte)
Invoquer le sub-agent test-runner via l’outil Agent → un nouveau contexte démarre, lance les tests, retourne uniquement la synthèse
Si OK, invoquer security-reviewer avec le code en question
Synthétiser le tout à l’utilisateur

Critique : entre les sub-agents, l’agent principal ne voit JAMAIS les détails de leur travail interne. Il reçoit seulement la dernière réponse de chaque sub-agent. Ça protège son contexte et garde le flow lisible.

Étape 4 — Sub-agents en parallèle

Pour des tâches indépendantes, vous pouvez lancer plusieurs sub-agents en parallèle dans le même message :

"Lance en parallèle :
- code-explorer pour identifier toutes les routes API du projet
- code-explorer pour identifier les tables Postgres utilisées
- security-reviewer sur le module billing.ts"

L’agent principal envoie 3 appels Agent simultanés. Latence totale = max(t1, t2, t3) au lieu de t1+t2+t3. Sur un projet typique, ça divise par 2-3 le temps total.

Étape 5 — Sub-agents via le SDK programmatique

Pour invoquer des sub-agents directement depuis du code (sans passer par l’interactivité Claude Code), vous pouvez créer plusieurs query() imbriquées :

// src/orchestrator.ts
import { query } from "@anthropic-ai/claude-agent-sdk";

async function runSubAgent(name: string, task: string): Promise<string> {
  const subAgentPrompts: Record<string, string> = {
    explorer: "Tu es un explorateur de code. Réponds court et précis avec les chemins file:line.",
    reviewer: "Tu fais un audit de sécurité strict. Verdict OK/WARN/CRITIQUE.",
  };

  const result = query({
    prompt: task,
    options: {
      systemPrompt: subAgentPrompts[name],
      model: name === "explorer" ? "claude-haiku-4-5" : "claude-sonnet-4-6",
      maxTurns: 8,
    },
  });

  let summary = "";
  for await (const msg of result) {
    if (msg.type === "assistant_text") summary += msg.text;
  }
  return summary;
}

// Orchestration : 3 sub-agents en parallèle
const [routes, tables, audit] = await Promise.all([
  runSubAgent("explorer", "Trouve toutes les routes API du projet"),
  runSubAgent("explorer", "Liste les tables Postgres référencées"),
  runSubAgent("reviewer", "Audit billing.ts"),
]);

console.log({ routes, tables, audit });

Étape 6 — Coordination par un agent superviseur

Pour les workflows complexes, un agent « superviseur » (Sonnet ou Opus) orchestre plusieurs sub-agents (Haiku) :

// Superviseur : Sonnet, planifie et synthétise
const supervisor = query({
  prompt: "Génère un rapport mensuel de l'activité commerciale",
  options: {
    systemPrompt: `Tu es un superviseur. Délègue les tâches à des sub-agents spécialisés :
    - data-fetcher : récupère les données via MCP CRM
    - chart-generator : produit les graphiques en SVG
    - writer : rédige la synthèse en français professionnel

    Tu coordonnes et synthétises. Tu n'exécutes pas toi-même.`,
    model: "claude-sonnet-4-6",
    // Le SDK propage automatiquement le contexte aux sub-agents définis dans .claude/agents/
  },
});

Étape 7 — Patterns avancés

Map-reduce : 1 superviseur (map) délègue à N sub-agents identiques sur chunks différents, puis les résultats sont regroupés (reduce)
Chain of refinement : sub-agent 1 produit un draft, sub-agent 2 critique, sub-agent 3 reformule
Voting : 3 sub-agents font la même analyse en parallèle, l’agent principal choisit le consensus
Specialist routing : un sub-agent « router » lit la question et la dispatche au bon expert (DB / front / sécu)

Coûts comparés

Hypothèse : tâche complexe nécessitant 30 tool calls. Si l’agent principal Sonnet fait tout seul, ~150K tokens cumulés (contexte qui grossit) → ~0.50 USD. Si 3 sub-agents Haiku font le travail détaillé et que Sonnet synthétise (~30K tokens chacun), total ~0.15 USD. Économie ~65 %.

Adaptation Afrique de l’Ouest

Pour un usage agence/PME, l’orchestration sub-agents permet de bâtir des agents puissants (audit complet de site, génération de rapport mensuel) à coût contenu. À 0.15 USD par exécution complète, vous pouvez lancer 100 audits par mois pour 15 USD, soit ~9 000 FCFA — bien moins que le coût d’un junior dédié.

Erreurs fréquentes

Erreur	Cause	Solution
Agent principal ne délègue jamais	Description du sub-agent vague	Réécrire la description avec verbe d’action et « Utiliser pour… »
Sub-agent perd du temps en idle	maxTurns trop élevé	5-8 maxTurns pour sub-agents Haiku
Latence cumulée si séquentiel	Sub-agents lancés un par un	Promise.all pour les indépendants
Sub-agent voit pas ses outils	tools: [] non spécifié	Whitelister explicitement les outils
Coût explose	Tous en Sonnet	Haiku par défaut, Sonnet uniquement si raisonnement complexe

Pour aller plus loin

Guide complet Claude Agent SDK 2026
Construire un agent custom
MCP server custom métier
Hooks et permissions
Documentation officielle : docs.anthropic.com/en/api/agent-sdk

Sub-agents et orchestration Claude : tutoriel pratique 2026

Pourquoi des sub-agents ?

Quand utiliser des sub-agents (et quand pas)

Prérequis

Étape 1 — Définir des sub-agents avec settings.json

Étape 2 — Plusieurs sub-agents complémentaires

Étape 3 — Invoquer un sub-agent depuis un agent principal

Étape 4 — Sub-agents en parallèle

Étape 5 — Sub-agents via le SDK programmatique

Étape 6 — Coordination par un agent superviseur

Étape 7 — Patterns avancés

Coûts comparés

Adaptation Afrique de l’Ouest

Erreurs fréquentes

Pour aller plus loin

Confiez-nous la Création de Votre Site Web

Pourquoi des sub-agents ?

Quand utiliser des sub-agents (et quand pas)

Prérequis

Étape 1 — Définir des sub-agents avec settings.json

Étape 2 — Plusieurs sub-agents complémentaires

Étape 3 — Invoquer un sub-agent depuis un agent principal

Étape 4 — Sub-agents en parallèle

Étape 5 — Sub-agents via le SDK programmatique

Étape 6 — Coordination par un agent superviseur

Étape 7 — Patterns avancés

Coûts comparés

Adaptation Afrique de l’Ouest

Erreurs fréquentes

Pour aller plus loin

Confiez-nous la Création de Votre Site Web

Articles Similaires

Dashboard agritech avec Grafana et SvelteKit : tutoriel 2026

MCP server custom métier : tutoriel complet 2026

PostgreSQL pgvector pour RAG IA : tutoriel 2026