Sous-agents dans le SDK

Les sous-agents sont des instances d'agent séparées que votre agent principal peut créer pour gérer des sous-tâches ciblées. Utilisez les sous-agents pour isoler le contexte des sous-tâches ciblées, exécuter plusieurs analyses en parallèle et appliquer des instructions spécialisées sans surcharger l'invite du principal agent.

Ce guide explique comment définir et utiliser les sous-agents dans le SDK en utilisant le paramètre agents.

Aperçu

Vous pouvez créer des sous-agents de trois façons :

Par programmation : utilisez le paramètre agents dans vos options query() (TypeScript, Python)
Basé sur le système de fichiers : définissez les agents comme des fichiers markdown dans les répertoires .claude/agents/ (voir définir les sous-agents comme fichiers)
Général intégré : Claude peut invoquer le sous-agent general-purpose intégré à tout moment via l'outil Task sans que vous ayez besoin de rien définir

Ce guide se concentre sur l'approche programmatique, qui est recommandée pour les applications SDK.

Lorsque vous définissez des sous-agents, Claude décide s'il faut les invoquer en fonction du champ description de chaque sous-agent. Écrivez des descriptions claires qui expliquent quand le sous-agent doit être utilisé, et Claude déléguera automatiquement les tâches appropriées. Vous pouvez également demander explicitement un sous-agent par son nom dans votre invite (par exemple, « Utilisez l'agent code-reviewer pour... »).

Avantages de l'utilisation des sous-agents

Gestion du contexte

Les sous-agents maintiennent un contexte séparé de l'agent principal, ce qui prévient la surcharge d'informations et maintient les interactions ciblées. Cet isolement garantit que les tâches spécialisées ne polluent pas le contexte de la conversation principale 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, en retournant uniquement les conclusions pertinentes.

Parallélisation

Plusieurs sous-agents peuvent s'exécuter simultanément, accélérant considérablement les flux de travail complexes.

Exemple : lors d'une révision de code, vous pouvez exécuter les sous-agents style-checker, security-scanner et test-coverage simultanément, réduisant le temps de révision de minutes à secondes.

Instructions et connaissances spécialisées

Chaque sous-agent peut avoir des invites système personnalisé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 restauration et les vérifications d'intégrité des données qui seraient du bruit inutile dans les instructions du principal agent.

Restrictions d'outils

Les sous-agents peuvent être limités à des outils spécifiques, réduisant le risque d'actions involontaires.

Exemple : un sous-agent doc-reviewer pourrait n'avoir accès qu'aux outils Read et Grep, garantissant qu'il peut analyser mais ne peut jamais modifier accidentellement vos fichiers de documentation.

Création de sous-agents

Définition programmatique (recommandée)

Définissez les sous-agents directement dans votre code en utilisant le paramètre agents. Cet exemple crée deux sous-agents : un examinateur de code avec accès en lecture seule et un exécuteur de tests qui peut exécuter des commandes. L'outil Task doit être inclus dans allowedTools puisque Claude invoque les sous-agents via l'outil Task.

Configuration AgentDefinition

Champ	Type	Requis	Description
`description`	`string`	Oui	Description en langage naturel de quand utiliser cet agent
`prompt`	`string`	Oui	L'invite système de l'agent définissant son rôle et son comportement
`tools`	`string[]`	Non	Tableau des noms d'outils autorisés. S'il est omis, hérite de tous les outils
`model`	`'sonnet' \| 'opus' \| 'haiku' \| 'inherit'`	Non

Les sous-agents ne peuvent pas créer leurs propres sous-agents. N'incluez pas Task dans le tableau tools d'un sous-agent.

Définition basée sur le système de fichiers (alternative)

Vous pouvez également définir les sous-agents comme des fichiers markdown dans les répertoires .claude/agents/. Consultez la documentation des sous-agents Claude Code pour plus de détails sur cette approche. Les agents définis par programmation ont la priorité sur les agents basés sur le système de fichiers portant le même nom.

Même sans définir de sous-agents personnalisés, Claude peut créer le sous-agent general-purpose intégré lorsque Task est dans votre allowedTools. Ceci est utile pour déléguer des tâches de recherche ou d'exploration sans créer d'agents spécialisés.

Invocation des sous-agents

Invocation automatique

Claude décide automatiquement quand invoquer les sous-agents en fonction de la tâche et du champ description de chaque sous-agent. Par exemple, si vous définissez un sous-agent performance-optimizer avec la description « Spécialiste de l'optimisation des performances pour l'optimisation des requêtes », Claude l'invoquera lorsque votre invite mentionne l'optimisation des requêtes.

Écrivez des descriptions claires et spécifiques pour que Claude puisse faire correspondre les tâches au bon sous-agent.

Invocation explicite

Pour garantir que Claude utilise un sous-agent spécifique, mentionnez-le par son nom dans votre invite :

"Use the code-reviewer agent to check the authentication module"

Cela contourne la correspondance automatique et invoque directement le sous-agent nommé.

