Outils & Modèles Par

Claude Agent SDK : construire un agent qui tient en production

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-vous

Questions fréquentes sur le Claude Agent SDK

C'est une bibliothèque Python et TypeScript d'Anthropic qui exécute la même boucle d'agent que Claude Code : le modèle planifie, appelle des outils, lit les résultats et recommence jusqu'à avoir terminé. Elle apporte aussi les outils intégrés (fichiers, commandes, recherche web), les sous-agents, les hooks, les sessions, la connexion à des serveurs MCP et un système de permissions. Elle s'appelait auparavant Claude Code SDK.
En Python, le paquet est claude-agent-sdk (pip install claude-agent-sdk) et il s'importe avec claude_agent_sdk. En TypeScript, c'est @anthropic-ai/claude-agent-sdk. Les deux embarquent un binaire Claude Code. Python 3.10 ou plus récent et Node.js 18.14 ou plus récent sont requis. Vérifiez la version dans la documentation avant de figer vos dépendances, le SDK évolue vite.
Il est conçu pour les modèles Claude. Vous pouvez en revanche les appeler par l'API Anthropic, Amazon Bedrock, Google Cloud ou Microsoft Foundry, ce qui permet de choisir l'hébergeur et la région. Si vous voulez pouvoir changer de fournisseur de modèle, un framework indépendant comme Pydantic AI, ou une couche d'abstraction à vous, est plus adapté.
Le Claude Agent SDK convient quand le modèle sera Claude et que vous voulez une boucle d'agent complète, avec ses outils et ses permissions, déjà éprouvée. Pydantic AI convient quand vous voulez un typage strict, des sorties structurées et la liberté de changer de modèle. Les deux sont utilisables en production. Le choix dépend de votre dépendance acceptable au fournisseur et de la place du code Python typé dans votre équipe.
On ne lui donne pas l'outil d'écriture directement. On expose un outil qui prépare l'action et renvoie un aperçu, puis on exige une confirmation humaine avant l'exécution, par le callback can_use_tool du SDK ou par une étape de votre application. Les règles de refus (disallowed_tools) et un hook PreToolUse permettent de bloquer ce qui ne doit jamais partir. Les droits de l'utilisateur doivent aussi être appliqués dans l'API appelée, pas seulement dans l'agent.
Avec un jeu de scénarios écrits à partir de demandes réelles, chacun associé au résultat attendu et, si possible, aux outils attendus. On le rejoue à chaque changement de prompt, d'outil ou de modèle, et on suit le taux de réussite, les appels d'outils inutiles, le coût et la durée par tâche. Le SDK ne fournit pas ce banc de test à votre place.
Le SDK lui-même est une bibliothèque. Le coût vient de l'usage de l'API, facturé au volume de tokens, et il augmente avec le nombre de tours de boucle, la taille des résultats d'outils et la longueur du contexte. Il faut donc le mesurer par tâche sur un jeu de test avant de chiffrer un déploiement, et plafonner la durée ou le nombre de tours d'une exécution.
Non, sauf accord préalable d'Anthropic. La documentation indique que les développeurs tiers ne peuvent pas proposer la connexion claude.ai ni ses limites d'usage dans leurs produits, y compris pour des agents construits avec le SDK. Il faut utiliser l'authentification par clé d'API ou par un fournisseur cloud.

Pour aller plus loin

Agents IA sur mesure

Une tâche qui prend des heures à votre équipe chaque semaine ?

On construit l'agent qui la traite de bout en bout dans vos outils : il lit, vérifie, rédige ou saisit, et vous gardez la validation sur ce qui compte.

Anas Rabhi, ingénieur IA et data scientist, fondateur de Tensoria
Anas R. Ingénieur IA, fondateur de Tensoria ianas.fr

Je suis ingénieur IA et data scientist, fondateur de Tensoria. Depuis plus de 6 ans, je conçois et développe des systèmes IA pour les entreprises : assistants internes basés sur RAG, agents IA en production, automatisations sur mesure, traitement intelligent de documents. Je prends le projet en charge du cadrage à la mise en production, sur les modèles du marché (Mistral, Claude, GPT) ou sur des modèles ouverts hébergés chez le client quand la confidentialité l'exige.