Anthropic Agents SDK (Claude Agent SDK)

L’Anthropic Agents SDK, officiellement nommé Claude Agent SDK, est le runtime agentique développé par Anthropic qui expose la boucle d’exécution, les outils intégrés et la gestion de contexte de Claude Code sous forme de bibliothèque programmable en Python et TypeScript. Il permet de construire des agents autonomes capables de lire des fichiers, exécuter des commandes, rechercher sur le web, éditer du code et orchestrer des workflows complexes.

Éditeur: Anthropic
Type: Runtime agentique (agent loop + outils intégrés)
Licence: Conditions commerciales Anthropic (propriétaire)
Langages: Python, TypeScript/JavaScript
Versions: Python : 0.1.48 | TypeScript : 0.2.74 (mars 2026)
Anciennement: Claude Code SDK (renommé en septembre 2025)
Modèles: Claude Opus 4.6, Sonnet 4.6, Haiku 4.5
Plateformes: API Anthropic, AWS Bedrock, Google Vertex AI, Azure AI Foundry
Installation (Python): pip install claude-agent-sdk
Installation (TS): npm install @anthropic-ai/claude-agent-sdk

Du Claude Code SDK au Claude Agent SDK

Pour comprendre le Claude Agent SDK, il faut revenir à son origine. Anthropic a d’abord développé un moteur d’exécution pour Claude Code, son outil de coding agentique en terminal. Ce moteur donnait à Claude l’accès au système de fichiers, au shell, à la recherche web et à des outils d’édition de code. Internement, les équipes d’Anthropic ont réalisé que ce moteur était bien plus polyvalent que prévu : elles l’utilisaient pour la recherche approfondie, la création de vidéos, la prise de notes et pratiquement toutes leurs boucles agentiques majeures.

En septembre 2025, Anthropic a renommé le Claude Code SDK en Claude Agent SDK pour refléter cette évolution. Le renommage n’est pas cosmétique : il s’accompagne de changements structurels. Depuis la version 0.1.0, le SDK ne charge plus le prompt système de Claude Code par défaut. Vos agents démarrent avec un prompt minimal, sauf si vous activez explicitement le preset claude_code ou fournissez votre propre prompt. C’est un choix délibéré pour garantir un comportement prévisible dans les pipelines CI/CD et les déploiements multi-tenants.

Noms de packages Le package Python est passé de claude-code-sdk à claude-agent-sdk, et la classe principale de ClaudeCodeOptions à ClaudeAgentOptions. En TypeScript, le package est passé de @anthropic-ai/claude-code à @anthropic-ai/claude-agent-sdk. L’ancien package Python reste disponible sur PyPI mais redirige vers le nouveau. Consultez le guide de migration officiel pour les détails.

Principe fondamental : donner un ordinateur à Claude

Le principe de conception du Claude Agent SDK est radicalement différent de celui de l’OpenAI Agents SDK. Là où OpenAI propose un framework d’orchestration léger avec des primitives abstraites (agents, handoffs, guardrails), Anthropic donne littéralement un ordinateur à Claude. Le SDK expose l’accès au terminal, au système de fichiers et au réseau, les mêmes outils qu’un développeur humain utilise au quotidien.

La philosophie est celle d’une boucle agentique concrète en trois phases : collecter le contexte (lire des fichiers, chercher sur le web, interroger des APIs), agir (éditer du code, exécuter des commandes, écrire des fichiers) et vérifier le travail (lancer des tests, relire la sortie, corriger si nécessaire). Cette boucle se répète jusqu’à ce que la tâche soit terminée ou qu’une limite soit atteinte.

Ce n’est pas une simulation : l’agent interagit avec le vrai système de fichiers et exécute de vraies commandes shell. C’est ce qui sépare fondamentalement le Claude Agent SDK du simple function calling. Le function calling est réactif, l’Agent SDK est proactif et gère l’ensemble de la boucle d’exécution.

Architecture du SDK

La boucle agentique (Agent Loop)