Configuration dynamique des agents

Vous pouvez créer des définitions d'agent dynamiquement en fonction des conditions d'exécution. Cet exemple crée un examinateur de sécurité avec différents niveaux de rigueur, en utilisant un modèle plus puissant pour les révisions strictes.

Détection de l'invocation des sous-agents

Les sous-agents sont invoqués via l'outil Task. Pour détecter quand un sous-agent est invoqué, recherchez les blocs tool_use avec name: "Task". Les messages provenant du contexte d'un sous-agent incluent un champ parent_tool_use_id.

Cet exemple itère à travers les messages en continu, enregistrant quand un sous-agent est invoqué et quand les messages suivants proviennent du contexte d'exécution de ce sous-agent.

La structure des messages diffère entre les SDK. En Python, les blocs de contenu sont accessibles directement via message.content. En TypeScript, SDKAssistantMessage enveloppe le message de l'API Claude, donc le contenu est accessible via message.message.content.

Reprise des sous-agents

Les sous-agents peuvent être repris pour continuer là où ils se sont arrêtés. Les sous-agents repris conservent leur historique de conversation complet, y compris tous les appels d'outils précédents, les résultats et le raisonnement. Le sous-agent reprend exactement où il s'est arrêté plutôt que de recommencer à zéro.

Lorsqu'un sous-agent se termine, Claude reçoit son ID d'agent dans le résultat de l'outil Task. Pour reprendre un sous-agent par programmation :

Capturez l'ID de session : Extrayez session_id des messages lors de la première requête
Extrayez l'ID d'agent : Analysez agentId à partir du contenu du message
Reprenez la session : Passez resume: sessionId dans les options de la deuxième requête, et incluez l'ID d'agent dans votre invite

Vous devez reprendre la même session pour accéder à la transcription du sous-agent. Chaque appel query() démarre une nouvelle session par défaut, donc passez resume: sessionId pour continuer dans la même session.

Si vous utilisez un agent personnalisé (pas un agent intégré), vous devez également passer la même définition d'agent dans le paramètre agents pour les deux requêtes.

L'exemple ci-dessous démontre ce flux : la première requête exécute un sous-agent et capture l'ID de session et l'ID d'agent, puis la deuxième requête reprend la session pour poser une question de suivi qui nécessite le contexte de la première analyse.

Les transcriptions des sous-agents persistent indépendamment de la conversation principale :

Compaction de la conversation principale : Lorsque la conversation principale se compacte, les transcriptions des sous-agents ne sont pas affectées. Elles sont stockées dans des fichiers séparés.
Persistance de la session : Les transcriptions des sous-agents persistent au sein de leur session. Vous pouvez reprendre un sous-agent après avoir redémarré Claude Code en reprenant la même session.
Nettoyage automatique : Les transcriptions sont nettoyées en fonction du paramètre cleanupPeriodDays (par défaut : 30 jours).

Restrictions d'outils

Les sous-agents peuvent avoir un accès aux outils restreint via le champ tools :

Omettez le champ : l'agent hérite de tous les outils disponibles (par défaut)
Spécifiez les outils : l'agent ne peut utiliser que les outils listés

Cet exemple crée un agent d'analyse en lecture seule qui peut examiner le code mais ne peut pas modifier les fichiers ou exécuter des commandes.

Combinaisons d'outils courantes

Cas d'usage	Outils	Description
Analyse en lecture seule	`Read`, `Grep`, `Glob`	Peut examiner le code mais pas modifier ou exécuter
Exécution de tests	`Bash`, `Read`, `Grep`	Peut exécuter des commandes et analyser la sortie
Modification de code	`Read`, `Edit`, `Write`, `Grep`, `Glob`	Accès complet en lecture/écriture sans exécution de commandes
Accès complet	Tous les outils

Dépannage

Claude ne délègue pas aux sous-agents

Si Claude complète les tâches directement au lieu de déléguer à votre sous-agent :

