SDK Claude Code (SDK Agent Claude) : Guide Python et TypeScript

Table des matières

Points clés à retenir
Qu'est-ce que le SDK Claude Code ?
SDK Claude Code vs. SDK Client Anthropic : Quand utiliser lequel
Installer le SDK Agent Claude
Étape 1 : Configurer l'authentification
Étape 2 : Exécuter votre première requête d'agent
Étape 3 : Contrôler les permissions avec allowedTools
Étape 4 : Utiliser des hooks pour le contrôle du cycle de vie
Étape 5 : Reprendre le travail avec des sessions
Étape 6 : Déléguer des tâches avec des sous-agents
Étape 7 : Connecter des systèmes externes via MCP
Utiliser Novita AI comme backend de modèle
SDK Claude Code dans les pipelines CI/CD
Dépannage
FAQ
Articles recommandés

Le SDK Claude Code, renommé SDK Agent Claude lors de la publication du SDK agent d’Anthropic, est une bibliothèque Python et TypeScript permettant d’exécuter des agents de codage autonomes au sein de votre application. Il gère la lecture de fichiers, les commandes, les modifications de code, les appels d’outils et l’itération multi-étapes sans avoir à construire manuellement une boucle d’outils. Avec le point de terminaison compatible Anthropic de Novita AI, le même SDK peut également exécuter des modèles open-weight pris en charge, offrant aux équipes une voie de choix de modèle et de contrôle des coûts au-delà du backend Anthropic par défaut.

Ce guide couvre tout ce dont les développeurs ont besoin pour commencer : installation, API query() principale, outils intégrés, hooks, sessions, sous-agents, intégration MCP, et comment utiliser l’API LLM de Novita AI comme backend de modèle.

Points clés à retenir