Quand vous lancez un agent via le SDK, celui-ci exécute la même boucle que Claude Code. Le cycle se déroule ainsi :

1. Réception du prompt. Claude reçoit votre prompt, le prompt système, les définitions d’outils et l’historique de conversation. Le SDK émet un SystemMessage avec les métadonnées de session.

2. Décision et appel d’outils. Claude évalue la situation et décide quels outils utiliser. Il peut lire un fichier, exécuter une commande bash, chercher sur le web, ou combiner plusieurs outils dans un même tour.

3. Exécution et retour. Le SDK exécute les outils, renvoie les résultats à Claude, qui analyse et décide s’il doit continuer (nouveau tour) ou terminer (réponse finale en texte seul).

4. Compaction automatique. Quand le contexte approche de sa limite, le SDK résume automatiquement les messages précédents (fonctionnalité héritée de la commande /compact de Claude Code) et recharge les fichiers d’instructions (CLAUDE.md) après compaction.

Vous contrôlez la boucle via deux paramètres clés : max_turns (limite le nombre de tours avec appels d’outils) et max_budget_usd (plafonne le coût en dollars). Sans limites, la boucle tourne jusqu’à ce que Claude termine naturellement, ce qui convient aux tâches bien définies mais peut s’éterniser sur des prompts ouverts.

Deux interfaces : query() et ClaudeSDKClient

Le SDK propose deux interfaces principales, fonctionnellement équivalentes mais ergonomiquement distinctes :

query() est le point d’entrée principal. C’est une fonction asynchrone qui retourne un itérateur async de messages. Simple, directe, idéale pour les cas d’usage one-shot :

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Trouve et corrige le bug dans auth.py",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Bash"],
            permission_mode="acceptEdits"
        ),
    ):
        print(message)

asyncio.run(main())

ClaudeSDKClient supporte les conversations bidirectionnelles et interactives. Il permet en plus de définir des custom tools (via MCP in-process) et des hooks (fonctions Python/TypeScript invoquées à des points précis de la boucle agentique) :

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

client = ClaudeSDKClient(options=ClaudeAgentOptions(
    system_prompt="Vous êtes un agent de review de code.",
    allowed_tools=["Read", "Grep", "Glob"],
    max_turns=10
))

# Conversation multi-tours
response = await client.send("Analyse ce repository pour des failles de sécurité.")
follow_up = await client.send("Concentre-toi sur les injections SQL.")

Outils intégrés

Le SDK embarque plus de 14 outils intégrés, les mêmes que ceux de Claude Code. Contrairement à l’OpenAI Agents SDK où vous devez définir vos outils comme des fonctions Python, ici les outils sont référencés par leur nom sous forme de chaîne de caractères :

Outil	Description	Catégorie
`Read`	Lecture de fichiers	Fichiers
`Write`	Écriture de fichiers	Fichiers
`Edit` / `MultiEdit`	Édition ciblée de fichiers	Fichiers
`Glob`	Recherche de fichiers par pattern	Recherche
`Grep`	Recherche de contenu dans les fichiers	Recherche
`Bash`	Exécution de commandes shell	Exécution
`WebSearch`	Recherche sur le web	Web
`WebFetch`	Récupération de pages web	Web
`Task`	Délégation à un subagent	Orchestration

Vous listez simplement les outils autorisés et le SDK s’occupe du reste : définitions, exécution, injection des résultats dans la boucle. C’est une différence majeure avec les frameworks classiques où chaque outil nécessite un schéma JSON, un handler et une logique de validation.

Système de permissions

Donner un terminal à une IA nécessite des garde-fous solides. Le SDK implémente un système de permissions à trois niveaux :

allowed_tools : une liste blanche d’outils auto-approuvés. Un agent en lecture seule avec ["Read", "Glob", "Grep"] exécute ces outils sans confirmation. Les outils non listés restent disponibles mais nécessitent une approbation.

disallowed_tools : une liste noire qui bloque des outils, quels que soient les autres paramètres.