Incluez l'outil Task : les sous-agents sont invoqués via l'outil Task, donc il doit être dans allowedTools
Utilisez des invites explicites : mentionnez le sous-agent par son nom dans votre invite (par exemple, « Utilisez l'agent code-reviewer pour... »)
Écrivez une description claire : expliquez exactement quand le sous-agent doit être utilisé pour que Claude puisse faire correspondre les tâches de manière appropriée

Les agents basés sur le système de fichiers ne se chargent pas

Les agents définis dans .claude/agents/ sont chargés au démarrage uniquement. Si vous créez un nouveau fichier d'agent pendant que Claude Code s'exécute, redémarrez la session pour le charger.

Windows : échecs des invites longues

Sous Windows, les sous-agents avec des invites très longues peuvent échouer en raison des limites de longueur de ligne de commande (8191 caractères). Gardez les invites concises ou utilisez des agents basés sur le système de fichiers pour les instructions complexes.

Documentation connexe

Sous-agents Claude Code : documentation complète des sous-agents incluant les définitions basées sur le système de fichiers
Aperçu du SDK : prise en main du Claude Agent SDK

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="Review the authentication module for security issues",
        options=ClaudeAgentOptions(
            # Task tool is required for subagent invocation
            allowed_tools=["Read", "Grep", "Glob", "Task"],
            agents={
                "code-reviewer": AgentDefinition(
                    # description tells Claude when to use this subagent
                    description="Expert code review specialist. Use for quality, security, and maintainability reviews.",
                    # prompt defines the subagent's behavior and expertise
                    prompt="""You are a code review specialist with expertise in security, performance, and best practices.

When reviewing code:
- Identify security vulnerabilities
- Check for performance issues
- Verify adherence to coding standards
- Suggest specific improvements

Be thorough but concise in your feedback.""",
                    # tools restricts what the subagent can do (read-only here)
                    tools=["Read", "Grep", "Glob"],
                    # model overrides the default model for this subagent
                    model="sonnet"
                ),
                "test-runner": AgentDefinition(
                    description="Runs and analyzes test suites. Use for test execution and coverage analysis.",
                    prompt="""You are a test execution specialist. Run tests and provide clear analysis of results.

Focus on:
- Running test commands
- Analyzing test output
- Identifying failing tests
- Suggesting fixes for failures""",
                    # Bash access lets this subagent run test commands
                    tools=["Bash", "Read", "Grep"]
                )
            }
        )
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

# Factory function that returns an AgentDefinition
# This pattern lets you customize agents based on runtime conditions
def create_security_agent(security_level: str) -> AgentDefinition:
    is_strict = security_level == "strict"
    return AgentDefinition(
        description="Security code reviewer",
        # Customize the prompt based on strictness level
        prompt=f"You are a {'strict' if is_strict else 'balanced'} security reviewer...",
        tools=["Read", "Grep", "Glob"],
        # Key insight: use a more capable model for high-stakes reviews
        model="opus" if is_strict else "sonnet"
    )

async def main():
    # The agent is created at query time, so each request can use different settings
    async for message in query(
        prompt="Review this PR for security issues",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Grep", "Glob", "Task"],
            agents={
                # Call the factory with your desired configuration
                "security-reviewer": create_security_agent("strict")
            }
        )
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="Use the code-reviewer agent to review this codebase",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Task"],
            agents={
                "code-reviewer": AgentDefinition(
                    description="Expert code reviewer.",
                    prompt="Analyze code quality and suggest improvements.",
                    tools=["Read", "Glob", "Grep"]
                )
            }
        )
    ):
        # Check for subagent invocation in message content
        if hasattr(message, 'content') and message.content:
            for block in message.content:
                if getattr(block, 'type', None) == 'tool_use' and block.name == 'Task':
                    print(f"Subagent invoked: {block.input.get('subagent_type')}")

        # Check if this message is from within a subagent's context
        if hasattr(message, 'parent_tool_use_id') and message.parent_tool_use_id:
            print("  (running inside subagent)")

        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

import { query, type SDKMessage } from '@anthropic-ai/claude-agent-sdk';

// Helper to extract agentId from message content
// Stringify to avoid traversing different block types (TextBlock, ToolResultBlock, etc.)
function extractAgentId(message: SDKMessage): string | undefined {
  if (!('message' in message)) return undefined;
  // Stringify the content so we can search it without traversing nested blocks
  const content = JSON.stringify(message.message.content);
  const match = content.match(/agentId:\s*([a-f0-9-]+)/);
  return match?.[1];
}

let agentId: string | undefined;
let sessionId: string | undefined;

// First invocation - use the Explore agent to find API endpoints
for await (const message of query({
  prompt: "Use the Explore agent to find all API endpoints in this codebase",
  options: { allowedTools: ['Read', 'Grep', 'Glob', 'Task'] }
})) {
  // Capture session_id from ResultMessage (needed to resume this session)
  if ('session_id' in message) sessionId = message.session_id;
  // Search message content for the agentId (appears in Task tool results)
  const extractedId = extractAgentId(message);
  if (extractedId) agentId = extractedId;
  // Print the final result
  if ('result' in message) console.log(message.result);
}

// Second invocation - resume and ask follow-up
if (agentId && sessionId) {
  for await (const message of query({
    prompt: `Resume agent ${agentId} and list the top 3 most complex endpoints`,
    options: { allowedTools: ['Read', 'Grep', 'Glob', 'Task'], resume: sessionId }
  })) {
    if ('result' in message) console.log(message.result);
  }
}

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="Analyze the architecture of this codebase",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Grep", "Glob", "Task"],
            agents={
                "code-analyzer": AgentDefinition(
                    description="Static code analysis and architecture review",
                    prompt="""You are a code architecture analyst. Analyze code structure,
identify patterns, and suggest improvements without making changes.""",
                    # Read-only tools: no Edit, Write, or Bash access
                    tools=["Read", "Grep", "Glob"]
                )
            }
        )
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())