Le Claude Agent SDK est une bibliothèque d'Anthropic, disponible en Python et en TypeScript, qui fournit la boucle d'agent de Claude Code pour l'embarquer dans votre propre application : le modèle planifie, appelle des outils, lit leurs résultats et recommence jusqu'à avoir terminé. Il apporte aussi les outils intégrés, les sous-agents, les hooks, les sessions, la connexion à des serveurs MCP et un système de permissions. Ce qu'il ne fournit pas, c'est ce qui fait la différence entre une démonstration et un agent utilisé tous les jours : droits par utilisateur, validation avant écriture, jeu de test, suivi des coûts.
Cet article s'adresse aux responsables techniques et aux développeurs de PME, d'ETI et d'éditeurs, ainsi qu'aux dirigeants qui doivent choisir avec quoi construire un agent. Les éléments sur le SDK viennent de la documentation officielle consultée le 17 novembre 2026. Le SDK a déjà changé de nom (il s'appelait Claude Code SDK) et d'API, donc vérifiez les détails avant de figer vos dépendances.
Nous n'avons pas de mission livrée avec ce SDK. Notre expérience de production porte sur des agents construits avec Pydantic AI et des serveurs MCP en Python, que nous comparons plus bas avec honnêteté.
Points clés à retenir
- Le Claude Agent SDK est la boucle d'agent de Claude Code sous forme de bibliothèque Python (claude-agent-sdk) et TypeScript (@anthropic-ai/claude-agent-sdk)
- Il prend en charge la boucle, les outils, les sous-agents, la gestion du contexte, MCP et les permissions ; il ne prend pas en charge vos droits métier, vos tests ni votre budget
- Les droits par utilisateur se règlent dans l'outil et dans l'API appelée, pas dans le prompt
- Une action qui écrit passe par une validation humaine, un refus explicite ou les deux
- Un jeu de scénarios rejoué à chaque changement donne la seule mesure fiable de la qualité, du coût et de la durée
- Le SDK est conçu pour les modèles Claude : si changer de fournisseur de modèle compte pour vous, comparez avec un framework indépendant comme Pydantic AI
Ce que le Claude Agent SDK prend en charge
Le Claude Agent SDK donne à votre code la même boucle d'agent que Claude Code, avec ses outils et sa gestion du contexte, pilotée depuis Python ou TypeScript. Il se distingue de l'API Claude utilisée directement, où vous écrivez vous-même la boucle d'appels d'outils, et de Managed Agents, où Anthropic héberge l'agent.
| Brique | Ce que fait le SDK |
|---|---|
| Boucle d'agent | Le modèle planifie, appelle un outil, lit le résultat et décide de la suite, jusqu'à la fin de la tâche ou une erreur |
| Outils intégrés | Lecture, écriture et édition de fichiers, commandes, recherche web |
| Outils à vous | Vos fonctions Python ou TypeScript, exposées au modèle par un serveur MCP exécuté dans votre processus |
| MCP | Connexion à des serveurs MCP externes (bases de données, navigateur, API) |
| Sous-agents | Agents spécialisés pour des sous-tâches ciblées |
| Contexte et sessions | Conservation du contexte entre les échanges, reprise ou bifurcation d'une session |
| Permissions et hooks | Modes de permission, règles d'autorisation et de refus, callback d'approbation, code exécuté avant ou après un appel d'outil |
Un détail d'architecture compte pour l'exploitation : le SDK lance un binaire Claude Code embarqué dans le paquet. Votre agent est donc un processus à héberger, avec ses variables d'environnement (clé d'API) et ses ressources, et non un simple appel HTTP. La documentation traite de l'hébergement en conteneur et en CI.
Les sous-agents, les skills et les hooks suivent les mêmes principes que dans l'outil en ligne de commande, que nous détaillons dans Claude Code : skills, sous-agents et hooks. Pour situer le SDK parmi les autres briques d'un agent (modèle, mémoire, orchestration), voyez notre guide des agents IA en entreprise.
Un exemple court : un outil à vous, limité à l'utilisateur connecté
Le plus petit agent utile ne lit pas des fichiers, il appelle un outil métier avec les droits de la personne connectée. L'exemple ci-dessous suit la syntaxe de la documentation officielle (paquet claude-agent-sdk, fonctions tool, create_sdk_mcp_server et query). La fonction api.factures_en_retard est fictive : c'est l'appel à votre propre API.
import asyncio
import json
from claude_agent_sdk import (
ClaudeAgentOptions, ResultMessage, ToolAnnotations,
create_sdk_mcp_server, query, tool,
)
def serveur_facturation(user_id: str):
# user_id vient de la session authentifiée, jamais du modèle
@tool(
"lister_factures_en_retard",
"Liste les factures impayées de l'utilisateur dont l'échéance est "
"dépassée de `depuis_jours` jours ou plus (20 au maximum).",
{"depuis_jours": int},
annotations=ToolAnnotations(readOnlyHint=True),
)
async def lister(args):
factures = await api.factures_en_retard( # votre API, avec les droits de user_id
user_id=user_id, jours=args["depuis_jours"], limite=20
)
return {"content": [{"type": "text",
"text": json.dumps(factures, ensure_ascii=False)}]}
return create_sdk_mcp_server(name="facturation", version="1.0.0", tools=[lister])
async def main(user_id: str):
options = ClaudeAgentOptions(
tools=[], # aucun outil intégré : pas de fichiers, pas de commandes
mcp_servers={"facturation": serveur_facturation(user_id)},
allowed_tools=["mcp__facturation__lister_factures_en_retard"],
permission_mode="dontAsk", # tout ce qui n'est pas autorisé est refusé
)
async for message in query(
prompt="Quelles factures ont plus de 30 jours de retard ?",
options=options,
):
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)
asyncio.run(main("utilisateur-42"))
Trois choix de cet exemple valent pour tous vos agents. Les outils intégrés sont retirés, parce qu'un agent de facturation n'a aucune raison de lancer des commandes. L'identifiant de l'utilisateur est fixé par votre code à la création du serveur, le modèle ne peut pas le modifier. Et le mode dontAsk transforme chaque demande d'autorisation en refus, ce qui convient à un agent sans interface de validation.
Ce qui reste à développer pour la production
Le SDK règle la mécanique de l'agent. Il ne connaît ni vos utilisateurs, ni vos règles métier, ni votre budget, et ces points décident de la mise en production. Le tableau les résume, puis chacun est détaillé.
| Sujet | Ce que le SDK offre | Ce qu'il reste à développer |
|---|---|---|
| Droits par utilisateur | Règles d'autorisation et de refus par outil | Les outils chargés selon le profil, le cloisonnement entre clients, le contrôle côté API |
| Validation avant écriture | Callback can_use_tool, hooks |
L'aperçu de l'action, l'interface de validation, le journal des décisions |
| Résultats d'outils | Le format du résultat, la gestion d'erreur | Pagination, plafonds, champs utiles seulement |
| Qualité | Rien | Jeu de scénarios, rejoué à chaque changement |
| Observabilité et coûts | Flux de messages et résultat final de chaque exécution (coût, nombre de tours), plafonds de tours et de budget | Traces, coût par tâche, alertes, plafond de tours |
Les droits par utilisateur et le cloisonnement
Un agent ne doit pouvoir faire que ce que l'utilisateur ferait lui-même dans l'application. Le prompt ne garantit rien : un texte malveillant glissé dans un document lu par l'agent peut le pousser à essayer autre chose. Le contrôle se met dans deux endroits, la liste d'outils construite à la connexion selon le profil, et l'API appelée par chaque outil, qui applique les droits existants.
C'est ce que nous avons construit pour ModelRH, un agent orchestrateur à 23 outils typés, chargés selon les droits de l'utilisateur, avec un flux de réponse en SSE et un cloisonnement des données. Le cas est décrit dans notre cas client ModelRH. Le SDK de cet article n'y était pas utilisé, mais le principe se transpose tel quel.
La validation humaine avant une action qui écrit
La documentation du SDK prévoit plusieurs niveaux. Les règles disallowed_tools refusent un outil dans tous les modes. Un hook PreToolUse peut bloquer un appel avant son exécution, y compris quand une règle l'a autorisé. Le callback can_use_tool suspend l'exécution jusqu'à la réponse d'une personne, qui peut accepter, refuser ou modifier les arguments. Un piège documenté mérite l'attention : un outil listé dans allowed_tools est approuvé sans passer par le callback, qui ne voit donc pas ses appels.
Notre méthode reste la même qu'ailleurs. L'agent dispose d'un outil qui prépare l'action et renvoie un aperçu (montant, destinataire, lignes modifiées), la personne valide, et seulement ensuite l'outil d'exécution est appelé. Dans ModelRH, une validation humaine précède le calcul. Une action irréversible ou massive reste dans l'interface du logiciel, pas dans l'agent.
Des résultats d'outils bornés
Un outil qui renvoie 5 000 lignes remplit le contexte, ralentit la réponse et coûte plus cher sans améliorer la réponse. Le SDK gère le contexte de l'agent, mais il ne sait pas quels champs de vos données comptent. C'est à l'outil de paginer, de plafonner (20 lignes dans l'exemple), de filtrer les champs et de renvoyer un message d'erreur utile quand la demande est trop large. La documentation propose is_error pour que le modèle lise un message que vous avez écrit plutôt qu'une exception brute. Quand le nombre d'outils grandit, la recherche d'outils du SDK charge les schémas à la demande.
Un jeu de test et une mesure
Rien dans le SDK ne dit si votre agent est bon. Il faut des scénarios écrits à partir de demandes réelles, avec le résultat attendu et, quand c'est utile, les outils attendus ou l'absence d'appel. On les rejoue à chaque modification de prompt, d'outil ou de modèle, et on suit le taux de réussite, les appels inutiles, le coût et la durée par tâche. Sur un projet pour un éditeur de plateforme IA, nous avons ainsi construit un benchmark du tool calling, avec des agents Pydantic AI et des serveurs MCP FastMCP. Le même raisonnement s'applique ici, et nous l'avons détaillé pour les serveurs MCP.
L'observabilité et les coûts
Le SDK renvoie un flux de messages et un résultat final, c'est suffisant pour déboguer en local. En production, il faut conserver les traces (quel outil, quels arguments, quelle durée), calculer un coût par tâche et alerter quand il dérive. La facture dépend du nombre de tours de boucle, de la taille des résultats d'outils et du contexte, donc elle se mesure sur votre jeu de test avant de se projeter. Nous avons utilisé Logfire pour ce suivi sur les agents Pydantic AI. Pour le SDK, comptez sur votre propre instrumentation autour de la boucle, et fixez une durée ou un nombre de tours maximal par exécution.
La dépendance au fournisseur de modèle
Le SDK est conçu pour les modèles Claude. Vous pouvez les atteindre par l'API Anthropic, Amazon Bedrock, Google Cloud ou Microsoft Foundry, ce qui laisse le choix de l'hébergeur et de la région, mais le modèle reste Claude. Deux autres règles de la documentation comptent pour un produit. Les conditions commerciales d'Anthropic s'appliquent, y compris quand vous servez vos propres clients, et vous ne pouvez pas proposer la connexion claude.ai à vos utilisateurs sans accord préalable : l'authentification passe par une clé d'API.
Cette dépendance n'est pas un défaut en soi. Elle est à choisir en connaissance de cause. Si votre cahier des charges impose un modèle hébergé en Europe d'un autre fournisseur, ou la possibilité de basculer vers un modèle local, l'architecture doit isoler le modèle dès le départ. Sur ModelRH, nous avons gardé un LLM interchangeable pour permettre une bascule on-premise.
Claude Agent SDK ou Pydantic AI
Les deux outils sont utilisables en production et ne répondent pas à la même contrainte. Pydantic AI est un framework Python indépendant du fournisseur, centré sur le typage : sorties structurées, outils typés, injection de dépendances, approbation humaine des outils, intégration MCP, évaluations et observabilité Logfire. Il prend en charge OpenAI, Anthropic, Google, Bedrock, Mistral, Ollama et d'autres.
| Critère | Claude Agent SDK | Pydantic AI |
|---|---|---|
| Modèles | Claude (API Anthropic, Bedrock, Google Cloud, Foundry) | Plusieurs fournisseurs, dont des modèles locaux |
| Langages | Python et TypeScript | Python |
| Point fort | Boucle d'agent complète, outils intégrés (fichiers, commandes), permissions, sous-agents, sessions | Typage strict, sorties structurées validées, indépendance du fournisseur |
| Cas typique | Agent qui travaille sur des fichiers, du code ou des documents, avec Claude | Agent métier branché sur des API et des données, avec un modèle à pouvoir changer |
| Exploitation | Un binaire Claude Code embarqué, à héberger | Une bibliothèque Python ordinaire |
Le choix tient en trois questions. Le modèle sera-t-il Claude pour longtemps ? L'agent travaille-t-il sur des fichiers et des documents, ou appelle-t-il surtout des API métier ? Votre équipe veut-elle des objets Python typés de bout en bout ? Si vous hésitez, comparez aussi les autres options dans notre comparatif LangChain, LangGraph et CrewAI. Les points communs restent les mêmes : droits, validation, mesure et coûts sont à construire dans les deux cas.
Si votre équipe veut monter en compétence sur ces briques, la formation agents IA couvre la construction d'agents avec outils et validation.
Pour les besoins qui dépassent un prototype, c'est le travail de notre offre de développement d'agents IA sur mesure : outils typés selon les droits, validation humaine, jeu de test et suivi en production, quel que soit le framework retenu. Sur le terrain de MCP, le pilier serveur MCP explique comment exposer vos outils aux assistants.
Vous hésitez sur le framework pour votre agent ?
Décrivez-nous le cas d'usage, les droits des utilisateurs et le modèle visé. Nous vous disons ce que nous construirions, avec quel outil, et comment nous le mesurerions, sur devis.
Prendre un rendez-vousQuestions fréquentes sur le Claude Agent SDK
Pour aller plus loin
- Guide des agents IA en entreprise : ce qu'est un agent, quand en construire un, et comment le cadrer.
- Frameworks d'agents IA : LangChain, LangGraph et CrewAI face aux besoins d'un projet réel.
- Claude Code : skills, sous-agents et hooks : les mécanismes que le SDK reprend.
- Cas client ModelRH : des outils typés selon les droits et une validation humaine.
- Quickstart du Claude Agent SDK : l'installation et un premier agent, dans la documentation officielle.