Le SDK Claude Code s’appelle désormais le SDK Agent Claude (claude-agent-sdk pour Python, @anthropic-ai/claude-agent-sdk pour TypeScript).
Une seule fonction query() remplace la boucle manuelle d’exécution d’outils que vous auriez besoin avec le SDK Client Anthropic.
Les outils intégrés couvrent la lecture de fichiers, l’édition, l’exécution bash, la recherche web, etc. — aucune implémentation requise.
Les sessions permettent aux agents de reprendre leur travail sur plusieurs appels avec un contexte complet intact.
Les hooks vous permettent de valider, journaliser ou bloquer les appels d’outils à des points spécifiques du cycle de vie.
Le point de terminaison compatible Anthropic de Novita AI (https://api.novita.ai/anthropic) vous permet d’utiliser des modèles open-weight de haute qualité avec le même code SDK.

Qu’est-ce que le SDK Claude Code ?

Le SDK Claude Code est une interface programmable pour les capacités d’agent de Claude Code. Il expose les mêmes outils, boucle de raisonnement et gestion de contexte que ceux utilisés de manière interactive par le CLI Claude Code — mais sous forme de bibliothèque que vous importez et appelez depuis votre propre code.

Anthropic l’a renommé SDK Agent Claude à partir de la génération 4.6, mais le terme de recherche original « claude code sdk » décrit toujours avec précision ce qu’il est : la couche SDK qui se situe au-dessus de Claude Code et vous permet d’automatiser des tâches d’agent dans un logiciel.

À quoi ça sert :

Révision de code automatisée, refactoring ou génération de tests dans les pipelines CI/CD
Agents qui lisent et modifient des fichiers, exécutent des scripts ou recherchent sur le web pour vous
Pipelines multi-agents où un coordinateur délègue des sous-tâches à des travailleurs spécialisés
Tout workflow où vous souhaitez que Claude entreprenne une action autonome en plusieurs étapes, pas seulement répondre à une invite

À quoi ça ne sert pas : Si vous avez besoin d’un contrôle direct sur chaque message, d’une sortie structurée à partir d’un seul appel, ou de réponses en streaming pour une interface de chat, le SDK Client Anthropic est plus approprié.

SDK Claude Code vs. SDK Client Anthropic : Quand utiliser lequel

Les deux SDK reposent sur Claude, mais ils résolvent des problèmes différents.

	SDK Agent Claude	SDK Client Anthropic
Exécution des outils	Gérée de manière autonome par Claude	Vous implémentez la boucle d’outils
Interface	`query()` retourne un itérateur asynchrone	`client.messages.create()` retourne un objet de réponse
Outils intégrés	Read, Write, Edit, Bash, Grep, Glob, WebSearch, etc.	Aucun — vous définissez et exécutez tous les outils
Sessions	Intégrées — reprenez avec un identifiant de session	Manuelles — gérez vous-même l’historique de la conversation
Meilleur pour	Pipelines d’agents, CI/CD, opérations sur fichiers	Applications de chat, sortie structurée, contrôle précis

Si vous voulez que Claude détermine quels fichiers lire et les modifie de manière autonome : SDK Agent. Si vous voulez que Claude réponde à une invite spécifique et retourne une valeur que vous traitez : SDK Client.

Installer le SDK Agent Claude

Python (nécessite Python 3.10+) :

pip install claude-agent-sdk

TypeScript / Node.js :

npm install @anthropic-ai/claude-agent-sdk

Le paquet TypeScript inclut un binaire natif Claude Code pour votre plateforme en tant que dépendance optionnelle. Vous n’avez pas besoin d’installer Claude Code séparément.

Pour vérifier votre version Python avant l’installation :

python3 --version  # macOS/Linux
py --version       # Windows

Si pip signale No matching distribution found for claude-agent-sdk, votre interpréteur Python est antérieur à la version 3.10.

Étape 1 : Configurer l’authentification

Définissez votre clé API Anthropic comme variable d’environnement :

export ANTHROPIC_API_KEY=your-api-key

Le SDK prend également en charge Amazon Bedrock, Google Vertex AI et Azure AI Foundry pour les équipes qui passent par des fournisseurs cloud :

# Amazon Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
# plus les identifiants AWS standard

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
# plus GOOGLE_CLOUD_PROJECT et les identifiants gcloud

# Microsoft Azure AI Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
# plus les identifiants Azure

Étape 2 : Exécuter votre première requête d’agent

Toute la surface du SDK est construite autour d’une seule fonction : query(). Elle accepte une invite et des options, et retourne un itérateur asynchrone d’événements de message.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Lister tous les fichiers Python dans ce répertoire",
        options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Lister tous les fichiers Python dans ce répertoire",
  options: { allowedTools: ["Bash", "Glob"] }
})) {
  if ("result" in message) console.log(message.result);
}

L’itérateur génère plusieurs types de messages. Les deux plus utiles :

ResultMessage (ou messages avec un champ result) — la réponse finale de l’agent
SystemMessage avec subtype === "init" — contient le session_id pour reprendre plus tard

Étape 3 : Contrôler les permissions avec allowedTools

Le SDK est livré avec des outils pré-implémentés. Vous déclarez ceux que l’agent peut utiliser ; Claude gère l’exécution.

Outil	Ce qu’il fait
Read	Lire n’importe quel fichier dans le répertoire de travail
Write	Créer de nouveaux fichiers
Edit	Effectuer des modifications ciblées sur des fichiers existants
Bash	Exécuter des commandes shell, scripts, opérations git
Glob	Trouver des fichiers par motif (`*/.ts`, `src/*/.py`)
Grep	Rechercher le contenu des fichiers avec des expressions régulières
WebSearch	Rechercher sur le web des informations actuelles
WebFetch	Récupérer et analyser le contenu d’une page web
Monitor	Surveiller un script en arrière-plan et réagir aux lignes de sortie
AskUserQuestion	Poser des questions de clarification à l’utilisateur en cours de tâche
Agent	Invoquer un sous-agent défini

