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 :

1

Installer le SDK

Installez @anthropic-ai/claude-code depuis NPM :

npm install -g @anthropic-ai/claude-code
2

Définir votre clé API

Obtenez votre clé API depuis la Console Anthropic et définissez la variable d’environnement ANTHROPIC_API_KEY :

export ANTHROPIC_API_KEY="votre-clé-api-ici"
3

Créer votre premier agent

Créez un de ces exemples d’agents :

# Créer un assistant juridique simple
claude -p "Révisez cette clause de contrat pour les problèmes potentiels : 'La partie accepte une responsabilité illimitée...'" \
  --append-system-prompt "Vous êtes un assistant juridique. Identifiez les risques et suggérez des améliorations."
4

Exécuter l'agent

Copiez et collez la commande ci-dessus directement dans votre terminal.

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 :

claude -p "Analyser les performances du système" \
  --append-system-prompt "Vous êtes un ingénieur de performance" \
  --allowedTools "Bash,Read,WebSearch" \
  --permission-mode acceptEdits \
  --cwd /chemin/vers/projet

Configuration

Le SDK exploite toutes les options CLI disponibles dans Claude Code. Voici les principales pour l’utilisation du SDK :

FlagDescriptionExemple
--print, -pExécuter en mode non-interactifclaude -p "requête"
--output-formatSpécifier le format de sortie (text, json, stream-json)claude -p --output-format json
--resume, -rReprendre une conversation par ID de sessionclaude --resume abc123
--continue, -cContinuer la conversation la plus récenteclaude --continue
--verboseActiver la journalisation détailléeclaude --verbose
--append-system-promptAjouter au prompt système (seulement avec --print)claude --append-system-prompt "Instruction personnalisée"
--allowedToolsListe 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"
--disallowedToolsListe 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-configCharger les serveurs MCP depuis un fichier JSONclaude --mcp-config servers.json
--permission-prompt-toolOutil 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.

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 :

# Continuer la conversation la plus récente
claude --continue "Maintenant refactorisez ceci pour de meilleures performances"

# Reprendre une conversation spécifique par ID de session
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Mettre à jour les tests"

# Reprendre en mode non-interactif
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Corriger tous les problèmes de linting" --no-interactive

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.

claude -p "Révisez ce code" --permission-mode plan

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 :

# Agent de réponse aux incidents SRE
claude -p "L'API est en panne, enquêtez" \
  --append-system-prompt "Vous êtes un expert SRE. Diagnostiquez les problèmes systématiquement et fournissez des solutions exploitables."

# Agent de révision de documents juridiques  
claude -p "Révisez ce contrat" \
  --append-system-prompt "Vous êtes un avocat d'entreprise. Identifiez les risques, suggérez des améliorations, et assurez la conformité."

# Ajouter au prompt système par défaut
claude -p "Refactorisez cette fonction" \
  --append-system-prompt "Incluez toujours une gestion d'erreurs complète et des tests unit."

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 :

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {"SLACK_TOKEN": "votre-token-slack"}
    },
    "jira": {
      "command": "npx", 
      "args": ["-y", "@modelcontextprotocol/server-jira"],
      "env": {"JIRA_TOKEN": "votre-token-jira"}
    },
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {"DB_CONNECTION_STRING": "votre-url-db"}
    }
  }
}

Exemples d’utilisation :

# Agent SRE avec outils de surveillance
claude -p "Enquêtez sur la panne du service de paiement" \
  --mcp-config sre-tools.json \
  --allowedTools "mcp__datadog,mcp__pagerduty,mcp__kubernetes" \
  --append-system-prompt "Vous êtes un SRE. Utilisez les données de surveillance pour diagnostiquer les problèmes."

# Agent de support client avec accès CRM
claude -p "Aidez à résoudre le ticket client #12345" \
  --mcp-config support-tools.json \
  --allowedTools "mcp__zendesk,mcp__stripe,mcp__user_db" \
  --append-system-prompt "Vous êtes un spécialiste du support technique."

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 MCP
  • nomOutil 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 :

  1. 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
  2. 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 :