permission_mode : contrôle le comportement pour les outils non couverts par les listes. Les modes disponibles vont de default (demande confirmation) à acceptEdits (auto-approuve les modifications de fichiers) jusqu’à bypassPermissions (auto-approuve tout, nécessite un flag de sécurité explicite).

bypassPermissions en production Le mode bypassPermissions nécessite explicitement allow_dangerously_skip_permissions=True comme garde-fou. Ne l’utilisez qu’en environnement sandboxé (conteneur Docker isolé, réseau restreint). En production, préférez acceptEdits avec des hooks PreToolUse pour filtrer les commandes sensibles.

Subagents : orchestration multi-agent

Le modèle de subagents est l’une des fonctionnalités les plus puissantes du SDK. Vous définissez des types d’agents dans un paramètre agents, chacun avec sa propre description, son prompt système, ses outils restreints et éventuellement un modèle différent. Quand Claude décide qu’une sous-tâche correspond à l’un de ces agents, il le spawn, lui transmet la tâche spécifique, et récupère uniquement le résultat.

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

for await (const message of query({
  prompt: "Fais une review complète de ce codebase.",
  options: {
    model: "opus",
    allowedTools: ["Read", "Glob", "Grep", "Task"],
    agents: {
      security_reviewer: {
        description: "Revue de sécurité du code",
        instructions: `Analysez le code pour :
          - Injections SQL/XSS
          - Failles d'authentification
          - Exposition de secrets`,
        tools: ["Read", "Grep", "Glob"],
        model: "opus"
      },
      performance_reviewer: {
        description: "Revue de performance",
        instructions: `Analysez :
          - Requêtes N+1
          - Fuites mémoire
          - Complexité algorithmique`,
        tools: ["Read", "Grep", "Glob"],
        model: "sonnet"  // Modèle plus rapide pour cette tâche
      }
    }
  }
})) {
  // L'agent parent orchestre, les subagents analysent
}

L’isolation de contexte est ce qui rend les subagents réellement utiles : chaque subagent dispose de sa propre fenêtre de contexte, donc l’analyse de sécurité ne pollue pas la revue de performance. Claude décide lui-même quand paralléliser. Vous définissez la capacité, pas le scheduling.

Règles essentielles des subagents Task doit figurer dans allowedTools de l’agent parent, sinon les subagents ne seront jamais déclenchés. Ne mettez jamais Task dans les outils d’un subagent : les subagents ne peuvent pas en spawner d’autres. C’est une limitation intentionnelle pour éviter les boucles infinies.

Hooks : contrôle déterministe

Les hooks sont des fonctions que le SDK (pas Claude) invoque à des moments précis de la boucle agentique. Ils permettent d’ajouter un traitement déterministe autour du comportement probabiliste du LLM.

Le hook le plus utilisé est PreToolUse, qui s’exécute avant chaque appel d’outil. Il permet de bloquer une commande bash dangereuse, de loguer un appel, d’injecter des variables d’environnement ou de rediriger un outil :

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

async def pre_tool_hook(tool_name, tool_input):
    # Bloquer les commandes rm -rf
    if tool_name == "Bash" and "rm -rf" in tool_input.get("command", ""):
        return {"decision": "block", "message": "Commande destructrice bloquée."}
    # Logger tous les appels
    print(f"[AUDIT] Tool: {tool_name}, Input: {tool_input}")
    return {"decision": "allow"}

client = ClaudeSDKClient(options=ClaudeAgentOptions(
    allowed_tools=["Read", "Bash", "Edit"],
    hooks={"PreToolUse": pre_tool_hook}
))

D’autres hooks existent pour PostToolUse (après l’exécution, pour filtrer ou enrichir le résultat), et des hooks personnalisés pour l’observabilité (suivi des coûts en temps réel, métriques de performance, alertes).

Intégration MCP

Le Claude Agent SDK intègre nativement le Model Context Protocol pour étendre les capacités de vos agents. Deux approches sont possibles :