La combinaison Bash + Read + Edit est suffisante pour la plupart des tâches de code automatisées. Ajoutez WebSearch ou WebFetch lorsque l’agent a besoin de données externes.

allowed_tools (Python) / allowedTools (TypeScript) pré-approuve des outils spécifiques sans demander confirmation. Restreindre l’ensemble d’outils limite également ce que l’agent peut faire involontairement — une barrière de sécurité utile pour les pipelines automatisés.

Agent de révision de code en lecture seule :

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="Examiner cette base de code pour les problèmes de sécurité et les mauvaises pratiques",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep"],
    ),
):
    if hasattr(message, "result"):
        print(message.result)

Agent d’édition complet (pré-approuve les écritures de fichiers) :

options=ClaudeAgentOptions(
    allowed_tools=["Read", "Write", "Edit", "Bash"],
    permission_mode="acceptEdits",
)

permission_mode="acceptEdits" approuve automatiquement les modifications de fichiers sans invite interactive, ce qui est nécessaire lors de l’exécution dans CI.

Étape 4 : Utiliser des hooks pour le contrôle du cycle de vie

Les hooks vous permettent d’exécuter du code personnalisé à des points définis de l’exécution de l’agent. Vous pouvez journaliser les actions, valider les entrées, bloquer les opérations dangereuses ou mettre à jour l’état externe.

Événements de hook disponibles : PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop, SubagentStop, SubagentStart, PreCompact, Notification, PermissionRequest

Cet exemple écrit un journal d’audit chaque fois que l’agent modifie ou crée un fichier :

import asyncio
from datetime import datetime
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher

async def log_file_change(input_data, tool_use_id, context):
    file_path = input_data.get("tool_input", {}).get("file_path", "inconnu")
    with open("./audit.log", "a") as f:
        f.write(f"{datetime.now().isoformat()}: modifié {file_path}\n")
    return {}