// l'appel d'outil est autorisé
{
  "behavior": "allow",
  "updatedInput": {...}, // entrée mise à jour, ou retournez simplement l'entrée originale
}

// l'appel d'outil est refusé
{
  "behavior": "deny",
  "message": "..." // chaîne lisible par l'humain expliquant pourquoi la permission a été refusée
}

Exemples d’implémentation :

# Utiliser avec votre configuration de serveur MCP
claude -p "Analysez et corrigez les problèmes de sécurité" \
  --permission-prompt-tool mcp__security__approval_prompt \
  --mcp-config security-tools.json \
  --allowedTools "Read,Grep" \
  --disallowedTools "Bash(rm*),Write"

# Avec des règles de permission personnalisées
claude -p "Refactorisez la base de code" \
  --permission-prompt-tool mcp__custom__permission_check \
  --mcp-config custom-config.json \
  --output-format json

Notes d’utilisation :

  • Utilisez updatedInput pour dire au modèle que le prompt de permission a muté son entrée ; sinon, définissez updatedInput à 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)

claude -p "Expliquez le fichier src/components/Header.tsx"
# Sortie : Ceci est un composant React montrant...

Sortie JSON

Retourne des données structurées incluant les métadonnées :

claude -p "Comment fonctionne la couche de données ?" --output-format json

Format de réponse :

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.003,
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 800,
  "num_turns": 6,
  "result": "Le texte de réponse ici...",
  "session_id": "abc123"
}

Sortie JSON en streaming

Diffuse chaque message au fur et à mesure qu’il est reçu :

$ claude -p "Construisez une application" --output-format stream-json

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 :

type SDKMessage =
  // Un message assistant
  | {
      type: "assistant";
      message: Message; // depuis le SDK Anthropic
      session_id: string;
    }

  // Un message utilisateur
  | {
      type: "user";
      message: MessageParam; // depuis le SDK Anthropic
      session_id: string;
    }

  // Émis comme dernier message
  | {
      type: "result";
      subtype: "success";
      duration_ms: float;
      duration_api_ms: float;
      is_error: boolean;
      num_turns: int;
      result: string;
      session_id: string;
      total_cost_usd: float;
    }

  // Émis comme dernier message, quand nous avons atteint le nombre maximum de tours
  | {
      type: "result";
      subtype: "error_max_turns" | "error_during_execution";
      duration_ms: float;
      duration_api_ms: float;
      is_error: boolean;
      num_turns: int;
      session_id: string;
      total_cost_usd: float;
    }

  // Émis comme premier message au début d'une conversation
  | {
      type: "system";
      subtype: "init";
      apiKeySource: string;
      cwd: string;
      session_id: string;
      tools: string[];
      mcp_servers: {
        name: string;
        status: string;
      }[];
      model: string;
      permissionMode: "default" | "acceptEdits" | "bypassPermissions" | "plan";
    };

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)

# Argument direct
claude -p "Expliquez ce code"

# Depuis stdin
echo "Expliquez ce code" | claude -p

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.

$ echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"Expliquez ce code"}]}}' | claude -p --output-format=stream-json --input-format=stream-json --verbose

Exemples d’intégration d’agents

Bot de réponse aux incidents SRE

#!/bin/bash

# Agent de réponse automatisée aux incidents
investigate_incident() {
    local incident_description="$1"
    local severity="${2:-medium}"
    
    claude -p "Incident : $incident_description (Gravité : $severity)" \
      --append-system-prompt "Vous êtes un expert SRE. Diagnostiquez le problème, évaluez l'impact, et fournissez des éléments d'action immédiats." \
      --output-format json \
      --allowedTools "Bash,Read,WebSearch,mcp__datadog" \
      --mcp-config monitoring-tools.json
}

