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"] :
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). 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 :
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. Les paramètres gérés par le serveur sont récupérés quand le processus s’authentifie avec une credential d’organisation ; l’isolation du système de fichiers ne les supprime pas. 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

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

Quand utiliser quel type de hook

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.
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.
  • É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