Les sous-agents dans le SDK Claude Code sont des IA spécialisées qui sont orchestrées par l’agent principal. Utilisez les sous-agents pour la gestion du contexte et la parallélisation. Ce guide explique comment les applications SDK interagissent avec et utilisent les sous-agents qui sont créés via des fichiers markdown.

​
Aperçu

Les sous-agents sont créés exclusivement par l’approche basée sur le système de fichiers en plaçant des fichiers markdown avec un frontmatter YAML dans des répertoires désignés. Le SDK peut ensuite invoquer ces sous-agents prédéfinis pendant l’exécution.

​
Avantages de l’utilisation des sous-agents

​
Gestion du contexte

Les sous-agents maintiennent un contexte séparé de l’agent principal, empêchant la surcharge d’informations et gardant les interactions focalisées. Cette isolation garantit que les tâches spécialisées ne polluent pas le contexte de conversation principal avec des détails non pertinents. Exemple : Un sous-agent research-assistant peut explorer des dizaines de fichiers et de pages de documentation sans encombrer la conversation principale avec tous les résultats de recherche intermédiaires - ne retournant que les découvertes pertinentes.

​
Parallélisation

Plusieurs sous-agents peuvent fonctionner simultanément, accélérant considérablement les flux de travail complexes. Exemple : Pendant une revue de code, vous pouvez exécuter les sous-agents style-checker, security-scanner, et test-coverage simultanément, réduisant le temps de revue de minutes à secondes.

​
Instructions et connaissances spécialisées

Chaque sous-agent peut avoir des invites système adaptées avec une expertise spécifique, des meilleures pratiques et des contraintes. Exemple : Un sous-agent database-migration peut avoir des connaissances détaillées sur les meilleures pratiques SQL, les stratégies de rollback et les vérifications d’intégrité des données qui seraient du bruit inutile dans les instructions de l’agent principal.

​
Restrictions d’outils

Les sous-agents peuvent être limités à des outils spécifiques, réduisant le risque d’actions non intentionnelles. Exemple : Un sous-agent doc-reviewer pourrait n’avoir accès qu’aux outils Read et Grep, garantissant qu’il peut analyser mais ne jamais modifier accidentellement vos fichiers de documentation.

​
Création de sous-agents

Les sous-agents sont définis comme des fichiers markdown dans des répertoires spécifiques :
  • Niveau projet : .claude/agents/*.md - Disponible uniquement dans le projet actuel
  • Niveau utilisateur : ~/.claude/agents/*.md - Disponible dans tous les projets

​
Format de fichier

Chaque sous-agent est un fichier markdown avec un frontmatter YAML : 
---
name: code-reviewer
description: Spécialiste expert en revue de code. Utiliser pour les revues de qualité, sécurité et maintenabilité.
tools: Read, Grep, Glob, Bash  # Optionnel - hérite de tous les outils si omis
---

L'invite système de votre sous-agent va ici. Cela définit le rôle du sous-agent,
ses capacités et son approche pour résoudre les problèmes.

Incluez des instructions spécifiques, des meilleures pratiques et toutes les contraintes
que le sous-agent devrait suivre.

​
Champs de configuration

ChampRequisDescription
nameOuiIdentifiant unique utilisant des lettres minuscules et des tirets
descriptionOuiDescription en langage naturel de quand utiliser ce sous-agent
toolsNonListe séparée par des virgules des outils autorisés. Si omis, hérite de tous les outils

​
Comment le SDK utilise les sous-agents

Lors de l’utilisation du SDK Claude Code, les sous-agents définis dans le système de fichiers sont automatiquement disponibles. Claude Code va :
  1. Auto-détecter les sous-agents depuis les répertoires .claude/agents/
  2. Les invoquer automatiquement basé sur la correspondance des tâches
  3. Utiliser leurs invites spécialisées et restrictions d’outils
  4. Maintenir un contexte séparé pour chaque invocation de sous-agent
Le SDK respecte la configuration du système de fichiers - il n’y a pas de moyen programmatique de créer des sous-agents à l’exécution. Tous les sous-agents doivent être définis comme fichiers avant l’exécution du SDK.

​
Exemples de sous-agents

Pour des exemples complets de sous-agents incluant des réviseurs de code, des exécuteurs de tests, des débogueurs et des auditeurs de sécurité, voir le guide principal des Sous-agents. Le guide inclut des configurations détaillées et des meilleures pratiques pour créer des sous-agents efficaces.

​
Modèles d’intégration SDK

​
Invocation automatique

Le SDK invoquera automatiquement les sous-agents appropriés basé sur le contexte de la tâche. Assurez-vous que le champ description de votre sous-agent indique clairement quand il devrait être utilisé : 
---
name: performance-optimizer
description: Utiliser PROACTIVEMENT quand les changements de code pourraient impacter les performances. DOIT ÊTRE UTILISÉ pour les tâches d'optimisation.
tools: Read, Edit, Bash, Grep
---

​
Invocation explicite

Les utilisateurs peuvent demander des sous-agents spécifiques dans leurs invites : 
// Lors de l'utilisation du SDK, les utilisateurs peuvent explicitement demander des sous-agents :
const result = await query({
  prompt: "Utilise le sous-agent code-reviewer pour vérifier le module d'authentification"
});

​
Restrictions d’outils

Les sous-agents peuvent avoir un accès restreint aux outils via le champ tools :
  • Omettre le champ - Le sous-agent hérite de tous les outils disponibles (par défaut)
  • Spécifier les outils - Le sous-agent ne peut utiliser que les outils listés
Exemple d’un sous-agent d’analyse en lecture seule : 
---
name: code-analyzer
description: Analyse statique de code et revue d'architecture
tools: Read, Grep, Glob  # Pas de permissions d'écriture ou d'exécution
---

Vous êtes un analyste d'architecture de code. Analysez la structure du code,
identifiez les modèles et suggérez des améliorations sans faire de changements.

​
Documentation connexe