Claude Agent SDK (anciennement Claude Code SDK) : guide Python et TypeScript

Table des matières

Points clés
Qu’est-ce que le SDK Claude Code ?
SDK Claude Code vs SDK client Anthropic : quand utiliser lequel ?
Installer le SDK Claude Agent
É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 les hooks pour le contrôle du cycle de vie
Étape 5 : Reprendre le travail avec les 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é Claude Agent SDK dans la version du SDK d’agents d’Anthropic, est une bibliothèque Python et TypeScript permettant d’exécuter des agents de codage autonomes dans 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 boucle d’outils construite à la main. Avec le endpoint compatible Anthropic de Novita AI, ce même SDK peut également exécuter les 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. Pour le compromis entre abonnement et API, consultez Tarifs de l’API Claude vs formules d’abonnement.

Ce guide couvre tout ce dont les développeurs ont besoin pour démarrer : installation, API principale 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 Claude Agent SDK (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 qu’il faudrait 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 le travail sur plusieurs appels avec un contexte complet intact.
Les hooks permettent de valider, journaliser ou bloquer les appels d’outils à des moments précis du cycle de vie.
Le endpoint compatible Anthropic de Novita AI (https://api.novita.ai/anthropic) 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 vers les capacités d’agent de Claude Code. Il expose les mêmes outils, la même boucle de raisonnement et la même gestion de contexte que la CLI Claude Code utilise de manière interactive — mais sous forme de bibliothèque que vous importez et appelez depuis votre propre code. Pour les règles et le périmètre au niveau du projet, consultez Règles de Claude Code et CLAUDE.md.

Anthropic l’a renommé Claude Agent SDK à partir de la génération 4.6, mais le terme de recherche d’origine « claude code sdk » décrit toujours précisément ce que c’est : la couche SDK qui se situe au-dessus de Claude Code et permet d’automatiser des tâches d’agent en logiciel.

Ce pour quoi c’est utile :

Revue de code automatisée, refactorisation 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 à votre place
Pipelines multi-agents où un coordinateur délègue des sous-tâches à des travailleurs spécialisés
Tout flux de travail où vous souhaitez que Claude agisse de manière autonome en plusieurs étapes, pas seulement qu’il réponde à une invite

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.

	Claude Agent SDK	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()` renvoie un itérateur asynchrone	`client.messages.create()` renvoie un objet de réponse
Outils intégrés	Read, Write, Edit, Bash, Grep, Glob, WebSearch, et plus encore	Aucun — vous définissez et exécutez tous les outils
Sessions	Intégré — reprenez avec un ID de session	Manuel — gérez vous-même l’historique de la conversation
Idéal 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 modifie de manière autonome : SDK Agent. Si vous voulez que Claude réponde à une invite spécifique et renvoie une valeur que vous traitez : SDK client.

Installer le SDK Claude Agent

Python (nécessite Python 3.10+) :

pip install claude-agent-sdk

TypeScript / Node.js :

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

Le package 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 de 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 à 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 standard AWS credentials

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
# plus GOOGLE_CLOUD_PROJECT and gcloud credentials

# Microsoft Azure AI Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
# plus Azure credentials

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

Toute la surface du SDK repose sur une seule fonction : query(). Elle accepte une invite et des options, et renvoie un itérateur asynchrone d’événements de messages.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="List all Python files in this directory",
        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: "List all Python files in this directory",
  options: { allowedTools: ["Bash", "Glob"] }
})) {
  if ("result" in message) console.log(message.result);
}

L’itérateur produit plusieurs types de messages. Les deux plus utiles :

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

Étape 3 : Contrôler les permissions avec allowedTools

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

Outil	Fonction
Read	Lit n’importe quel fichier du 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 modèle (`*/.ts`, `src/*/.py`)
Grep	Recherche le contenu des fichiers avec des expressions régulières
WebSearch	Recherche sur le web 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 suffit 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 revue de code en lecture seule :

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="Review this codebase for security issues and code smell",
    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 en CI.

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

Les hooks permettent d’exécuter du code personnalisé à des points précis de l’exécution de l’agent. Vous pouvez journaliser des actions, valider des entrées, bloquer des 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", "unknown")
    with open("./audit.log", "a") as f:
        f.write(f"{datetime.now().isoformat()}: modified {file_path}\n")
    return {}

async def main():
    async for message in query(
        prompt="Refactor auth.py to use 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 ?? "unknown";
  await appendFile("./audit.log", `${new Date().toISOString()}: modified ${filePath}\n`);
  return {};
};

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

Un hook PreToolUse qui renvoie { 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 — les fichiers lus, ce qu’il a trouvé, l’historique de la conversation — sur plusieurs appels query(). Cela permet de décomposer une longue tâche en étapes ou de continuer un travail interrompu.

Pour reprendre une session, récupérez le session_id depuis l’événement init de SystemMessage, puis transmettez-le à resume :

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

async def main():
    session_id = None

    # First query: read and analyze the codebase
    async for message in query(
        prompt="Read the authentication module and identify all external dependencies",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]),
    ):
        if isinstance(message, SystemMessage) and message.subtype == "init":
            session_id = message.data["session_id"]

    # Second query: continue with full context from the first
    async for message in query(
        prompt="Now check if any of those dependencies have known vulnerabilities",
        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 conserve 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 reviennent dans le contexte principal.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="Review this codebase: use the security-auditor agent for auth files and the style-checker agent for everything else",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Agent"],
            agents={
                "security-auditor": AgentDefinition(
                    description="Specialist in authentication and authorization security.",
                    prompt="Audit auth-related code for OWASP Top 10 vulnerabilities. Be specific about line numbers and risk severity.",
                    tools=["Read", "Glob", "Grep"],
                ),
                "style-checker": AgentDefinition(
                    description="Code style and maintainability reviewer.",
                    prompt="Check code for naming conventions, complexity, and documentation gaps.",
                    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 afin de tracer quelle sortie provient de quel sous-agent.

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

Le Model Context Protocol (MCP) 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="Open https://example.com and describe the page structure",
        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 conforme à la spécification MCP. Le registre communautaire MCP sur github.com/modelcontextprotocol/servers répertorie des centaines d’intégrations, notamment Postgres, Puppeteer, Slack, GitHub et des variantes de systèmes de fichiers.

Utiliser Novita AI comme backend de modèle

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

Le endpoint de Novita AI reprend 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="your-novita-api-key"

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 — accessibles via ce endpoint. Pour les équipes qui créent des pipelines d’agents exécutant des milliers de tâches, la différence de coût par jeton peut être significative. Consultez l’API LLM Novita AI pour le catalogue de modèles actuel et les tarifs.

Si vous avez besoin de déployer votre agent sur une infrastructure sandbox isolée — utile pour l’exécution de code agentique où vous ne voulez pas que l’agent touche au 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 avec le SDK Claude Agent.

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 supervision en CI. Un modèle typique avec GitHub Actions :

- name: Run automated code review
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    python review_agent.py

Où review_agent.py contient par exemple :

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Review all changed Python files in this PR for correctness and test coverage gaps. Output a JSON report.",
        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 (refactorisation automatisée, 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 de 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 cette variable d’environnement. Exportez-la dans votre shell ou dans votre fichier .env avant d’exécuter.

L’agent TypeScript se termine avant d’avoir terminé Assurez-vous d’utiliser await sur toute la boucle itérateur. Le SDK doit traiter tous les événements de messages avant que votre processus ne se termine.

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 des sous-agents séparément de celle de l’agent principal.

La session ne reprend pas correctement Récupérez session_id depuis 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 Claude Agent (anciennement SDK Claude Code) vous fournit un agent autonome qui gère automatiquement l’exécution des outils. 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 des appels de modèles directs avec un contrôle précis.

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

Python 3.10 ou ultérieur. Le package ne s’installe pas sur Python 3.9 ou antérieur.

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

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

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

En définissant ANTHROPIC_BASE_URL sur un endpoint 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.

En quoi le SDK Agent diffère-t-il de Claude Managed Agents ?

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 mieux adapté au développement local et aux agents qui doivent accéder à vos fichiers ou services privés.

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

La fonction query() renvoie 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 d’agent Claude d’Anthropic devrais-je lire en premier ?

La documentation officielle se trouve sur code.claude.com/docs/en/agent-sdk/overview. Commencez par le guide de 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 Claude Agent, API LLM Novita AI

Claude Agent SDK (anciennement Claude Code SDK) : guide Python et TypeScript

Points clés

Qu’est-ce que le SDK Claude Code ?

SDK Claude Code vs SDK client Anthropic : quand utiliser lequel ?

Installer le SDK Claude Agent

É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 les hooks pour le contrôle du cycle de vie

Étape 5 : Reprendre le travail avec les 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 claude-agent-sdk ?

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

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

En quoi le SDK Agent diffère-t-il de Claude Managed Agents ?

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

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

Quelle documentation du SDK d’agent Claude d’Anthropic devrais-je lire en premier ?

Articles recommandés

Product

RESOURCES

Partners

Company

Points clés

Qu’est-ce que le SDK Claude Code ?

SDK Claude Code vs SDK client Anthropic : quand utiliser lequel ?

Installer le SDK Claude Agent

É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 les hooks pour le contrôle du cycle de vie

Étape 5 : Reprendre le travail avec les 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 claude-agent-sdk ?

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

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

En quoi le SDK Agent diffère-t-il de Claude Managed Agents ?

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

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

Quelle documentation du SDK d’agent Claude d’Anthropic devrais-je lire en premier ?

Articles recommandés

Articles associés

Product

RESOURCES

Partners

Company