async def main():
    async for message in query(
        prompt="Refactoriser auth.py pour utiliser des dataclasses",
        options=ClaudeAgentOptions(
            permission_mode="acceptEdits",
            hooks={
                "PostToolUse": [
                    HookMatcher(matcher="Edit|Write", hooks=[log_file_change])
                ]
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

import { query, HookCallback } from "@anthropic-ai/claude-agent-sdk";
import { appendFile } from "fs/promises";

const logFileChange: HookCallback = async (input) => {
  const filePath = (input as any).tool_input?.file_path ?? "inconnu";
  await appendFile("./audit.log", `${new Date().toISOString()}: modifié ${filePath}\n`);
  return {};
};

for await (const message of query({
  prompt: "Refactoriser auth.ts pour utiliser des interfaces",
  options: {
    permissionMode: "acceptEdits",
    hooks: {
      PostToolUse: [{ matcher: "Edit|Write", hooks: [logFileChange] }]
    }
  }
})) {
  if ("result" in message) console.log(message.result);
}

Un hook PreToolUse retournant { block: true } empêchera complètement l’appel d’outil — utile pour appliquer des politiques comme « ne jamais supprimer de fichiers » dans des contextes automatisés.

Étape 5 : Reprendre le travail avec des sessions

Les sessions préservent le contexte complet de l’agent — les fichiers qu’il a lus, ce qu’il a trouvé, l’historique de la conversation — sur plusieurs appels query(). Cela vous permet de diviser une tâche longue en étapes ou de continuer un travail qui a été interrompu.

Pour reprendre une session, capturez le session_id à partir de l’événement d’initialisation SystemMessage, puis passez-le à resume :

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage, ResultMessage

async def main():
    session_id = None

    # Première requête : lire et analyser la base de code
    async for message in query(
        prompt="Lire le module d'authentification et identifier toutes les dépendances externes",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]),
    ):
        if isinstance(message, SystemMessage) and message.subtype == "init":
            session_id = message.data["session_id"]

    # Deuxième requête : continuer avec le contexte complet de la première
    async for message in query(
        prompt="Vérifier maintenant si certaines de ces dépendances ont des vulnérabilités connues",
        options=ClaudeAgentOptions(
            resume=session_id,
            allowed_tools=["Read", "Bash", "WebSearch"],
        ),
    ):
        if isinstance(message, ResultMessage):
            print(message.result)

asyncio.run(main())

La deuxième invite utilise « ces dépendances » — une référence qui n’a de sens que parce que la session transporte le contexte du premier appel. Sans resume, Claude n’aurait aucune idée de ce à quoi vous faites référence.

Étape 6 : Déléguer des tâches avec des sous-agents

Les sous-agents sont des agents spécialisés que votre agent principal peut invoquer via l’outil Agent. L’agent principal coordonne ; les sous-agents effectuent un travail ciblé. Les résultats remontent dans le contexte principal.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="Examiner cette base de code : utiliser l'agent security-auditor pour les fichiers d'authentification et l'agent style-checker pour tout le reste",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Agent"],
            agents={
                "security-auditor": AgentDefinition(
                    description="Spécialiste de la sécurité de l'authentification et de l'autorisation.",
                    prompt="Auditer le code lié à l'authentification pour les vulnérabilités OWASP Top 10. Soyez précis sur les numéros de ligne et la gravité des risques.",
                    tools=["Read", "Glob", "Grep"],
                ),
                "style-checker": AgentDefinition(
                    description="Réviseur de style de code et de maintenabilité.",
                    prompt="Vérifier le code pour les conventions de nommage, la complexité et les lacunes de documentation.",
                    tools=["Read", "Glob"],
                ),
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

Incluez "Agent" dans allowed_tools pour pré-approuver les invocations de sous-agents. Les messages d’un sous-agent incluent un champ parent_tool_use_id pour tracer quelle sortie provient de quel sous-agent.

Étape 7 : Connecter des systèmes externes via MCP

Le Model Context Protocol (MCP) vous permet d’ajouter des capacités externes à l’agent — bases de données, navigateurs, API internes — sans écrire d’outils personnalisés. L’agent traite les outils MCP de la même manière que les outils intégrés.

Cet exemple ajoute l’automatisation du navigateur via le serveur MCP Playwright :

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Ouvrir https://example.com et décrire la structure de la page",
        options=ClaudeAgentOptions(
            mcp_servers={
                "playwright": {
                    "command": "npx",
                    "args": ["@playwright/mcp@latest"]
                }
            }
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

L’option mcp_servers accepte tout serveur qui suit la spécification MCP. Le registre MCP communautaire à github.com/modelcontextprotocol/servers répertorie des centaines d’intégrations, notamment Postgres, Puppeteer, Slack, GitHub et des variantes de système de fichiers.

Utiliser Novita AI comme backend de modèle

Le SDK Agent Claude utilise par défaut l’API d’Anthropic, mais vous pouvez le pointer vers le point de terminaison compatible Anthropic de Novita AI pour utiliser des modèles open-weight rentables — sans aucune modification de code.

Le point de terminaison de Novita AI reflète le format de l’API Anthropic :

https://api.novita.ai/anthropic

Définissez ces deux variables d’environnement avant d’exécuter votre agent :

export ANTHROPIC_BASE_URL="https://api.novita.ai/anthropic"
export ANTHROPIC_API_KEY="votre-clé-api-novita"

Vos appels query() existants fonctionnent sans modification. Le SDK lit ANTHROPIC_BASE_URL automatiquement.

Novita AI héberge une gamme de modèles — notamment Kimi K2.5, GLM 5.2, MiniMax M2.1 et Qwen 3.5 — qui sont accessibles via ce point de terminaison. Pour les équipes qui construisent des pipelines d’agents exécutant des milliers de tâches, la différence de coût par jeton peut être significative. Consultez API LLM Novita AI pour le catalogue de modèles actuel et les tarifs.

Si vous devez déployer votre agent dans une infrastructure de bac à sable isolée — utile pour l’exécution de code agentique où vous ne voulez pas que l’agent touche à votre système de fichiers hôte — Novita Agent Sandbox fournit un environnement d’exécution compatible E2B spécialement conçu pour les agents construits sur le SDK Agent Claude.

SDK Claude Code dans les pipelines CI/CD

Les restrictions permission_mode="acceptEdits" et allowed_tools du SDK rendent pratique l’exécution d’agents sans surveillance dans CI. Un modèle typique pour GitHub Actions :

- name: Exécuter une révision de code automatisée
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    python review_agent.py

Où review_agent.py contient quelque chose comme :

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Examiner tous les fichiers Python modifiés dans cette PR pour la correction et les lacunes de couverture de test. Produire un rapport JSON.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Bash"],
            permission_mode="acceptEdits",
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

Pour les agents qui écrivent dans le dépôt (refactoring automatisé, génération de documentation), associez cela à un hook PostToolUse qui valide les modifications avant qu’elles n’atteignent git.

Dépannage

No matching distribution found for claude-agent-sdk Votre version Python est inférieure à 3.10. Exécutez python3 --version et mettez à niveau si nécessaire.

ANTHROPIC_API_KEY is not set Le SDK nécessite la variable d’environnement. Exportez-la dans votre shell ou votre fichier .env avant d’exécuter.

L’agent TypeScript se termine avant d’avoir terminé Assurez-vous d’utiliser await pour la boucle d’itérateur complète. Le SDK doit traiter tous les événements de message avant la sortie de votre processus.

L’agent utilise des outils inattendus Utilisez allowed_tools pour restreindre explicitement l’ensemble d’outils. Si vous ne le spécifiez pas, l’agent a accès à tous les outils intégrés.

Les messages des sous-agents n’apparaissent pas dans la sortie Filtrez les messages où parent_tool_use_id est défini pour identifier la sortie du sous-agent séparément de celle de l’agent principal.

La session ne reprend pas correctement Capturez session_id à partir du SystemMessage avec subtype === "init" au début de la première requête, pas à partir d’un message de résultat.

FAQ

Quelle est la différence entre le SDK Claude Code et le SDK Anthropic ?

Le SDK Agent Claude (anciennement SDK Claude Code) vous donne un agent autonome qui gère l’exécution des outils automatiquement. Le SDK Client Anthropic vous donne un accès brut à l’API où vous implémentez vous-même la boucle d’outils. Utilisez le SDK Agent pour les pipelines d’agents ; utilisez le SDK Client pour les appels de modèle directs avec un contrôle précis.

Quelle version de Python est requise pour le claude-agent-sdk ?

Python 3.10 ou ultérieur. Le paquet ne s’installera pas sur Python 3.9 ou antérieur.

Ai-je besoin d’installer le CLI Claude Code pour utiliser le SDK TypeScript ?

Non. Le paquet @anthropic-ai/claude-agent-sdk inclut son propre binaire natif Claude Code en tant que dépendance optionnelle.

Le SDK Agent Claude peut-il utiliser des modèles autres que ceux de Claude d’Anthropic ?

En définissant ANTHROPIC_BASE_URL sur un point de terminaison compatible Anthropic comme https://api.novita.ai/anthropic, vous pouvez utiliser tout modèle hébergé par ce fournisseur — y compris les modèles open-weight de Kimi, GLM, MiniMax ou Qwen.

En quoi le SDK Agent est-il différent des Managed Agents de Claude ?

Managed Agents est une API REST hébergée où Anthropic exécute l’agent dans son infrastructure. Le SDK Agent est une bibliothèque qui exécute la boucle de l’agent dans votre propre processus, sur votre propre système de fichiers. Le SDK Agent est meilleur pour le développement local et les agents qui ont besoin d’accéder à vos fichiers ou services privés.

Le SDK Agent Claude prend-il en charge la sortie en streaming ?

La fonction query() retourne un itérateur asynchrone qui produit des messages au fur et à mesure que l’agent travaille. Cela offre un comportement de type streaming — vous voyez les résultats intermédiaires avant la réponse finale.

Puis-je utiliser le SDK Agent avec Amazon Bedrock ou Vertex AI ?

Oui. Définissez CLAUDE_CODE_USE_BEDROCK=1 plus les identifiants AWS pour Bedrock, ou CLAUDE_CODE_USE_VERTEX=1 plus les identifiants Google Cloud pour Vertex AI.

Quelle documentation du SDK Agent Claude devrais-je lire en premier ?

La documentation officielle se trouve à code.claude.com/docs/en/agent-sdk/overview. Commencez par le démarrage rapide, puis lisez les guides sur les sessions et les hooks une fois que vous avez un agent fonctionnel.

Articles recommandés

Sources vérifiées le 3 juillet 2026 : Documentation du SDK Agent Claude, API LLM Novita AI

SDK Claude Code (SDK Agent Claude) : Guide Python et TypeScript

Points clés à retenir

Qu’est-ce que le SDK Claude Code ?

SDK Claude Code vs. SDK Client Anthropic : Quand utiliser lequel

Installer le SDK Agent Claude

Étape 1 : Configurer l’authentification

Étape 2 : Exécuter votre première requête d’agent

Étape 3 : Contrôler les permissions avec allowedTools

Étape 4 : Utiliser des hooks pour le contrôle du cycle de vie

Étape 5 : Reprendre le travail avec des sessions

Étape 6 : Déléguer des tâches avec des sous-agents

Étape 7 : Connecter des systèmes externes via MCP

Utiliser Novita AI comme backend de modèle

SDK Claude Code dans les pipelines CI/CD

Dépannage

FAQ

Quelle est la différence entre le SDK Claude Code et le SDK Anthropic ?

Quelle version de Python est requise pour le claude-agent-sdk ?

Ai-je besoin d’installer le CLI Claude Code pour utiliser le SDK TypeScript ?

Le SDK Agent Claude peut-il utiliser des modèles autres que ceux de Claude d’Anthropic ?

En quoi le SDK Agent est-il différent des Managed Agents de Claude ?

Le SDK Agent Claude prend-il en charge la sortie en streaming ?

Puis-je utiliser le SDK Agent avec Amazon Bedrock ou Vertex AI ?

Quelle documentation du SDK Agent Claude devrais-je lire en premier ?

Articles recommandés

Product

RESOURCES

Partners

Company

Points clés à retenir

Qu’est-ce que le SDK Claude Code ?

SDK Claude Code vs. SDK Client Anthropic : Quand utiliser lequel

Installer le SDK Agent Claude

Étape 1 : Configurer l’authentification

Étape 2 : Exécuter votre première requête d’agent

Étape 3 : Contrôler les permissions avec allowedTools

Étape 4 : Utiliser des hooks pour le contrôle du cycle de vie

Étape 5 : Reprendre le travail avec des sessions

Étape 6 : Déléguer des tâches avec des sous-agents

Étape 7 : Connecter des systèmes externes via MCP

Utiliser Novita AI comme backend de modèle

SDK Claude Code dans les pipelines CI/CD

Dépannage

FAQ

Quelle est la différence entre le SDK Claude Code et le SDK Anthropic ?

Quelle version de Python est requise pour le claude-agent-sdk ?

Ai-je besoin d’installer le CLI Claude Code pour utiliser le SDK TypeScript ?

Le SDK Agent Claude peut-il utiliser des modèles autres que ceux de Claude d’Anthropic ?

En quoi le SDK Agent est-il différent des Managed Agents de Claude ?

Le SDK Agent Claude prend-il en charge la sortie en streaming ?

Puis-je utiliser le SDK Agent avec Amazon Bedrock ou Vertex AI ?

Quelle documentation du SDK Agent Claude devrais-je lire en premier ?

Articles recommandés

Articles associés

Product

RESOURCES

Partners

Company