Serveurs MCP externes : des processus séparés qui communiquent via stdio ou HTTP/SSE. Idéal pour les intégrations avec des services tiers (Slack, GitHub, Google Drive, Asana, etc.) :

options = ClaudeAgentOptions(
    mcp_servers={
        "github": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-github"]
        }
    }
)

Serveurs MCP in-process (SDK MCP Servers) : des fonctions Python ou TypeScript décorées avec @tool qui s’exécutent directement dans votre processus, sans processus séparé. C’est la manière recommandée de créer des outils custom :

from claude_agent_sdk import tool, create_sdk_mcp_server

@tool("check_inventory", "Vérifie le stock d'un produit", {"product_id": str})
async def check_inventory(args):
    stock = await database.get_stock(args["product_id"])
    return {"content": [{"type": "text", "text": f"Stock: {stock} unités"}]}

inventory_server = create_sdk_mcp_server(
    name="inventory",
    version="1.0.0",
    tools=[check_inventory]
)

options = ClaudeAgentOptions(
    mcp_servers={"inventory": inventory_server}
)

Vous pouvez combiner serveurs externes et in-process dans le même agent. L’écosystème MCP croissant signifie que vous pouvez ajouter rapidement de nouvelles capacités sans écrire de connecteur custom.

Sessions et persistance

Par défaut, chaque appel à query() démarre une session fraîche sans mémoire des interactions précédentes. Pour maintenir un contexte entre les tours, le SDK utilise un système de sessions identifié par un session_id.

Pour reprendre une session existante, récupérez le session_id retourné dans le ResultMessage et passez-le en paramètre resume dans l’appel suivant. Le SDK reconstruit automatiquement le contexte.

La version TypeScript 0.2.x introduit aussi une interface V2 basée sur les sessions, avec ClaudeSDKClient qui maintient l’état de conversation de manière transparente.

Configuration par le système de fichiers

Le SDK supporte la configuration par fichiers, héritée de Claude Code :

CLAUDE.md : fichier d’instructions au niveau du projet. L’agent le charge au démarrage et après chaque compaction. C’est l’équivalent d’un prompt système persistant, ancré dans votre repository.

.claude/agents/ : dossier contenant des définitions de subagents sous forme de fichiers Markdown. Chaque fichier décrit un agent spécialisé que le SDK peut spawner.

.claude/skills/ : fichiers SKILL.md qui étendent les capacités de Claude avec des compétences spécialisées.

.claude/commands/ : commandes slash personnalisées définies en Markdown.

.claude/settings.json : configuration des hooks et des permissions.

Pour activer cette configuration basée sur les fichiers, ajoutez setting_sources=["project"] dans vos options. Par défaut (depuis la version 0.1.0), le SDK ignore ces fichiers pour garantir un comportement isolé.

Comparaison avec l’OpenAI Agents SDK

Les deux SDK portent le mot « agents » mais incarnent des philosophies très différentes :

Critère	Claude Agent SDK (Anthropic)	OpenAI Agents SDK
Philosophie	Runtime avec accès système (terminal, fichiers, réseau)	Framework d’orchestration (primitives abstraites)
Boucle agentique	Intégrée (gérée par le SDK + Claude Code runtime)	Gérée par le Runner
Outils intégrés	14+ outils (Read, Write, Bash, WebSearch, etc.)	Outils hébergés (WebSearchTool, FileSearchTool, etc.)
Custom tools	Via MCP in-process (`@tool`) ou serveurs MCP	Via `@function_tool` + décorateurs Python
Multi-agent	Subagents avec isolation de contexte	Handoffs (transfert de contrôle)
Guardrails	Hooks (PreToolUse, PostToolUse) + permissions	Guardrails dédiés (input/output/tool)
Tracing	Via hooks et logging	Intégré (Dashboard OpenAI, gratuit)
Multi-provider	Non (Claude uniquement, via API, Bedrock, Vertex, Azure)	Oui (100+ providers via LiteLLM)
Licence	Propriétaire (Commercial Terms)	MIT (open source)
Accès système	Shell réel, filesystem réel	Abstrait (function tools)