# Utilisation
investigate_incident "API de paiement retournant des erreurs 500" "high"

Révision de sécurité automatisée

# Agent d'audit de sécurité pour les pull requests
audit_pr() {
    local pr_number="$1"
    
    gh pr diff "$pr_number" | claude -p \
      --append-system-prompt "Vous êtes un ingénieur de sécurité. Révisez cette PR pour les vulnérabilités, les modèles non sécurisés, et les problèmes de conformité." \
      --output-format json \
      --allowedTools "Read,Grep,WebSearch"
}

# Utilisation et sauvegarde dans un fichier
audit_pr 123 > security-report.json

Assistant juridique multi-tours

# Révision de document juridique avec persistance de session
session_id=$(claude -p "Démarrer une session de révision juridique" --output-format json | jq -r '.session_id')

# Réviser le contrat en plusieurs étapes
claude -p --resume "$session_id" "Révisez contract.pdf pour les clauses de responsabilité"
claude -p --resume "$session_id" "Vérifiez la conformité avec les exigences RGPD" 
claude -p --resume "$session_id" "Générez un résumé exécutif des risques"

Meilleures pratiques spécifiques à Python

Modèles clés

import asyncio
from claude_code_sdk import ClaudeSDKClient, ClaudeCodeOptions

# Toujours utiliser des gestionnaires de contexte
async with ClaudeSDKClient() as client:
    await client.query("Analysez ce code")
    async for msg in client.receive_response():
        # Traiter les messages en streaming
        pass

# Exécuter plusieurs agents simultanément
async with ClaudeSDKClient() as reviewer, ClaudeSDKClient() as tester:
    await asyncio.gather(
        reviewer.query("Révisez main.py"),
        tester.query("Écrivez des tests pour main.py")
    )

# Gestion d'erreurs
from claude_code_sdk import CLINotFoundError, ProcessError

try:
    async with ClaudeSDKClient() as client:
        # Votre code ici
        pass
except CLINotFoundError:
    print("Installez CLI : npm install -g @anthropic-ai/claude-code")
except ProcessError as e:
    print(f"Erreur de processus : {e}")

# Collecter la réponse complète avec métadonnées
async def get_response(client, prompt):
    await client.query(prompt)
    text = []
    async for msg in client.receive_response():
        if hasattr(msg, 'content'):
            for block in msg.content:
                if hasattr(block, 'text'):
                    text.append(block.text)
        if type(msg).__name__ == "ResultMessage":
            return {'text': ''.join(text), 'cost': msg.total_cost_usd}

Conseils IPython/Jupyter

# Dans Jupyter, utilisez await directement dans les cellules
client = ClaudeSDKClient()
await client.connect()
await client.query("Analysez data.csv")
async for msg in client.receive_response():
    print(msg)
await client.disconnect()

# Créer des fonctions d'aide réutilisables
async def stream_print(client, prompt):
    await client.query(prompt)
    async for msg in client.receive_response():
        if hasattr(msg, 'content'):
            for block in msg.content:
                if hasattr(block, 'text'):
                    print(block.text, end='', flush=True)

Meilleures pratiques

  • Utilisez le format de sortie JSON pour l’analyse programmatique des réponses :

    # Analyser la réponse JSON avec jq
    result=$(claude -p "Générer du code" --output-format json)
    code=$(echo "$result" | jq -r '.result')
    cost=$(echo "$result" | jq -r '.cost_usd')
    
  • Gérez les erreurs avec élégance - vérifiez les codes de sortie et stderr :

    if ! claude -p "$prompt" 2>error.log; then
        echo "Une erreur s'est produite :" >&2
        cat error.log >&2
        exit 1
    fi
    
  • 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 :

    timeout 300 claude -p "$complex_prompt" || echo "Timeout après 5 minutes"
    
  • Respectez les limites de taux lors de plusieurs requêtes en ajoutant des délais entre les appels

Ressources connexes