Les sous-agents sont l'un des ajouts les plus utiles à l'écosystème Claude Code/Claude Agent : ils permettent de diviser des workflows complexes en équipes d'IA plus petites et spécialisées, de préserver le contexte du thread principal et de limiter l'accès aux outils en toute sécurité. Cet article explique quels sont les sous-agents, comment les créer et les invoquer (CLI, système de fichiers et SDK), le principes de conception vous devez suivre lors de leur construction, et exemple de code concret vous pouvez copier et adapter.
Que sont les sous-agents ?
A sous-agent Il s'agit d'un assistant IA préconfiguré et à portée restreinte, auquel Claude Code (ou le SDK Claude Agent) peut déléguer des tâches. Chaque sous-agent :
- A un nom unique et une description claire de l'objectif.
- Fonctionne dans son propre fenêtre de contexte séparé de la conversation principale (afin que les longues chaînes de détails ne polluent pas le contexte de l'orchestrateur).
- Peut être configuré avec un ensemble limité de les outils (lecture/écriture de fichiers, bash, grep, outils MCP, etc.), et avec un choix de modèle spécifique.
- Contient une invite système (la personnalité et les instructions du sous-agent) qui guide le comportement et les contraintes.
Ces propriétés rendent les sous-agents idéaux pour les tâches nécessitant beaucoup de jetons (recherche, recherche de gros journaux), sensibles à la sécurité (analyse ou outils potentiellement destructeurs) ou répétitives et bien spécifiées (vérification de style, exécution de tests).
Anthropic a été rapidement itéré : le Claude Code CLI et l'Agent SDK ont été refactorisés et étendus dans le Kit de développement logiciel Claude Agent, la prise en charge des plugins a été introduite pour le regroupement des agents et des personnalisations associées (commandes slash, serveurs MCP, hooks), et communication permettent de regrouper les workflows de domaine pour une réutilisation dans Claude.ai, Claude Code et le SDK Agent. Ces mises à jour simplifient partager, installer et versionner Sous-agents entre équipes et projets. Si vous envisagez de créer des workflows de production, vous devez évaluer le packaging des plugins et des compétences, ainsi que les modèles de déploiement basés sur le SDK.
Pourquoi les sous-agents sont importants
Trois raisons pour lesquelles ils sont immédiatement utiles :
- Préservation du contexte — Les recherches longues ou bruyantes, les tests ou les analyses sont intégrés à un sous-agent au lieu de submerger le contexte principal. Cela réduit le gaspillage de jetons et facilite l'analyse des résultats.
- Expertise spécialisée — vous pouvez encoder les connaissances et le comportement du domaine dans une invite système adaptée à la tâche (par exemple, un
security-auditorqui se concentre sur les secrets, les problèmes de dépendance et l'utilisation non sécurisée du shell). - Des autorisations plus sûres — limiter les outils par sous-agent réduit le rayon d'explosion (un examinateur de documents peut avoir des outils en lecture seule ; un exécuteur de tests a
Bashmais nonEdit). - Parallélisation : Vous pouvez lancer plusieurs sous-agents pour qu'ils s'exécutent simultanément (par exemple :
style-checker,security-scanner,test-runner) et collectent ensuite leurs brefs résultats — une énorme victoire pour les contrôles indépendants coûteux.
Prérequis pour l'utilisation des sous-agents dans Claude Code
Avant de commencer à créer des sous-agents, assurez-vous de disposer des éléments suivants :
1) Claude Code installé et authentifié
Installez la CLI Claude Code ou utilisez les intégrations Web/IDE. Documents de démarrage rapide et de configuration de CometAPI répertoriez les méthodes d'installation prises en charge (package global npm ou installateurs natifs) et montrez comment vérifier votre installation avec claude --version / claude doctor. Vous aurez également besoin d'un API Comet compte (l'utilisation de la clé CometAPI pour accéder au code Claude est moins chère et plus pratique que le modèle officiel.) comme indiqué dans le démarrage rapide.
2) Nœud / environnement (pour certains chemins d'installation) et outils shell de base
Si vous effectuez l'installation via le package npm, vous devriez disposer de Node.js (Node 18+ est courant dans les exemples). Si vous prévoyez d'utiliser le SDK Agent (JavaScript/TypeScript ou Python), vous aurez besoin d'un projet avec la dépendance SDK installée. De nombreux tutoriels supposent l'utilisation d'outils de développement standard (git, bash, etc.). gh CLI pour les workflows GitHub).
3) Présentation du projet & CLAUDE.md
La meilleure pratique consiste à conserver les documents d'aide au niveau du dépôt (CLAUDE.md) et de placer des agents à portée de projet .claude/agents/ Les coéquipiers en héritent donc. Les fichiers CLAUDE.md sont automatiquement intégrés au contexte de Claude et contribuent à harmoniser le comportement entre les sessions. Chaque sous-agent est un fichier Markdown avec une interface YAML. Exemple minimal :
---
name: code-reviewer
description: Expert code review specialist. Use PROACTIVELY after code changes to check security, style, and maintainability.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer. When invoked:
1. Run `git diff` to identify modified files.
2. Focus review on changed code paths.
3. List security issues, probable false positives, and suggested fixes.
4. Provide a short, prioritized action list.
Return results in JSON with fields: summary, issues.
nameest un identifiant en minuscules.descriptionguide l'invocation et la correspondance automatiques.toolsrestreint l'accès aux outils (omet d'hériter de tout).modelpeuvent êtresonnet,opus,haiku, ouinherit.
4) Autorisations et serveurs MCP (facultatif mais courant)
Si vos workflows utilisent des serveurs MCP (Model Context Protocol) ou des outils externes (Puppeteer, Sentry, outils REST personnalisés), assurez-vous que vos serveurs MCP sont configurés et accessibles. Pour les opérations sensibles (écriture, bash, commit Git), soyez vigilant quant à la liste blanche et à la répartition par agent. tools portée.
Comment créer des sous-agents dans Claude Code
Vous pouvez créer des sous-agents de trois manières principales : via la CLI interactive (/agents), sous forme de fichiers Markdown du système de fichiers, ou par programmation via le SDK Agent. Voici les options étape par étape :
Claude Code prend en charge trois manières pratiques de créer des sous-agents :
- CLI interactive
/agentsUI — le plus rapide pour la création itérative au sein d'une session. - Basé sur le système de fichiers — créer des fichiers Markdown avec frontmatter YAML dans
.claude/agents/(au niveau du projet) ou~/.claude/agents/(niveau utilisateur). Les agents de projet ont une priorité plus élevée. - Programmatique (Agent SDK) — définir des sous-agents dans le code via le
agentsparamètre lorsque vous appelezquery(); recommandé pour les applications pilotées par SDK. Cette approche est idéale lorsque des sous-agents doivent être créés dynamiquement ou intégrés à une application.
Flux interactif rapide (première étape recommandée)
- Démarrez Claude Code dans votre terminal ou ouvrez la palette de commandes dans VS Code.
- Exécutez l'interface des sous-agents avec la commande slash :
/agents
- Choisir Créer un nouvel agentChoisissez le périmètre au niveau du projet ou de l'utilisateur, renseignez le nom, la description, les outils et l'invite système, puis enregistrez. Vous pouvez générer un brouillon avec Claude, puis l'affiner. Une fois enregistré, l'agent est disponible dans
/agentset peut être invoqué explicitement ou automatiquement.
Sous-agents basés sur le système de fichiers (Markdown + frontmatter YAML)
Les sous-agents sont stockés sous forme de fichiers Markdown avec une page de garde YAML. Placez-les dans :
- Portée du projet:
.claude/agents/*.md(priorité la plus élevée) - Portée de l'utilisateur :
~/.claude/agents/*.md
Structure de base du fichier :
---
name: code-reviewer
description: "Review recent code changes for security and style."
tools: Read, Grep, Glob, Bash # optional; omit to inherit
model: sonnet # optional; or 'inherit'
---
You are a senior code reviewer with expertise in security, performance, and best practices.
When reviewing:
- Identify security vulnerabilities
- Prioritize clarity and maintainability
- Always provide concise examples and suggested fixes
- If unsure, ask for the minimal reproducible snippet
Quelques notes de mise en œuvre :
namedoit être en minuscules avec des tirets.- Omettre
toolspermettra au sous-agent d'hériter de tous les outils du thread principal ; lister explicitement les outils impose un modèle de moindre privilège. - Utilisez le
model: 'inherit'pour un comportement cohérent avec le thread principal, ou spécifiez un alias de modèle (par exemple,sonnet,opus,haiku).
Définition JSON CLI (utilisation ad hoc/session)
Vous pouvez définir des sous-agents temporaires en ligne lors du lancement d'une session :
claude --agents '{
"code-reviewer": {
"description": "Expert code reviewer.",
"prompt": "You are a senior code reviewer. Focus on security and best practices.",
"tools": ,
"model": "sonnet"
}
}'
Les agents définis par CLI sont utiles pour les exécutions scriptées ou les expériences ; ils ont une priorité inférieure à celle des agents de projet mais supérieure à celle des agents utilisateurs.
Définition programmatique (Agent SDK — recommandé pour les applications)
Si vous créez une application ou une automatisation, définissez les sous-agents par programmation via le SDK de l'agent agents Paramètre (option la plus intégrée). Exemple (TypeScript) :
import { query } from '@anthropic-ai/claude-agent-sdk';
async function runReview() {
const result = await query({
prompt: "Assess the authentication module for security issues",
options: {
agents: {
"code-reviewer": {
description: "Expert code review specialist",
prompt: `You are a code review specialist...`,
tools: ,
model: "sonnet"
},
"test-runner": {
description: "Runs the test suite and analyzes failures",
prompt: `You run tests and summarize failures...`,
tools: ,
model: "sonnet"
}
}
}
});
console.log(result);
}
Le SDK accepte également les agents basés sur le système de fichiers (il chargera .claude/agents/ fichiers) si vous préférez ce modèle. Les agents programmatiques sont puissants pour les workflows dynamiques et l'intégration CI.
Pour Python, le claude-agent-sdk le package prend en charge des modèles similaires : vous pouvez utiliser query() or ClaudeSDKClient et configurez les options, les outils et les serveurs MCP par programmation. Consultez le dépôt du SDK Python pour des exemples de démarrage rapide.
Comment invoquer des sous-agents
Délégation automatique
Claude Code peut automatiquement Choisissez un sous-agent lorsqu'une invite utilisateur correspond à son objectif. Ceci est utile pour l'orchestration en arrière-plan, où l'agent principal oriente automatiquement les tâches vers le bon spécialiste. Appuyez-vous sur des descriptions claires des sous-agents et des invites système ciblées pour améliorer la précision de la sélection automatique.
Invocation explicite (recommandée pour plus de clarté)
Vous pouvez invoquer explicitement un agent dans une conversation :
> Use the code-reviewer subagent to check my recent changes
L'invocation explicite est déterministe et recommandée pour les flux de production où vous souhaitez éviter une délégation inattendue.
Modèles d'orchestrateur SDK
Modèles courants dans les applications SDK :
- Fourcher + rassembler:Lancez plusieurs sous-agents en parallèle, collectez la réponse concise de chaque agent, puis résumez/fusionnez les résultats dans l'agent principal.
- Boucle de supervision:L'orchestrateur attribue des tâches aux sous-agents, inspecte les résultats et les accepte ou demande un recalcul/clarification.
- Exécution en bac à sable:Donnez des capacités potentiellement dangereuses (déployer, exécuter des scripts) à un agent étroitement contraint et exigez des crochets d'approbation humaine explicites avant l'exécution.
Ces modèles correspondent à des implémentations pratiques utilisant la gestion de session, les hooks et les outils MCP de l'Agent SDK.
Comment créer des sous-agents utiles, sûrs et composables
1) Responsabilité unique et consignes claires
Chaque sous-agent doit avoir un objectif clair et une invite système spécifiant les limites, les critères de réussite et le format de sortie. Si la sortie souhaitée est structurée (JSON, liste à puces, correctif de code), donnez des instructions précises au sous-agent afin de réduire les erreurs d'analyse.
2) Le moindre privilège pour les outils
Accorder uniquement les outils nécessaires à un sous-agent. Par exemple, un réviseur de documents n'en a pas besoin. Write or Bash. Utilisez le mode lecture seule par défaut lorsque cela est possible et augmentez explicitement les autorisations des outils si nécessaire. Cela réduit les risques et simplifie l'audit.
3) Renvoyer des sorties compactes et structurées
Les sous-agents doivent revenir réponses concises et définitives Plutôt que de longues traces de pensée. Un modèle courant consiste à effectuer un travail intensif dans le contexte du sous-agent, puis à renvoyer un bref résumé avec des pièces jointes (correctifs, références de fichiers, JSON). Cela optimise l'efficacité du contexte pour l'orchestrateur.
4) Testabilité et gestion des versions
Stockez les fichiers des sous-agents dans le système de gestion des versions, créez des tests d'intégration continue (CI) qui s'exécutent en conditions réelles sur de petites entrées et épinglez les modèles/ensembles d'outils. Si vous utilisez Skills et des plugins, adoptez les modèles de gestion des versions et de la place de marché des plugins pour gérer les mises à niveau et les retours en arrière.
5) Crochets d'audit et points de contrôle avec intervention humaine
Utilisez les hooks du SDK pour intercepter les appels d'outils (hooks PreToolUse) et exiger l'approbation humaine pour les actions destructives. Enregistrez tous les appels d'outils pour des audits rejouables. Le SDK fournit des mécanismes de hooks et d'autorisations pour prendre en charge ce modèle.
Exemple d'application — un petit pipeline de type production
Vous trouverez ci-dessous un exemple compact qui montre les éléments typiques : un agent de système de fichiers, une invocation SDK qui utilise deux agents (un pour la révision, un pour les tests) et une orchestration simple.
1) Agent du système de fichiers : .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Use PROACTIVELY after code changes. Perform security, style, and maintainability review on modified files.
tools: Read, Grep, Glob
model: inherit
---
You are a meticulous senior code reviewer. When invoked:
1. Run `git diff --name-only` to find modified files.
2. For each modified file, read and look for security issues, suspicious patterns, or maintainability problems.
3. Return JSON:
{
"summary": "one-line summary",
"issues": ,
"recommended_changes":
}
2) Orchestration programmatique (Node.js)
import { query } from '@anthropic-ai/claude-agent-sdk';
import fs from 'fs';
async function runPipeline() {
const result = query({
prompt: 'Run PR checks: security review then unit tests.',
options: {
agents: {
'code-reviewer': {
description: 'Use PROACTIVELY after code changes; output JSON with issues.',
prompt: fs.readFileSync('./.claude/agents/code-reviewer.md', 'utf8'),
tools: ,
model: 'sonnet'
},
'test-runner': {
description: 'Run test suite and summarize failing tests.',
prompt: `You are a test-runner. Execute tests and return JSON { summary, failing_tests[] }`,
tools:
}
}
}
});
for await (const message of result) {
// Implement streaming logic: messages may include subagent outputs
console.log(message);
}
}
runPipeline().catch(console.error);
Remarques : le code-reviewer est stocké dans le référentiel pour être réutilisé par l'équipe ; l'appel SDK démontre que les agents programmatiques ont la priorité et que tools la portée empêche les écritures accidentelles.
Sujets et modèles avancés
Configuration dynamique de l'agent
Créez des usines d'agents paramétrées qui choisissent le modèle et les ensembles d'outils en fonction de l'environnement (développement ou production) ou des niveaux de gravité (par exemple, strict vs balanced modes de sécurité). Les exemples du SDK montrent comment générer des définitions d'agent lors de l'exécution.
Parallélisation
Déployez plusieurs agents d'analyse en lecture seule en parallèle (style, sécurité, couverture des tests) et agrégez leurs sorties JSON dans le thread principal. Cela réduit considérablement le temps d'exécution des dépôts volumineux.
Agents fournis par le plugin
Les plugins peuvent fournir des sous-agents fournis avec le manifeste du plugin ; ils apparaissent dans /agents Aux côtés des agents personnalisés, ils peuvent être invoqués explicitement. Utilisez-le pour distribuer des agents standardisés entre les équipes.
Où utiliser Claude Code CLI est le plus recommandé
C'est avec plaisir que nous annonçons que CometAPI prend désormais entièrement en charge le puissant Claude Code CLI. Il vous suffit d'installer Claude Code et de vous authentifier avec la clé API Comet obtenue et l'adresse de base pour utiliser le modèle API Comet sur Claude Code.
Pourquoi utiliser le code claude via CometAPI ?
Principales fonctionnalités de l'intelligence artificielle : générez, déboguez et optimisez facilement le code à l'aide de modèles conçus spécifiquement pour les développeurs.
- Sélection de modèles flexible : notre gamme complète de modèles vous permet de développer de manière plus fluide.
- Intégration transparente : les API sont toujours disponibles. Intégrez Claude Code directement à votre workflow existant en quelques minutes.
- L'utilisation de Claude Code via CometAPI permettra de réduire davantage les coûtsL'API Claude fournie par CometAPI bénéficie d'une réduction de 20 % sur le prix officiel et est mise à jour avec le dernier modèle par l'officiel.
Prêt à utiliser Claude Code cli ? consultez le Guide de l'API pour des instructions détaillées.
Si vous souhaitez connaître plus de conseils, de guides et d'actualités sur l'IA, suivez-nous sur VK, X et Discord!
Voir aussi Comment installer et exécuter Claude Code via CometAPI ?
Réflexions finales
Traiter les sous-agents comme micro-personnages réutilisables et versionnésCommencez petit : faites un doc-reviewer et test-runner pour un dépôt, enregistrez-les dans .claude/agents/, et les automatiser dans CI en utilisant headless claude -p. Répétez vos invites, ajoutez des sorties structurées et renforcez les autorisations des outils.
Le modèle mental le plus efficace : imaginez Claude comme chef de projet et les sous-agents comme spécialistes de l'équipe. Le responsable délègue des tâches clairement formulées, agrège les livrables des spécialistes et rédige le rapport final. Au fil du temps, vous constaterez des améliorations en termes de fiabilité, de testabilité et de capacité à automatiser de larges pans des workflows des développeurs.