Le Claude Agent SDK excelle pour les agents qui doivent interagir avec un environnement réel : debug de code, administration système, recherche dans des codebases, automatisation DevOps. L’OpenAI Agents SDK est mieux adapté aux workflows conversationnels multi-agents (support client, pipelines de traitement, orchestration de spécialistes) où l’accent est mis sur le routage et la coordination plutôt que sur l’exécution système.

Le choix dépend fondamentalement de ce que fait votre agent : s’il doit « utiliser un ordinateur », le Claude Agent SDK est l’outil naturel. S’il doit « coordonner des spécialistes », l’OpenAI Agents SDK sera plus adapté.

Cas d’usage concrets

Agents de coding et SRE : c’est le terrain natif du SDK. Un agent peut analyser un codebase, identifier un bug, le corriger et relancer les tests, le tout dans une session continue. Les équipes SRE l’utilisent pour diagnostiquer des incidents de production en lisant des logs, exécutant des commandes de diagnostic et proposant des correctifs.

Agents de recherche approfondie : un agent utilise WebSearch et WebFetch pour collecter des sources, Bash pour exécuter des scripts d’analyse, et Write pour produire un rapport structuré. La compaction automatique permet des sessions de recherche longues sans perte de contexte.

Agents financiers : accès à des APIs externes via MCP, exécution de calculs via Bash (scripts Python), stockage de données et production de rapports. L’isolation des subagents permet de séparer l’analyse de risque de la synthèse finale.

Assistants personnels : gestion de calendrier, rédaction d’emails, organisation de fichiers. L’écosystème MCP (Slack, Google Drive, Asana) permet des intégrations sans code custom.

Pipelines CI/CD : le SDK s’intègre dans les workflows d’intégration continue. Un agent peut reviewer du code dans une PR, exécuter des tests, et poster un commentaire structuré. Le mode acceptEdits avec des hooks de sécurité permet une automatisation contrôlée.

Déploiement et plateformes

Le Claude Agent SDK supporte quatre méthodes d’authentification, ce qui le rend flexible pour différents contextes de déploiement :

API Anthropic directe : la méthode standard. Configurez ANTHROPIC_API_KEY et c’est parti. Facturation au token selon la grille tarifaire Anthropic.

AWS Bedrock : activez CLAUDE_CODE_USE_BEDROCK=1 et configurez vos credentials AWS. Permet de rester dans l’écosystème AWS avec facturation consolidée et conformité enterprise.

Google Vertex AI : activez CLAUDE_CODE_USE_VERTEX=1 et configurez Google Cloud. Idéal pour les équipes déjà sur GCP.

Microsoft Azure AI Foundry : activez CLAUDE_CODE_USE_FOUNDRY=1 et configurez Azure. Option récente qui étend la disponibilité aux environnements Microsoft.

Authentification et termes d’utilisation Anthropic interdit explicitement aux développeurs tiers de proposer une connexion via claude.ai ou d’utiliser les rate limits des plans Free, Pro ou Max pour leurs produits. Les agents construits avec le SDK doivent utiliser des clés API. En revanche, pour un usage personnel et expérimental, les comptes Pro/Max restent utilisables normalement. Anthropic a clarifié ce point en mars 2026 après une controverse communautaire.

Bonnes pratiques de sécurité

Un agent avec accès au terminal est un outil puissant mais potentiellement dangereux. Voici les pratiques recommandées :

Conteneurisation : exécutez vos agents dans des conteneurs Docker avec un réseau restreint. Utilisez un proxy pour injecter les credentials afin que l’agent ne voie jamais les clés API directement.

Principe du moindre privilège : restreignez à trois niveaux : les commandes Bash autorisées (via hooks PreToolUse), l’accès au filesystem (limité aux répertoires du projet), et les serveurs MCP autorisés.

Hooks d’audit : implémentez des hooks PreToolUse et PostToolUse qui loguent chaque action. En production, un agent sans audit trail est un risque non géré.

