SDK
Intégrez Claude Code dans vos applications de manière programmatique à l’aide du SDK.
Le SDK Claude Code permet aux développeurs d’intégrer Claude Code dans leurs applications de manière programmatique. Il permet d’exécuter Claude Code en tant que sous-processus, offrant ainsi un moyen de créer des assistants de codage et des outils alimentés par l’IA qui exploitent les capacités de Claude.
Le SDK est disponible pour une utilisation en ligne de commande, TypeScript et Python.
Authentification
Pour utiliser le SDK Claude Code, nous recommandons de créer une clé API dédiée :
- Créez une clé API Anthropic dans la Console Anthropic
- Ensuite, définissez la variable d’environnement
ANTHROPIC_API_KEY
. Nous recommandons de stocker cette clé en toute sécurité (par exemple, en utilisant un secret Github)
Utilisation de base du SDK
Le SDK Claude Code vous permet d’utiliser Claude Code en mode non interactif depuis vos applications.
Ligne de commande
Voici quelques exemples de base pour le SDK en ligne de commande :
TypeScript
Le SDK TypeScript est inclus dans le package principal @anthropic-ai/claude-code
sur NPM :
Le SDK TypeScript accepte tous les arguments pris en charge par le SDK en ligne de commande, ainsi que :
Argument | Description | Par défaut |
---|---|---|
abortController | Contrôleur d’abandon | new AbortController() |
cwd | Répertoire de travail actuel | process.cwd() |
executable | Quel runtime JavaScript utiliser | node lors de l’exécution avec Node.js, bun lors de l’exécution avec Bun |
executableArgs | Arguments à passer à l’exécutable | [] |
pathToClaudeCodeExecutable | Chemin vers l’exécutable Claude Code | Exécutable fourni avec @anthropic-ai/claude-code |
Python
Le SDK Python est disponible sous le nom claude-code-sdk
sur PyPI :
Prérequis :
- Python 3.10+
- Node.js
- CLI Claude Code :
npm install -g @anthropic-ai/claude-code
Utilisation de base :
Le SDK Python accepte tous les arguments pris en charge par le SDK en ligne de commande via la classe ClaudeCodeOptions
:
Utilisation avancée
La documentation ci-dessous utilise le SDK en ligne de commande comme exemple, mais peut également être utilisée avec les SDK TypeScript et Python.
Conversations à plusieurs tours
Pour les conversations à plusieurs tours, vous pouvez reprendre des conversations ou continuer à partir de la session la plus récente :
Invites système personnalisées
Vous pouvez fournir des invites système personnalisées pour guider le comportement de Claude :
Vous pouvez également ajouter des instructions à l’invite système par défaut :
Configuration MCP
Le Model Context Protocol (MCP) vous permet d’étendre Claude Code avec des outils et des ressources supplémentaires provenant de serveurs externes. En utilisant l’option --mcp-config
, vous pouvez charger des serveurs MCP qui fournissent des capacités spécialisées comme l’accès aux bases de données, les intégrations d’API ou des outils personnalisés.
Créez un fichier de configuration JSON avec vos serveurs MCP :
Puis utilisez-le avec Claude Code :
Lors de l’utilisation des outils MCP, vous devez les autoriser explicitement à l’aide de l’option --allowedTools
. Les noms des outils MCP suivent le modèle mcp__<serverName>__<toolName>
où :
serverName
est la clé de votre fichier de configuration MCPtoolName
est l’outil spécifique fourni par ce serveur
Cette mesure de sécurité garantit que les outils MCP ne sont utilisés que lorsqu’ils sont explicitement autorisés.
Si vous spécifiez uniquement le nom du serveur (c’est-à-dire mcp__<serverName>
), tous les outils de ce serveur seront autorisés.
Les modèles de glob (par exemple, mcp__go*
) ne sont pas pris en charge.
Outil d’invite d’autorisation personnalisé
En option, utilisez --permission-prompt-tool
pour passer un outil MCP que nous utiliserons pour vérifier si l’utilisateur accorde au modèle les autorisations d’invoquer un outil donné. Lorsque le modèle invoque un outil, voici ce qui se passe :
- Nous vérifions d’abord les paramètres d’autorisation : tous les fichiers settings.json, ainsi que
--allowedTools
et--disallowedTools
passés au SDK ; si l’un d’entre eux autorise ou refuse l’appel d’outil, nous procédons à l’appel d’outil - Sinon, nous invoquons l’outil MCP que vous avez fourni dans
--permission-prompt-tool
L’outil MCP --permission-prompt-tool
reçoit le nom de l’outil et l’entrée, et doit renvoyer une charge utile JSON sous forme de chaîne avec le résultat. La charge utile doit être l’une des suivantes :
Par exemple, une implémentation d’outil d’invite d’autorisation MCP en TypeScript pourrait ressembler à ceci :
Pour utiliser cet outil, ajoutez votre serveur MCP (par exemple avec --mcp-config
), puis invoquez le SDK comme suit :
Notes d’utilisation :
- Utilisez
updatedInput
pour indiquer au modèle que l’invite d’autorisation a modifié son entrée ; sinon, définissezupdatedInput
sur l’entrée originale, comme dans l’exemple ci-dessus. Par exemple, si l’outil montre un diff de modification de fichier à l’utilisateur et lui permet de modifier manuellement le diff, l’outil d’invite d’autorisation doit renvoyer cette modification mise à jour. - La charge utile doit être au format JSON stringifié
Options CLI disponibles
Le SDK exploite toutes les options CLI disponibles dans Claude Code. Voici les principales pour l’utilisation du SDK :
Option | Description | Exemple |
---|---|---|
--print , -p | Exécuter en mode non interactif | claude -p "requête" |
--output-format | Spécifier le format de sortie (text , json , stream-json ) | claude -p --output-format json |
--resume , -r | Reprendre une conversation par ID de session | claude --resume abc123 |
--continue , -c | Continuer la conversation la plus récente | claude --continue |
--verbose | Activer la journalisation détaillée | claude --verbose |
--max-turns | Limiter les tours agentiques en mode non interactif | claude --max-turns 3 |
--system-prompt | Remplacer l’invite système (uniquement avec --print ) | claude --system-prompt "Instruction personnalisée" |
--append-system-prompt | Ajouter à l’invite système (uniquement avec --print ) | claude --append-system-prompt "Instruction personnalisée" |
--allowedTools | Liste d’outils autorisés séparés par des espaces, ou chaîne d’outils autorisés séparés par des virgules | claude --allowedTools mcp__slack mcp__filesystem claude --allowedTools "Bash(npm install),mcp__filesystem" |
--disallowedTools | Liste d’outils refusés séparés par des espaces, ou chaîne d’outils refusés séparés par des virgules | claude --disallowedTools mcp__splunk mcp__github claude --disallowedTools "Bash(git commit),mcp__github" |
--mcp-config | Charger les serveurs MCP à partir d’un fichier JSON | claude --mcp-config servers.json |
--permission-prompt-tool | Outil MCP pour gérer les invites d’autorisation (uniquement avec --print ) | claude --permission-prompt-tool mcp__auth__prompt |
Pour une liste complète des options et fonctionnalités CLI, consultez la documentation Utilisation de la CLI.
Formats de sortie
Le SDK prend en charge plusieurs formats de sortie :
Sortie texte (par défaut)
Renvoie uniquement le texte de la réponse :
Sortie JSON
Renvoie des données structurées incluant des métadonnées :
Format de réponse :
Sortie JSON en streaming
Diffuse chaque message au fur et à mesure qu’il est reçu :
Chaque conversation commence par un message système initial init
, suivi d’une liste de messages utilisateur et assistant, puis d’un message système final result
avec des statistiques. Chaque message est émis sous forme d’objet JSON distinct.
Schéma de message
Les messages renvoyés par l’API JSON sont strictement typés selon le schéma suivant :
Nous publierons bientôt ces types dans un format compatible avec JSONSchema. Nous utilisons le versionnement sémantique pour le package principal Claude Code afin de communiquer les changements majeurs à ce format.
Les types Message
et MessageParam
sont disponibles dans les SDK Anthropic. Par exemple, consultez les SDK Anthropic TypeScript et Python.
Exemples
Intégration de script simple
Traitement de fichiers avec Claude
Gestion de session
Meilleures pratiques
-
Utiliser le format de sortie JSON pour l’analyse programmatique des réponses :
-
Gérer les erreurs avec élégance - vérifier les codes de sortie et stderr :
-
Utiliser la gestion de session pour maintenir le contexte dans les conversations à plusieurs tours
-
Envisager des délais d’attente pour les opérations de longue durée :
-
Respecter les limites de taux lors de multiples requêtes en ajoutant des délais entre les appels
Applications réelles
Le SDK Claude Code permet des intégrations puissantes avec votre flux de travail de développement. Un exemple notable est Claude Code GitHub Actions, qui utilise le SDK pour fournir des capacités automatisées de revue de code, de création de PR et de triage des problèmes directement dans votre flux de travail GitHub.
Ressources connexes
- Utilisation et contrôles de la CLI - Documentation complète de la CLI
- Intégration GitHub Actions - Automatisez votre flux de travail GitHub avec Claude
- Tutoriels - Guides étape par étape pour les cas d’utilisation courants