Subagents, agent teams et Agent SDK

Claude Code propose quatre façons de faire travailler plusieurs agents : les subagents définis dans .claude/agents, les agent teams qui coordonnent plusieurs sessions en parallèle autour d'un lead, les background agents qui exécutent des sessions complètes en tâche de fond, et l'Agent SDK qui permet de construire vos propres agents par programmation. Ce guide explique quand utiliser chacun et comment les configurer.

Ces quatre mécanismes répondent à des besoins distincts. Les subagents préservent le contexte de votre conversation principale en isolant les sous-tâches. Les agent teams ajoutent la communication directe entre agents. Les background agents libèrent votre terminal. L'Agent SDK sort de Claude Code pour embarquer la même boucle agentique dans vos propres applications. Pour situer ces outils dans l'ensemble des extensions de Claude Code, consultez le guide des commandes personnalisées et skills.

Qu'est-ce qu'un subagent dans Claude Code ?

Un subagent est un assistant IA spécialisé qui traite un type de tâche précis. Chaque subagent s'exécute dans sa propre fenêtre de contexte, avec son propre system prompt, un accès aux outils spécifique et des permissions indépendantes. Quand Claude rencontre une tâche qui correspond à la description d'un subagent, il lui délègue le travail, et le subagent renvoie uniquement son résumé à la conversation principale.

Les subagents servent à plusieurs objectifs selon la documentation officielle :

• Préserver le contexte en gardant l'exploration et l'implémentation hors de votre conversation principale
• Imposer des contraintes en limitant les outils accessibles à un subagent
• Réutiliser des configurations entre projets avec des subagents au niveau utilisateur
• Spécialiser le comportement avec des system prompts ciblés
• Maîtriser les coûts en routant des tâches vers des modèles plus rapides comme Haiku

Claude Code inclut des subagents intégrés comme Explore, Plan et general-purpose. Explore est un agent en lecture seule sur le modèle Haiku, optimisé pour la recherche dans une base de code. Important : les subagents ne peuvent pas en lancer d'autres (pas d'imbrication).

À retenir : un subagent traite une sous-tâche dans son propre contexte et ne renvoie que son résumé. Il fonctionne dans une seule session.

Où vivent les subagents et quels champs de frontmatter utiliser ?

Les subagents sont des fichiers Markdown avec un frontmatter YAML. Vous les stockez à différents emplacements selon leur portée. Les subagents projet vivent dans .claude/agents/ (versionnés avec votre code), les subagents utilisateur dans ~/.claude/agents/. Claude Code scanne ces deux répertoires de manière récursive, donc vous pouvez les organiser en sous-dossiers comme agents/review/.

Voici un fichier subagent minimal, tel que présenté dans la documentation :

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Le corps du fichier devient le system prompt du subagent. Seuls name et description sont obligatoires. Les principaux champs de frontmatter sont :

D'autres champs existent : skills, mcpServers, hooks, memory, background, effort, isolation et color. Pour comprendre les modes de permission cités ici, consultez le guide permissions et sécurité. Les subagents sont chargés au démarrage de la session : si vous éditez un fichier directement sur le disque, redémarrez la session pour le prendre en compte.

À retenir : un subagent est un fichier .md dans .claude/agents/ (projet) ou ~/.claude/agents/ (utilisateur), avec un frontmatter dont seuls name et description sont requis.

Comment créer et gérer des subagents avec la commande /agents ?

La commande /agents ouvre une interface à onglets pour gérer vos subagents. Tapez la dans une session :

/agents

L'onglet Running affiche les subagents actifs et permet de les ouvrir ou de les arrêter. L'onglet Library permet de voir tous les subagents disponibles (intégrés, utilisateur, projet et plugin), d'en créer de nouveaux avec une configuration guidée ou une génération par Claude, d'éditer leur configuration et leurs accès aux outils, et de supprimer les subagents custom.

Pour créer un subagent, basculez sur l'onglet Library, sélectionnez Create new agent, puis choisissez Personal (enregistré dans ~/.claude/agents/) ou un emplacement projet. L'option Generate with Claude rédige pour vous l'identifiant, la description et le system prompt à partir d'une simple description en langage naturel. Les subagents créés via l'interface /agents sont disponibles immédiatement, sans redémarrage.

Vous pouvez aussi définir des subagents à la volée pour une seule session avec le flag --agents, qui accepte du JSON avec les mêmes champs que le frontmatter :

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

Une fois le subagent défini, invoquez-le simplement en le nommant dans votre prompt :

Use the code-reviewer agent to review this project

À retenir : /agents est la méthode recommandée pour créer et gérer vos subagents. Le flag --agents permet d'en définir à la volée en JSON pour une session.

Comment fonctionnent les agent teams et le rôle du lead ?

Les agent teams coordonnent plusieurs instances de Claude Code qui travaillent ensemble. Une session joue le rôle de lead : elle crée l'équipe, fait apparaître les coéquipiers, assigne les tâches et synthétise les résultats. Contrairement aux subagents qui ne renvoient leurs résultats qu'à l'agent principal, les coéquipiers d'une team communiquent directement entre eux et vous pouvez interagir avec chacun individuellement.

Les agent teams sont expérimentales et désactivées par défaut. Activez-les en réglant la variable d'environnement CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS sur 1, directement dans votre shell ou via settings.json :

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Une fois activées, demandez simplement à Claude de créer une équipe en décrivant la tâche et la structure souhaitée en langage naturel :

Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