Budget et limites : fixez systématiquement max_budget_usd et max_turns. Un agent sur un prompt ouvert peut boucler indéfiniment et générer des coûts importants.

Secrets : ne codez jamais les clés API en dur. Utilisez des variables d’environnement ou un gestionnaire de secrets. L’agent peut lire le filesystem ; s’il y a un .env avec des secrets, il le trouvera.

Limites et points d’attention

Le Claude Agent SDK est verrouillé sur les modèles Claude. Pas de support multi-provider. C’est un choix délibéré : les capacités de raisonnement, de tool use et de suivi d’instructions de Claude sont optimisées spécifiquement pour la boucle agentique du SDK. Mais c’est aussi un facteur de lock-in.

La licence est propriétaire (Commercial Terms of Service d’Anthropic), pas MIT comme l’OpenAI Agents SDK. Cela a des implications pour les projets open source et les déploiements on-premise avec des contraintes de licence.

Le SDK est en évolution rapide (v0.x). L’API change entre les versions mineures. Pinez vos dépendances et consultez le changelog systématiquement.

Enfin, le SDK ne fournit pas de couche UI, de simulation, ni d’intégrations business prêtes à l’emploi. C’est un moteur d’exécution agentique, pas une plateforme SaaS. Pour un support client clé en main ou un chatbot d’entreprise, il faudra construire toute l’infrastructure autour.

Questions fréquentes

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

Claude Code est le produit fini d’Anthropic : un outil de coding agentique disponible en CLI, extension VS Code et application desktop. Le Claude Agent SDK est le moteur sous-jacent qui alimente Claude Code, exposé comme une bibliothèque pour que les développeurs puissent construire leurs propres agents. Pensez à Claude Code comme la voiture complète et au SDK comme le moteur que vous pouvez installer dans votre propre châssis.

Le Claude Agent SDK est-il gratuit ?

Le SDK lui-même est téléchargeable gratuitement, mais il est sous licence propriétaire (Commercial Terms of Service d’Anthropic), pas MIT. L’utilisation nécessite une clé API Anthropic (ou Bedrock/Vertex/Azure), et les appels sont facturés au token selon la grille tarifaire du fournisseur choisi. Pour Claude Opus 4.6 via l’API directe : environ $5/M tokens en entrée et $25/M tokens en sortie.

Peut-on utiliser le Claude Agent SDK avec des modèles non-Claude ?

Non, le SDK est conçu exclusivement pour les modèles Claude. Il est possible de le connecter à OpenRouter pour router vers d’autres modèles, mais cette configuration n’est pas officiellement supportée. Si vous avez besoin d’un framework multi-provider, l’OpenAI Agents SDK (via LiteLLM) ou LangChain sont de meilleures options.

Comment le Claude Agent SDK gère-t-il la sécurité des commandes exécutées ?

Via un système de permissions à trois niveaux : allowed_tools (liste blanche d’outils auto-approuvés), disallowed_tools (liste noire qui bloque des outils), et permission_mode (contrôle le comportement pour les outils non couverts). En complément, les hooks PreToolUse permettent d’inspecter et de bloquer des appels d’outils spécifiques avant exécution. La recommandation est de toujours exécuter les agents en environnement sandboxé avec le minimum de permissions nécessaires.

Le Claude Agent SDK peut-il fonctionner sur AWS Bedrock ou Google Vertex AI ?

Oui. Le SDK supporte trois plateformes cloud en plus de l’API directe : AWS Bedrock (CLAUDE_CODE_USE_BEDROCK=1), Google Vertex AI (CLAUDE_CODE_USE_VERTEX=1) et Azure AI Foundry (CLAUDE_CODE_USE_FOUNDRY=1). Chaque plateforme utilise ses propres mécanismes d’authentification et de facturation. C’est la voie recommandée pour les déploiements enterprise qui nécessitent une conformité spécifique (HIPAA, SOC 2, etc.).