Passer au contenu principal
Le SDK Agent est construit sur la même base que Claude Code, ce qui signifie que vos agents SDK ont accès aux mêmes fonctionnalités basées sur le système de fichiers : instructions de projet (CLAUDE.md et règles), compétences, hooks, et bien plus. Lorsque vous omettez settingSources, query() lit les mêmes paramètres du système de fichiers que l’interface de ligne de commande Claude Code : paramètres utilisateur, projet et locaux, fichiers CLAUDE.md, et compétences, agents et commandes .claude/. Pour fonctionner sans ces éléments, passez settingSources: [], ce qui limite l’agent à ce que vous configurez par programmation. Les paramètres de politique gérée et la configuration globale ~/.claude.json sont lus indépendamment de cette option. Voir Ce que settingSources ne contrôle pas. Pour une vue d’ensemble conceptuelle de ce que chaque fonctionnalité fait et quand l’utiliser, voir Étendre Claude Code.

Contrôler les paramètres du système de fichiers avec settingSources

L’option des sources de paramètres (setting_sources en Python, settingSources en TypeScript) contrôle quels paramètres basés sur le système de fichiers le SDK charge. Passez une liste explicite pour accepter des sources spécifiques, ou passez un tableau vide pour désactiver les paramètres utilisateur, projet et locaux. Cet exemple charge à la fois les paramètres au niveau utilisateur et au niveau projet en définissant settingSources sur ["user", "project"] :
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async for message in query(
    prompt="Help me refactor the auth module",
    options=ClaudeAgentOptions(
        # "user" loads from ~/.claude/, "project" loads from ./.claude/ in cwd.
        # Together they give the agent access to CLAUDE.md, skills, hooks, and
        # permissions from both locations.
        setting_sources=["user", "project"],
        allowed_tools=["Read", "Edit", "Bash"],
    ),
):
    if isinstance(message, AssistantMessage):
        for block in message.content:
            if hasattr(block, "text"):
                print(block.text)
    if isinstance(message, ResultMessage) and message.subtype == "success":
        print(f"\nResult: {message.result}")