Une agent team se compose de quatre éléments : le team lead (la session principale qui coordonne), les teammates (instances Claude Code séparées, chacune dans sa propre fenêtre de contexte), une task list partagée (les coéquipiers réclament et complètent les tâches) et une mailbox (système de messagerie entre agents). Le lead peut assigner explicitement une tâche, ou un coéquipier peut s'auto-attribuer la prochaine tâche libre et débloquée.

La documentation recommande de commencer avec 3 à 5 coéquipiers pour la plupart des workflows, car les coûts en tokens augmentent linéairement avec le nombre d'agents actifs. Vous pouvez réutiliser une définition de subagent comme rôle de coéquipier en mentionnant son nom au lead. Pour les configurations multi-agents avancées, voyez les best practices avancées de Claude Code.

À retenir : une agent team fait travailler plusieurs sessions en parallèle autour d'un lead, avec communication directe entre coéquipiers. La fonctionnalité est expérimentale et s'active via CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.

Que sont les background agents et la commande claude agents ?

Les background agents (agent view) permettent de piloter plusieurs sessions Claude Code complètes depuis un seul écran. Ouvrez l'agent view depuis votre shell :

claude agents

Cet écran liste toutes vos sessions en tâche de fond : ce qui tourne, ce qui attend votre intervention et ce qui est terminé. Chaque session en tâche de fond est une conversation Claude Code complète qui continue de tourner sans terminal attaché, donc vous pouvez l'ouvrir, répondre, puis repartir quand vous voulez.

Le fonctionnement est simple. Tapez un prompt et appuyez sur Entrée : une nouvelle session démarre sur cette tâche et apparaît sous forme de ligne. Chaque prompt lance sa propre session, ce qui vous permet d'en exécuter plusieurs en parallèle. Sélectionnez une ligne et appuyez sur Espace pour ouvrir le panneau d'aperçu (peek), qui montre la dernière sortie de la session ou la question en attente. Appuyez sur Entrée ou → pour vous attacher à la conversation complète, et sur ← pour vous détacher et revenir au tableau.

Les sessions sont regroupées par état : Working, Needs input, Idle, Completed, Failed et Stopped. Un processus superviseur séparé exécute ces sessions, ce qui leur permet de continuer même après la fermeture de l'agent view ou du shell. Pour basculer une session interactive déjà ouverte vers l'arrière-plan, lancez /bg à l'intérieur de celle-ci.

À retenir : claude agents ouvre un écran unique pour dispatcher et surveiller plusieurs sessions complètes en parallèle, qui continuent de tourner sans terminal attaché.

Comment construire ses propres agents avec l'Agent SDK ?

L'Agent SDK donne accès aux mêmes outils, à la même boucle agentique et à la même gestion de contexte que Claude Code, programmables en Python et TypeScript. Vous construisez ainsi des agents qui lisent des fichiers, exécutent des commandes, cherchent sur le web et éditent du code, le tout dans votre propre application.

Installez le SDK selon votre langage :

# TypeScript
npm install @anthropic-ai/claude-agent-sdk

# Python (3.10 ou plus récent)
pip install claude-agent-sdk

Définissez ensuite votre clé API et lancez un premier agent. Voici l'exemple TypeScript de la documentation officielle :

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Find and fix the bug in auth.ts",
  options: { allowedTools: ["Read", "Edit", "Bash"] }
})) {
  console.log(message); // Claude lit le fichier, trouve le bug, l'édite
}

Et l'équivalent Python :

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Find and fix the bug in auth.py",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
    ):
        print(message)


asyncio.run(main())

Le SDK embarque des outils intégrés (Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch et d'autres), donc votre agent travaille immédiatement sans que vous ayez à implémenter l'exécution des outils. Il supporte aussi les hooks, les subagents (via le champ agents et l'outil Agent), les serveurs MCP, le contrôle des permissions et les sessions résumables. Il charge également la configuration filesystem de Claude Code : skills, commandes et CLAUDE.md. Pour brancher des outils externes, voyez le guide MCP (Model Context Protocol), et pour l'usage en CI/CD, le guide mode headless et CI/CD.

À retenir : l'Agent SDK embarque la boucle agentique de Claude Code dans vos applications Python ou TypeScript, avec exécution des outils déjà gérée.

Subagents, agent teams, background agents ou Agent SDK : lequel choisir ?

Ces quatre approches se complètent. Le tableau suivant résume les distinctions clés issues de la documentation officielle :

Les subagents et les agent teams parallélisent tous deux le travail, mais diffèrent sur la communication : les subagents ne renvoient leurs résultats qu'à l'agent principal et ne se parlent pas, alors que les coéquipiers d'une team partagent une task list et communiquent directement. Choisissez selon que vos travailleurs ont besoin de se coordonner ou non.

Pour enseigner vos conventions à tous ces agents, le fichier CLAUDE.md reste central : les coéquipiers et subagents le lisent à leur démarrage. Consultez le guide du système de mémoire CLAUDE.md pour structurer ces instructions.

Pour maîtriser l'orchestration multi-agents en conditions réelles, la formation Claude Code de SFEIR propose une journée de labs pratiques. La formation Développeur Augmenté par l'IA approfondit l'usage des subagents et de l'Agent SDK dans des architectures de production.

À retenir : choisissez les subagents pour des tâches focalisées, les agent teams pour la coordination, les background agents pour le parallélisme non surveillé, et l'Agent SDK pour des agents custom en production.

---