SpyBara
Go Premium

agent-sdk/subagents.md 2026-05-07 22:59 UTC to 2026-05-08 22:00 UTC

601 added, 0 removed.

2026
Sun 31 06:39 Sat 30 06:23 Fri 29 06:38 Thu 28 06:37 Wed 27 06:42 Tue 26 06:33 Sun 24 06:25 Sat 23 06:18 Fri 22 06:33 Thu 21 06:36 Wed 20 06:35 Tue 19 06:34 Mon 18 23:59 Sun 17 01:01 Fri 15 22:58 Thu 14 17:02 Wed 13 23:01 Tue 12 22:57 Mon 11 23:00 Sun 10 23:03 Sat 9 04:57 Fri 8 22:00 Thu 7 22:59 Tue 5 23:00 Mon 4 22:58 Sat 2 18:14 Fri 1 18:19

Sous-agents dans le SDK

Définissez et invoquez des sous-agents pour isoler le contexte, exécuter des tâches en parallèle et appliquer des instructions spécialisées dans vos applications Claude Agent SDK.

Les sous-agents sont des instances d'agent distinctes 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 Agent 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étermine 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

Isolation du contexte

Chaque sous-agent s'exécute dans sa propre conversation nouvelle. Les appels d'outils intermédiaires et les résultats restent à l'intérieur du sous-agent ; seul son message final revient au parent. Voir Ce que les sous-agents héritent pour savoir exactement ce qui se trouve dans le contexte du sous-agent.

Exemple : un sous-agent research-assistant peut explorer des dizaines de fichiers sans que le contenu de ces fichiers s'accumule dans la conversation principale. Le parent reçoit un résumé concis, pas chaque fichier que le sous-agent a lu.

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 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 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 Agent doit être inclus dans allowedTools puisque Claude invoque les sous-agents via l'outil Agent.

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(
# Agent tool is required for subagent invocation
allowed_tools=["Read", "Grep", "Glob", "Agent"],
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())

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
disallowedTools string[] Non Tableau des noms d'outils à supprimer de l'ensemble d'outils de l'agent
model string Non Remplacement du modèle pour cet agent. Accepte un alias tel que 'sonnet', 'opus', 'haiku', 'inherit', ou un ID de modèle complet. Par défaut le modèle principal s'il est omis
skills string[] Non Liste des noms de compétences à précharger dans le contexte de l'agent au démarrage. Les compétences non listées restent invocables via l'outil Skill
memory 'user' | 'project' | 'local' Non Source de mémoire pour cet agent
mcpServers (string | object)[] Non Serveurs MCP disponibles pour cet agent, par nom ou configuration en ligne
maxTurns number Non Nombre maximum de tours d'agent avant que l'agent s'arrête
background boolean Non Exécuter cet agent comme une tâche de fond non bloquante lorsqu'il est invoqué
effort 'low' | 'medium' | 'high' | 'xhigh' | 'max' | number Non Niveau d'effort de raisonnement pour cet agent
permissionMode PermissionMode Non Mode de permission pour l'exécution des outils au sein de cet agent

Dans le SDK Python, ces noms de champs utilisent camelCase pour correspondre au format de transmission. Voir la référence AgentDefinition pour plus de détails.

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/. Voir 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.

Ce que les sous-agents héritent

La fenêtre de contexte d'un sous-agent commence fraîche (pas de conversation parent) mais n'est pas vide. Le seul canal du parent au sous-agent est la chaîne d'invite de l'outil Agent, donc incluez tous les chemins de fichiers, messages d'erreur ou décisions dont le sous-agent a besoin directement dans cette invite.

Le sous-agent reçoit Le sous-agent ne reçoit pas
Sa propre invite système (AgentDefinition.prompt) et l'invite de l'outil Agent L'historique de conversation du parent ou les résultats des outils
Le CLAUDE.md du projet (chargé via settingSources) Le contenu des compétences préchargées, sauf s'il est listé dans AgentDefinition.skills
Les définitions d'outils (héritées du parent, ou le sous-ensemble dans tools) L'invite système du parent

Invocation des sous-agents

Invocation automatique

Claude décide automatiquement quand invoquer les sous-agents en fonction de la tâche et de la 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 d'agent dynamique

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.

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", "Agent"],
agents={
# Call the factory with your desired configuration
"security-reviewer": create_security_agent("strict")
},
),
):
if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

Détection de l'invocation de sous-agents

Les sous-agents sont invoqués via l'outil Agent. Pour détecter quand un sous-agent est invoqué, vérifiez les blocs tool_use où name est "Agent". 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.

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", "Agent"],
agents={
"code-reviewer": AgentDefinition(
description="Expert code reviewer.",
prompt="Analyze code quality and suggest improvements.",
tools=["Read", "Glob", "Grep"],
)
},
),
):
# Check for subagent invocation. Match both names: older SDK
# versions emitted "Task", current versions emit "Agent".
if hasattr(message, "content") and message.content:
for block in message.content:
if getattr(block, "type", None) == "tool_use" and block.name in (
"Task",
"Agent",
):
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())

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 là 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 Agent. Pour reprendre un sous-agent par programmation :

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

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.

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", "Agent"] }
})) {
// 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 Agent 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", "Agent"], resume: sessionId }
})) {
if ("result" in message) console.log(message.result);
}
}

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.

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", "Agent"],
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())

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 Hérite de tous les outils du parent (omettez le champ tools)

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 :

  1. Incluez l'outil Agent : les sous-agents sont invoqués via l'outil Agent, donc il doit être dans allowedTools
  2. Utilisez des invites explicites : mentionnez le sous-agent par son nom dans votre invite (par exemple, « Utilisez l'agent code-reviewer pour... »)
  3. É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 d'invite longue

Sur 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