Claude Code SDK
Construisez des agents IA personnalisés avec le Claude Code SDK
Pourquoi utiliser le Claude Code SDK ?
Le Claude Code SDK fournit tous les éléments de base dont vous avez besoin pour construire des agents prêts pour la production :
- Intégration Claude optimisée : Mise en cache automatique des prompts et optimisations de performance
- Écosystème d’outils riche : Opérations sur fichiers, exécution de code, recherche web, et extensibilité MCP
- Permissions avancées : Contrôle granulaire des capacités des agents
- Essentiels de production : Gestion d’erreurs intégrée, gestion de session, et surveillance
Que pouvez-vous construire avec le SDK ?
Voici quelques exemples de types d’agents que vous pouvez créer :
Agents de codage :
- Agents SRE qui diagnostiquent et corrigent les problèmes de production
- Bots de révision de sécurité qui auditent le code pour les vulnérabilités
- Assistants d’ingénierie d’astreinte qui trient les incidents
- Agents de révision de code qui appliquent le style et les meilleures pratiques
Agents métier :
- Assistants juridiques qui révisent les contrats et la conformité
- Conseillers financiers qui analysent les rapports et prévisions
- Agents de support client qui résolvent les problèmes techniques
- Assistants de création de contenu pour les équipes marketing
Le SDK est actuellement disponible en TypeScript et Python, avec une interface en ligne de commande (CLI) pour le prototypage rapide.
Démarrage rapide
Faites fonctionner votre premier agent en moins de 5 minutes :
Installer le SDK
Installez @anthropic-ai/claude-code
depuis NPM :
Installez @anthropic-ai/claude-code
depuis NPM :
Installez @anthropic-ai/claude-code
depuis NPM :
Installez claude-code-sdk
depuis PyPI et @anthropic-ai/claude-code
depuis NPM :
(Optionnel) Installez IPython pour le développement interactif :
Définir votre clé API
Obtenez votre clé API depuis la Console Anthropic et définissez la variable d’environnement ANTHROPIC_API_KEY
:
Créer votre premier agent
Créez un de ces exemples d’agents :
Exécuter l'agent
Copiez et collez la commande ci-dessus directement dans votre terminal.
Copiez et collez la commande ci-dessus directement dans votre terminal.
- Configurer le projet :
-
Ajoutez
"type": "module"
à votre package.json -
Sauvegardez le code ci-dessus comme
legal-agent.ts
, puis exécutez :
Sauvegardez le code ci-dessus comme legal-agent.py
, puis exécutez :
Pour les notebooks IPython/Jupyter, vous pouvez exécuter le code directement dans une cellule :
Chaque exemple ci-dessus crée un agent fonctionnel qui va :
- Analyser le prompt en utilisant les capacités de raisonnement de Claude
- Planifier une approche multi-étapes pour résoudre le problème
- Exécuter des actions en utilisant des outils comme les opérations sur fichiers, les commandes bash, et la recherche web
- Fournir des recommandations exploitables basées sur l’analyse
Utilisation principale
Vue d’ensemble
Le Claude Code SDK vous permet d’interfacer avec Claude Code en mode non-interactif depuis vos applications.
Prérequis
- Node.js 18+
@anthropic-ai/claude-code
depuis NPM
Utilisation de base
L’interface principale en ligne de commande pour Claude Code est la commande claude
. Utilisez le flag --print
(ou -p
) pour exécuter en mode non-interactif et imprimer le résultat final :
Configuration
Le SDK exploite toutes les options CLI disponibles dans Claude Code. Voici les principales pour l’utilisation du SDK :
Flag | 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 |
--append-system-prompt | Ajouter au prompt système (seulement avec --print ) | claude --append-system-prompt "Instruction personnalisée" |
--allowedTools | Liste séparée par des espaces d’outils autorisés, ou chaîne de liste séparée par des virgules d’outils autorisés | claude --allowedTools mcp__slack mcp__filesystem claude --allowedTools "Bash(npm install),mcp__filesystem" |
--disallowedTools | Liste séparée par des espaces d’outils refusés, ou chaîne de liste séparée par des virgules d’outils refusés | claude --disallowedTools mcp__splunk mcp__github claude --disallowedTools "Bash(git commit),mcp__github" |
--mcp-config | Charger les serveurs MCP depuis un fichier JSON | claude --mcp-config servers.json |
--permission-prompt-tool | Outil MCP pour gérer les prompts de permission (seulement avec --print ) | claude --permission-prompt-tool mcp__auth__prompt |
Pour une liste complète des options CLI et des fonctionnalités, consultez la documentation de référence CLI.
Prérequis
- Node.js 18+
@anthropic-ai/claude-code
depuis NPM
Utilisation de base
L’interface principale en ligne de commande pour Claude Code est la commande claude
. Utilisez le flag --print
(ou -p
) pour exécuter en mode non-interactif et imprimer le résultat final :
Configuration
Le SDK exploite toutes les options CLI disponibles dans Claude Code. Voici les principales pour l’utilisation du SDK :
Flag | 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 |
--append-system-prompt | Ajouter au prompt système (seulement avec --print ) | claude --append-system-prompt "Instruction personnalisée" |
--allowedTools | Liste séparée par des espaces d’outils autorisés, ou chaîne de liste séparée par des virgules d’outils autorisés | claude --allowedTools mcp__slack mcp__filesystem claude --allowedTools "Bash(npm install),mcp__filesystem" |
--disallowedTools | Liste séparée par des espaces d’outils refusés, ou chaîne de liste séparée par des virgules d’outils refusés | claude --disallowedTools mcp__splunk mcp__github claude --disallowedTools "Bash(git commit),mcp__github" |
--mcp-config | Charger les serveurs MCP depuis un fichier JSON | claude --mcp-config servers.json |
--permission-prompt-tool | Outil MCP pour gérer les prompts de permission (seulement avec --print ) | claude --permission-prompt-tool mcp__auth__prompt |
Pour une liste complète des options CLI et des fonctionnalités, consultez la documentation de référence CLI.
Prérequis
- Node.js 18+
@anthropic-ai/claude-code
depuis NPM
Pour voir le code source du SDK TypeScript, visitez la page @anthropic-ai/claude-code
sur NPM.
Utilisation de base
L’interface principale via le SDK TypeScript est la fonction query
, qui retourne un itérateur asynchrone qui diffuse les messages au fur et à mesure qu’ils arrivent :
Configuration
Le SDK TypeScript accepte tous les arguments supportés par la ligne de commande, ainsi que les options supplémentaires suivantes :
Argument | Description | 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 qui est livré avec @anthropic-ai/claude-code |
permissionMode | Mode de permission pour la session | "default" (options : "default" , "acceptEdits" , "plan" , "bypassPermissions" ) |
Prérequis
- Python 3.10+
claude-code-sdk
depuis PyPI- Node.js 18+
@anthropic-ai/claude-code
depuis NPM
Pour voir le code source du SDK Python, consultez le dépôt claude-code-sdk
.
Pour le développement interactif, utilisez IPython : pip install ipython
Utilisation de base
Le SDK Python fournit deux interfaces principales :
- La classe
ClaudeSDKClient
(Recommandée)
Idéale pour les réponses en streaming, les conversations multi-tours, et les applications interactives :
Le SDK supporte également le passage de messages structurés et d’entrées d’images :
Les exemples Python sur cette page utilisent asyncio
, mais vous pouvez aussi utiliser anyio
.
- La fonction
query
Pour des requêtes simples, ponctuelles :
Configuration
Le SDK Python accepte tous les arguments supportés par la ligne de commande via la classe ClaudeCodeOptions
.
Authentification
Clé API Anthropic
Pour l’authentification de base, récupérez une clé API Anthropic depuis la Console Anthropic et définissez la variable d’environnement ANTHROPIC_API_KEY
, comme démontré dans le Démarrage rapide.
Identifiants API tiers
Le SDK supporte également l’authentification via des fournisseurs d’API tiers :
- Amazon Bedrock : Définissez la variable d’environnement
CLAUDE_CODE_USE_BEDROCK=1
et configurez les identifiants AWS - Google Vertex AI : Définissez la variable d’environnement
CLAUDE_CODE_USE_VERTEX=1
et configurez les identifiants Google Cloud
Pour des instructions de configuration détaillées pour les fournisseurs tiers, consultez la documentation Amazon Bedrock et Google Vertex AI.
Conversations multi-tours
Pour les conversations multi-tours, vous pouvez reprendre des conversations ou continuer depuis la session la plus récente :
Utilisation du Mode Plan
Le Mode Plan permet à Claude d’analyser le code sans faire de modifications, utile pour les révisions de code et la planification de changements.
Le Mode Plan restreint l’édition, la création de fichiers, et l’exécution de commandes. Voir modes de permission pour les détails.
Prompts système personnalisés
Les prompts système définissent le rôle, l’expertise, et le comportement de votre agent. C’est là que vous spécifiez quel type d’agent vous construisez :
Utilisation avancée
Outils personnalisés via MCP
Le Model Context Protocol (MCP) vous permet de donner à vos agents des outils et capacités personnalisés. Ceci est crucial pour construire des agents spécialisés qui ont besoin d’intégrations spécifiques au domaine.
Exemples de configurations d’outils d’agents :
Exemples d’utilisation :
Lors de l’utilisation d’outils MCP, vous devez explicitement les autoriser en utilisant le flag --allowedTools
. Les noms d’outils MCP suivent le modèle mcp__<nomServeur>__<nomOutil>
où :
nomServeur
est la clé de votre fichier de configuration MCPnomOutil
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 seulement le nom du serveur (c’est-à-dire mcp__<nomServeur>
), tous les outils de ce serveur seront autorisés.
Les modèles glob (par exemple, mcp__go*
) ne sont pas supportés.
Outil de prompt de permission personnalisé
Optionnellement, utilisez --permission-prompt-tool
pour passer un outil MCP que nous utiliserons pour vérifier si l’utilisateur accorde ou non au modèle les permissions d’invoquer un outil donné. Quand le modèle invoque un outil, voici ce qui se passe :
- Nous vérifions d’abord les paramètres de permission : tous les fichiers settings.json, ainsi que
--allowedTools
et--disallowedTools
passés dans le SDK ; si l’un de ceux-ci autorise ou refuse l’appel d’outil, nous procédons avec 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 retourner une charge utile JSON-stringifiée avec le résultat. La charge utile doit être l’une des suivantes :
Exemples d’implémentation :
Notes d’utilisation :
- Utilisez
updatedInput
pour dire au modèle que le prompt de permission a muté son entrée ; sinon, définissezupdatedInput
à l’entrée originale, comme dans l’exemple ci-dessus. Par exemple, si l’outil montre un diff d’édition de fichier à l’utilisateur et lui permet d’éditer le diff manuellement, l’outil de prompt de permission devrait retourner cette édition mise à jour. - La charge utile doit être JSON-stringifiée
Formats de sortie
Le SDK supporte plusieurs formats de sortie :
Sortie texte (par défaut)
Sortie JSON
Retourne des données structurées incluant les 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 init
initial, suivi d’une liste de messages utilisateur et assistant, suivi d’un message système result
final avec les statistiques. Chaque message est émis comme un objet JSON séparé.
Schéma de message
Les messages retournés par l’API JSON sont strictement typés selon le schéma suivant :
Nous publierons bientôt ces types dans un format compatible JSONSchema. Nous utilisons la versioning sémantique pour le package principal Claude Code pour communiquer les changements cassants à ce format.
Les types Message
et MessageParam
sont disponibles dans les SDK Anthropic. Par exemple, voir les SDK Anthropic TypeScript et Python.
Formats d’entrée
Le SDK supporte plusieurs formats d’entrée :
Entrée texte (par défaut)
Entrée JSON en streaming
Un flux de messages fourni via stdin
où chaque message représente un tour utilisateur. Cela permet plusieurs tours d’une conversation sans relancer le binaire claude
et permet de fournir des conseils au modèle pendant qu’il traite une demande.
Chaque message est un objet JSON ‘Message utilisateur’, suivant le même format que le schéma de message de sortie. Les messages sont formatés en utilisant le format jsonl où chaque ligne d’entrée est un objet JSON complet. L’entrée JSON en streaming nécessite -p
et --output-format stream-json
.
Actuellement, ceci est limité aux messages utilisateur texte seulement.
Exemples d’intégration d’agents
Bot de réponse aux incidents SRE
Révision de sécurité automatisée
Assistant juridique multi-tours
Meilleures pratiques spécifiques à Python
Modèles clés
Conseils IPython/Jupyter
Meilleures pratiques
-
Utilisez le format de sortie JSON pour l’analyse programmatique des réponses :
-
Gérez les erreurs avec élégance - vérifiez les codes de sortie et stderr :
-
Utilisez la gestion de session pour maintenir le contexte dans les conversations multi-tours
-
Considérez les timeouts pour les opérations de longue durée :
-
Respectez les limites de taux lors de plusieurs requêtes en ajoutant des délais entre les appels
Ressources connexes
- Utilisation et contrôles CLI - Documentation CLI complète
- Intégration GitHub Actions - Automatisez votre workflow GitHub avec Claude
- Workflows courants - Guides étape par étape pour les cas d’usage courants