Chaque source charge les paramètres à partir d’un emplacement spécifique, où <cwd> est le répertoire de travail que vous passez via l’option cwd, ou le répertoire courant du processus s’il n’est pas défini. Pour la définition de type complète, voir SettingSource (TypeScript) ou SettingSource (Python).
SourceCe qu’elle chargeEmplacement
"project"CLAUDE.md du projet, .claude/rules/*.md, compétences du projet, hooks du projet, settings.json du projet<cwd>/.claude/ pour settings.json et hooks ; <cwd> et chaque répertoire parent pour CLAUDE.md et rules ; <cwd> et chaque répertoire parent jusqu’à la racine du dépôt pour les compétences
"user"CLAUDE.md utilisateur, ~/.claude/rules/*.md, compétences utilisateur, paramètres utilisateur~/.claude/
"local"CLAUDE.local.md, .claude/settings.local.json<cwd>/.claude/ pour settings.local.json ; <cwd> et chaque répertoire parent pour CLAUDE.local.md
Omettre settingSources équivaut à ["user", "project", "local"]. L’option cwd détermine où le SDK recherche les entrées au niveau du projet. CLAUDE.md et les rules se chargent à partir de <cwd> et de chaque répertoire parent. Les compétences se chargent à partir de <cwd> et de chaque répertoire parent jusqu’à la racine du dépôt. Le settings.json du projet et les hooks se chargent uniquement à partir de <cwd>/.claude/ sans secours au répertoire parent.

Ce que settingSources ne contrôle pas

settingSources couvre les paramètres utilisateur, projet et locaux. Quelques entrées sont lues indépendamment de sa valeur :
EntréeComportementPour désactiver
Paramètres de politique géréeToujours chargés quand présents sur l’hôteSupprimez le fichier de paramètres gérés
Configuration globale ~/.claude.jsonToujours lueRelocalisez avec CLAUDE_CONFIG_DIR dans env
Mémoire automatique à ~/.claude/projects/<project>/memory/Chargée par défaut dans l’invite systèmeDéfinissez autoMemoryEnabled: false dans les paramètres, ou CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 dans env
Connecteurs MCP de claude.aiChargés quand la méthode d’authentification active est un abonnement claude.ai. Passer mcpServers: {} ne les supprime pasDéfinissez strictMcpConfig: true, ou ENABLE_CLAUDEAI_MCP_SERVERS=false dans env
Ne vous fiez pas aux options par défaut de query() pour l’isolation multi-locataire. Parce que les entrées ci-dessus sont lues indépendamment de settingSources, un processus SDK peut récupérer la configuration au niveau de l’hôte et la mémoire par répertoire. Pour les déploiements multi-locataires, exécutez chaque locataire dans son propre système de fichiers et définissez settingSources: [] plus CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 dans env. Voir Déploiement sécurisé.

Instructions de projet (CLAUDE.md et règles)

Les fichiers CLAUDE.md et les fichiers .claude/rules/*.md donnent à votre agent un contexte persistant sur votre projet : conventions de codage, commandes de construction, décisions architecturales et instructions. Quand settingSources inclut "project" (comme dans l’exemple ci-dessus), le SDK charge ces fichiers en contexte au démarrage de la session. L’agent suit ensuite vos conventions de projet sans que vous ayez besoin de les répéter dans chaque invite.

Emplacements de chargement de CLAUDE.md

NiveauEmplacementQuand chargé
Projet (racine)<cwd>/CLAUDE.md ou <cwd>/.claude/CLAUDE.mdsettingSources inclut "project"
Règles du projet<cwd>/.claude/rules/*.md et .claude/rules/*.md dans chaque répertoire parentsettingSources inclut "project"
Projet (répertoires parents)Fichiers CLAUDE.md dans les répertoires au-dessus de cwdsettingSources inclut "project", chargés au démarrage de la session
Projet (répertoires enfants)Fichiers CLAUDE.md dans les sous-répertoires de cwdsettingSources inclut "project", chargés à la demande quand l’agent lit un fichier dans ce sous-arbre
Local<cwd>/CLAUDE.local.md et CLAUDE.local.md dans chaque répertoire parentsettingSources inclut "local"
Utilisateur~/.claude/CLAUDE.mdsettingSources inclut "user"
Règles utilisateur~/.claude/rules/*.mdsettingSources inclut "user"
Tous les niveaux sont additifs : si les fichiers CLAUDE.md du projet et de l’utilisateur existent tous les deux, l’agent voit les deux. Il n’y a pas de règle de précédence stricte entre les niveaux ; si les instructions entrent en conflit, le résultat dépend de la façon dont Claude les interprète. Écrivez des règles sans conflit, ou énoncez explicitement la précédence dans le fichier plus spécifique (« Ces instructions de projet remplacent tout défaut au niveau utilisateur en conflit »).
Vous pouvez également injecter du contexte directement via systemPrompt sans utiliser les fichiers CLAUDE.md. Voir Modifier les invites système. Utilisez CLAUDE.md quand vous voulez que le même contexte soit partagé entre les sessions Claude Code interactives et vos agents SDK.
Pour savoir comment structurer et organiser le contenu de CLAUDE.md, voir Gérer la mémoire de Claude.

Compétences

Les compétences sont des fichiers markdown qui donnent à votre agent des connaissances spécialisées et des flux de travail invocables. Contrairement à CLAUDE.md (qui se charge à chaque session), les compétences se chargent à la demande. L’agent reçoit les descriptions des compétences au démarrage et charge le contenu complet quand c’est pertinent. Les compétences sont découvertes à partir du système de fichiers via settingSources. Quand l’option skills sur query() est omise, les compétences utilisateur et projet découvertes sont activées et l’outil Skill est disponible, ce qui correspond au comportement de la CLI. Pour contrôler quelles compétences sont activées, passez skills comme "all", une liste de noms de compétences, ou [] pour désactiver toutes les compétences. Quand skills est défini, le SDK ajoute automatiquement l’outil Skill à allowedTools. Si vous passez également une liste tools explicite, incluez "Skill" dans cette liste pour que Claude puisse invoquer les compétences.
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

# Skills in .claude/skills/ are discovered automatically
# when settingSources includes "project"
async for message in query(
    prompt="Review this PR using our code review checklist",
    options=ClaudeAgentOptions(
        setting_sources=["user", "project"],
        skills="all",
        allowed_tools=["Read", "Grep", "Glob"],
    ),
):
    if isinstance(message, ResultMessage) and message.subtype == "success":
        print(message.result)
Les compétences doivent être créées en tant qu’artefacts du système de fichiers (.claude/skills/<name>/SKILL.md). Le SDK n’a pas d’API programmatique pour enregistrer les compétences. Voir Agent Skills dans le SDK pour les détails complets.
Pour en savoir plus sur la création et l’utilisation des compétences, voir Agent Skills dans le SDK.

Hooks

Le SDK supporte deux façons de définir les hooks, et ils s’exécutent côte à côte :
  • Hooks du système de fichiers : commandes shell définies dans settings.json, chargées quand settingSources inclut la source pertinente. Ce sont les mêmes hooks que vous configureriez pour les sessions Claude Code interactives.
  • Hooks programmatiques : fonctions de rappel passées directement à query(). Celles-ci s’exécutent dans votre processus d’application et peuvent retourner des décisions structurées. Voir Contrôler l’exécution avec les hooks.
Les deux types s’exécutent pendant le même cycle de vie des hooks. Si vous avez déjà des hooks dans le .claude/settings.json de votre projet et que vous définissez settingSources: ["project"], ces hooks s’exécutent automatiquement dans le SDK sans configuration supplémentaire. Les rappels de hook reçoivent l’entrée de l’outil et retournent un dictionnaire de décision. Retourner {} signifie permettre à l’outil de procéder. Pour bloquer l’exécution, retournez un objet hookSpecificOutput avec permissionDecision: "deny" et une permissionDecisionReason. La raison est envoyée à Claude comme résultat de l’outil. Les champs decision et reason au niveau supérieur sont dépréciés pour PreToolUse. Voir le guide des hooks pour la signature de rappel complète et les types de retour.
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, ResultMessage


# PreToolUse hook callback. Positional args:
#   input_data: HookInput dict with tool_name, tool_input, hook_event_name
#   tool_use_id: str | None, the ID of the tool call being intercepted
#   context: HookContext, carries session metadata
async def audit_bash(input_data, tool_use_id, context):
    command = input_data.get("tool_input", {}).get("command", "")
    if "rm -rf" in command:
        return {
            "hookSpecificOutput": {
                "hookEventName": "PreToolUse",
                "permissionDecision": "deny",
                "permissionDecisionReason": "Destructive command blocked",
            }
        }
    return {}  # Empty dict: allow the tool to proceed


# Filesystem hooks from .claude/settings.json run automatically
# when settingSources loads them. You can also add programmatic hooks:
async for message in query(
    prompt="Refactor the auth module",
    options=ClaudeAgentOptions(
        setting_sources=["project"],  # Loads hooks from .claude/settings.json
        hooks={
            "PreToolUse": [
                HookMatcher(matcher="Bash", hooks=[audit_bash]),
            ]
        },
    ),
):
    if isinstance(message, ResultMessage) and message.subtype == "success":
        print(message.result)

Quand utiliser quel type de hook

Type de hookMeilleur pour
Système de fichiers (settings.json)Partager les hooks entre les sessions CLI et SDK. Supporte "command" (scripts shell), "http" (POST à un point de terminaison), "mcp_tool" (appeler l’outil d’un serveur MCP connecté), "prompt" (l’LLM évalue une invite), et "agent" (génère un agent vérificateur). Ceux-ci s’exécutent dans l’agent principal et tous les sous-agents qu’il génère.
Programmatique (rappels dans query())Logique spécifique à l’application, décisions structurées et intégration en processus. Ceux-ci s’exécutent également à l’intérieur des sous-agents. Le rappel reçoit agent_id et agent_type pour distinguer.
Le SDK TypeScript supporte des événements de hook supplémentaires au-delà de Python, notamment SessionStart, SessionEnd, TeammateIdle, et TaskCompleted. Voir le guide des hooks pour le tableau complet de compatibilité des événements.
Pour les détails complets sur les hooks programmatiques, voir Contrôler l’exécution avec les hooks. Pour la syntaxe des hooks du système de fichiers, voir Hooks.

Choisir la bonne fonctionnalité

Le SDK Agent vous donne accès à plusieurs façons d’étendre le comportement de votre agent. Si vous n’êtes pas sûr de celle à utiliser, ce tableau mappe les objectifs courants à la bonne approche.
Vous voulez…UtiliserSurface SDK
Définir les conventions de projet que votre agent suit toujoursCLAUDE.mdsettingSources: ["project"] le charge automatiquement
Donner à l’agent du matériel de référence qu’il charge quand c’est pertinentSkillssettingSources + option skills
Exécuter un flux de travail réutilisable (déployer, examiner, publier)User-invocable skillssettingSources + option skills
Déléguer une sous-tâche isolée à un contexte frais (recherche, examen)SubagentsParamètre agents + allowedTools: ["Agent"]
Coordonner plusieurs instances de Claude Code avec des listes de tâches partagées et la messagerie directe inter-agentsAgent teamsNon configuré directement via les options SDK. Les équipes d’agents sont une fonctionnalité CLI où une session agit comme le chef d’équipe, coordonnant le travail entre les coéquipiers indépendants
Exécuter une logique déterministe sur les appels d’outils (audit, blocage, transformation)HooksParamètre hooks avec rappels, ou scripts shell chargés via settingSources
Donner à Claude un accès structuré aux outils pour un service externeMCPParamètre mcpServers
Subagents versus agent teams : Les subagents sont éphémères et isolés : conversation fraîche, une tâche, résumé retourné au parent. Les agent teams coordonnent plusieurs instances indépendantes de Claude Code qui partagent une liste de tâches et se envoient des messages directement. Les agent teams sont une fonctionnalité CLI. Voir What subagents inherit et la agent teams comparison pour les détails.
Chaque fonctionnalité que vous activez ajoute à la fenêtre de contexte de votre agent. Pour les coûts par fonctionnalité et comment ces fonctionnalités se superposent, voir Extend Claude Code.

Ressources connexes

  • Étendre Claude Code : Vue d’ensemble conceptuelle de toutes les fonctionnalités d’extension, avec tableaux de comparaison et analyse des coûts de contexte
  • Compétences dans le SDK : Guide complet pour utiliser les compétences par programmation
  • Sous-agents : Définir et invoquer les sous-agents pour les sous-tâches isolées
  • Hooks : Intercepter et contrôler le comportement de l’agent aux points d’exécution clés
  • Permissions : Contrôler l’accès aux outils avec les modes, les règles et les rappels
  • Invites système : Injecter du contexte sans fichiers CLAUDE.md