SDK Claude Code : Guide du développeur Python et TypeScript

Le SDK Claude Code — désormais officiellement nommé SDK Agent Claude — est une bibliothèque Python et TypeScript qui vous permet d’exécuter Claude en tant qu’agent autonome dans votre propre application. Vous lui donnez une instruction, et il gère le reste : lire des fichiers, exécuter des commandes, éditer du code, et itérer jusqu’à ce que la tâche soit accomplie. Pas de boucle d’outils à écrire, pas de gestion de flux à configurer.

Ce guide couvre tout ce dont les développeurs ont besoin pour démarrer : installation, API centrale query(), 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

• Le SDK Claude Code s’appelle désormais 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 avec le SDK Client Anthropic.
• Les outils intégrés couvrent la lecture, l’édition, l’exécution bash, la recherche web, et plus encore — aucune implémentation requise.
• Les sessions permettent aux agents de reprendre le travail sur plusieurs appels avec un contexte complet intact.
• Les hooks vous permettent de valider, journaliser ou bloquer des 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 programmatique pour les capacités d’agent de Claude Code. Il expose les mêmes outils, boucle de raisonnement et gestion de contexte que la CLI Claude Code utilise de manière interactive — mais en tant que 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 précisément ce que c’est : la couche SDK qui se trouve au-dessus de Claude Code et qui 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 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 flux de travail où vous voulez que Claude prenne des mesures autonomes en plusieurs étapes, pas seulement répondre à une instruction

Ce pour quoi ce n’est pas fait : Si vous avez besoin d’un contrôle direct sur chaque message, d’une sortie structurée depuis 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, et plus	Aucun — vous définissez et exécutez tous les outils
Sessions	Intégrées — reprenez avec un ID de session	Manuelles — gérez vous-même l’historique de la conversation
Meilleur pour	Pipelines agentiques, CI/CD, opérations sur fichiers	Applications de chat, sortie structurée, contrôle fin

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

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 d’installer :

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

Étape 1 : Configurer l’authentification

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

export ANTHROPIC_API_KEY=votre-clé-api

Le SDK prend également en charge Amazon Bedrock, Google Vertex AI et Azure AI Foundry pour les équipes qui acheminent via 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 agent

Toute la surface du SDK est construite autour d’une seule fonction : query(). Elle accepte une instruction 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="Liste tous les fichiers Python de 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: "Liste tous les fichiers TypeScript de 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" — porte le session_id pour reprendre plus tard

Étape 3 : Contrôler les autorisations avec allowedTools

Le SDK fournit des outils pré-implémentés. Vous déclarez lesquels l’agent peut utiliser ; Claude gère l’exécution.

Outil	Ce qu’il fait
Read	Lit n’importe quel fichier dans le répertoire de travail
Write	Crée de nouveaux fichiers
Edit	Effectue des modifications ciblées sur des fichiers existants
Bash	Exécute des commandes shell, des scripts, des opérations git
Glob	Trouve des fichiers par motif (**/*.ts, src/**/*.py)
Grep	Recherche du contenu dans les fichiers avec des expressions régulières
WebSearch	Recherche sur le web pour des informations actuelles
WebFetch	Récupère et analyse le contenu d’une page web
Monitor	Surveille un script en arrière-plan et réagit aux lignes de sortie
AskUserQuestion	Pose des questions de clarification à l’utilisateur en cours de tâche
Agent	Invoque 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 invite. 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="Révise ce codebase pour les vulnérabilités de sécurité et les défauts de code",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep"],
    ),
):
    if hasattr(message, "result"):
        print(message.result)

Agent d’édition complète (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 en environnement CI.

Étape 4 : Utiliser les 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 des actions, valider des entrées, bloquer des opérations dangereuses ou mettre à jour un é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 édite 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="Refactore 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: "Refactore 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 les sessions

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

Pour reprendre une session, capturez le session_id depuis 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 le codebase
    async for message in query(
        prompt="Lis le module d'authentification et identifie 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érifie maintenant si l'une de ces dépendances a 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 instruction 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 les 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 reviennent dans le contexte principal.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="Révise ce codebase : utilise 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 en sécurité d'authentification et d'autorisation.",
                    prompt="Audite le code lié à l'authentification pour les vulnérabilités OWASP Top 10. Sois précis sur les numéros de ligne et la sévérité des risques.",
                    tools=["Read", "Glob", "Grep"],
                ),
                "style-checker": AgentDefinition(
                    description="Relecteur de style de code et de maintenabilité.",
                    prompt="Vérifie 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="Ouvre https://example.com et décris 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 suivant la spécification MCP. Le registre communautaire MCP sur github.com/modelcontextprotocol/servers liste des centaines d’intégrations incluant 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 économiques — 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 — dont Kimi K2.5, GLM 5.2, MiniMax M2.1, et Qwen 3.5 — 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 token peut être significative. Voir API LLM Novita AI pour le catalogue de modèles et la tarification actuels.

Si vous avez besoin de déployer votre agent dans une infrastructure sandbox 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="Révise tous les fichiers Python modifiés dans cette PR pour la correction et les lacunes de couverture de test. Produis 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 à jour si nécessaire.

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

L’agent TypeScript se termine avant d’avoir terminé Assurez-vous de await la boucle complète de l’itérateur. 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 dont 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 depuis le SystemMessage avec subtype === "init" au début de la première requête, pas depuis 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 agentiques ; 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 plus ancien.

Dois-je installer la CLI Claude Code pour utiliser le SDK TypeScript ?

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

Le SDK Agent Claude peut-il utiliser des modèles autres que 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 n’importe quel modèle hébergé par ce fournisseur — y compris des modèles open-weight de Kimi, GLM, MiniMax ou Qwen.

Quelle est la différence entre le SDK Agent et les Agents Gérés Claude ?

Les Agents Gérés 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 génère des messages pendant le travail de l’agent. Cela offre un comportement de type streaming — vous voyez des 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 dois-je lire en premier ?

Les docs officielles sont sur 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

• Documentation CLI Claude Code : Configuration, commandes slash et intégration API LLM
• SDK Vercel AI : Guide complet du développeur pour construire des applications IA
• Comment déployer et héberger le SDK Agent Claude avec Novita Sandbox

---

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