
Le Claude Agent SDK, expliqué à ceux qui construisent des sites
L'Agent SDK, c'est Claude Code en bibliothèque : mêmes outils, même boucle d'agent, même gestion du contexte, en Python ou TypeScript. Ce qu'il fait, ce qui le distingue de Claude Code et de l'API, son coût et les premiers agents à construire.
Nous construisons des sites clients avec Claude Code tous les jours, et la question que nous entendons maintenant, de la part de clients comme d'autres développeurs, est la suivante : la même chose peut-elle tourner sans personne devant le terminal ? C'est le rôle du Claude Agent SDK. Ce qui se positionne sur le sujet est soit de la documentation de référence, soit une explication écrite pour des ingénieurs IA. Celle-ci s'adresse à ceux qui gèrent ou construisent des sites, et chaque détail a été vérifié dans la documentation d'Anthropic le 9 novembre 2026.
Qu'est-ce que le Claude Agent SDK ?
Le Claude Agent SDK, c'est Claude Code sous forme de bibliothèque. Anthropic le décrit comme les mêmes outils, la même boucle d'agent et la même gestion du contexte que Claude Code, programmables en Python et en TypeScript. Vous appelez une seule fonction, query, avec une consigne et des options, et le SDK renvoie des messages au fil de l'eau pendant que Claude planifie, lit des fichiers, lance des commandes et modifie le code, jusqu'à la fin de la tâche ou une erreur.
La différence avec un appel direct à l'API Claude, c'est qui écrit la boucle. Avec l'API, vous envoyez un message, recevez une réponse, et si elle demande un outil, vous l'exécutez vous-même et renvoyez le résultat. Le SDK livre cette boucle déjà écrite, avec les outils intégrés de Claude Code : lire, écrire et modifier des fichiers, lancer des commandes shell, chercher dans les fichiers et sur le web.
En quoi diffère-t-il de Claude Code et de l'API Claude ?
| Option | Qui l'exécute | À utiliser quand |
|---|---|---|
| Claude Code | Vous, en interactif, dans un terminal, un IDE, l'app de bureau ou le navigateur | Une personne est au clavier et fait le travail |
| Agent SDK | Votre propre processus, en Python ou TypeScript | Votre code lance la tâche : une planification, un webhook, un pipeline |
| API Claude | Votre processus ; vous écrivez la boucle d'outils | Vous voulez un contrôle total, ou pas d'agent du tout |
| Managed Agents | L'infrastructure d'Anthropic, configurée via l'API | Vous voulez que la boucle soit hébergée pour vous |
Pour une activité web, la ligne qui compte est la deuxième. Claude Code, c'est quand une personne conduit. L'Agent SDK, c'est quand autre chose déclenche le travail : une planification nocturne, un formulaire envoyé, un nouvel élément dans un CMS, une pull request.
Comment installer le Claude Agent SDK ?
Les paquets sont @anthropic-ai/claude-agent-sdk sur npm et claude-agent-sdk sur PyPI, avec Node.js 18.14 ou plus, ou Python 3.10 ou plus. Les deux embarquent un binaire Claude Code natif, donc la plupart des installations n'ont besoin de rien d'autre. Définissez ANTHROPIC_API_KEY dans l'environnement du processus qui exécute l'agent. Le SDK ne lit pas les fichiers .env tout seul, et c'est le premier piège : une clé qui marche dans votre terminal et échoue dans une tâche planifiée se trouve souvent dans un fichier que la tâche n'a jamais chargé. Le démarrage rapide construit un premier agent qui trouve et corrige des bugs dans un fichier.
Dans le code, le cœur est petit. Vous importez query, passez une consigne et réglez les deux options qui comptent le plus : allowedTools, les outils que l'agent peut utiliser sans demander, et permissionMode, ce qu'il peut faire sans surveillance. Tout le reste, d'un prompt système personnalisé aux serveurs MCP, se règle dans le même objet d'options.
Combien coûte le Claude Agent SDK ?
La bibliothèque est gratuite ; l'usage du modèle ne l'est pas. Le SDK s'authentifie avec une clé API de la Claude Console, ou via Amazon Bedrock, Google Cloud, Microsoft Foundry ou Claude Platform on AWS, chacun facturant au token. Aux tarifs API actuels d'Anthropic, Claude Sonnet 5.5 coûte 2 $ par million de tokens en entrée et 10 $ en sortie, Claude Opus 5.5 4 $ et 20 $, et Claude Haiku 5.5 0,10 $ et 0,50 $ pour les consignes jusqu'à 100 000 tokens. Un audit en lecture seule d'un petit site coûte peu à ces prix ; un agent qui relit un gros code toutes les heures, non.
Ce que vous ne pouvez pas faire, c'est livrer un agent qui se connecte avec un abonnement Claude. La documentation d'Anthropic indique que, sauf accord préalable, les développeurs tiers ne peuvent pas proposer la connexion claude.ai ni ses limites d'usage dans leurs produits, y compris les agents bâtis sur le SDK. Votre formule Pro ou Max couvre votre propre usage de Claude Code ; un agent qui tourne pour un client, ou dans un produit, tourne avec une clé API. L'usage du SDK relève des conditions commerciales d'Anthropic.
Qu'est-ce qui a changé avec le renommage du Claude Code SDK ?
Si vous avez construit sur l'ancien Claude Code SDK, trois choses changent. Les paquets ont été renommés depuis @anthropic-ai/claude-code et claude-code-sdk. La classe d'options Python ClaudeCodeOptions est devenue ClaudeAgentOptions. Et depuis la version 0.1.0, le SDK n'utilise plus par défaut le prompt système de Claude Code : il part d'un prompt minimal, et vous demandez le comportement de Claude Code explicitement avec le preset claude_code. Le guide de migration montre l'avant et l'après dans les deux langages.
Un autre réglage par défaut mérite l'attention, parce qu'il surprend dans l'autre sens. Sauf si vous passez settingSources: [], le SDK charge les mêmes réglages de fichiers que la CLI : vos réglages utilisateur, le dossier .claude du projet et ses fichiers CLAUDE.md. Sur votre portable, c'est pratique. Sur un serveur qui exécute des agents pour plusieurs clients, les consignes d'un projet peuvent fuir dans l'exécution d'un autre : isolez chacun.
Que doit construire en premier une activité web ?
Quelque chose en lecture seule, planifié. Les agents les plus vite rentables sur un site sont ceux qui vérifient plutôt que ceux qui modifient :
- Un audit hebdomadaire qui lit vos pages, signale les titres manquants, les liens internes cassés, les images trop lourdes et les pages sorties du sitemap, puis rédige un rapport.
- Un contrôle des formulaires et intégrations qui envoie une demande test par chaque formulaire et vérifie qu'elle arrive au CRM, parce qu'un formulaire peut échouer en silence pendant des semaines.
- Un agent de briefs qui lit les exports de la Search Console et rédige des briefs pour les questions où vous êtes près de vous positionner.
- Un relecteur de pull requests qui confronte une modification au CLAUDE.md du projet avant qu'une personne ne la regarde.
Chacun n'a besoin que de Read, Glob, Grep et de la récupération de pages web, et aucun n'a besoin du droit de modifier. C'est voulu. Un agent sans surveillance avec un accès en écriture à un site en ligne est un autre risque qu'un agent sur votre bureau, et c'est dans le système de permissions que vous décidez quels outils tournent sans validation.
Les hooks, skills et sous-agents marchent-ils dans le SDK ?
Oui, et c'est la principale raison de l'utiliser plutôt que d'écrire votre propre boucle. Le SDK prend en charge les mêmes hooks, sous-agents, serveurs MCP, sessions, skills et plugins que Claude Code. Une équipe qui utilise déjà Claude Code peut reprendre sa configuration : les hooks qui bloquent les commandes risquées, les sous-agents qui découpent un build, les serveurs MCP qui relient un CMS et le CLAUDE.md qui fixe les règles du projet se chargent de la même façon.
Où tourne un agent bâti sur le SDK ?
Là où tourne votre code : une tâche planifiée, un conteneur, un pipeline CI ou un petit serveur. Le guide d'hébergement d'Anthropic couvre Docker, le cloud et la CI. Si vous préférez ne pas exécuter le processus vous-même, Managed Agents est l'alternative hébergée d'Anthropic, configurée via l'API. Pour la plupart des petites équipes web, une tâche planifiée dans la CI qu'elles utilisent déjà suffit, et elle tourne à côté du code qu'elle vérifie.
Comment nommer un agent bâti dessus ?
Pas Claude Code. Les règles de marque d'Anthropic pour le SDK autorisent Claude Agent, ou le nom de votre agent suivi de Powered by Claude, et excluent Claude Code, Claude Code Agent et tout ce qui imite l'apparence de Claude Code. Utiliser la marque Claude est facultatif, et le produit doit se lire comme le vôtre, pas comme un produit Anthropic.
Quand l'Agent SDK est-il le mauvais outil ?
Quand une personne va de toute façon relire chaque étape. Si le travail consiste à construire ou modifier un site sous les yeux de quelqu'un, Claude Code lui-même est la meilleure interface, avec les diffs, les validations et l'historique devant vous. Le SDK mérite sa place quand le travail doit se faire sans que personne n'ouvre de terminal, et quand la même tâche revient assez souvent pour qu'on gagne à l'écrire une fois. Si vous ne savez pas lesquelles de vos tâches récurrentes s'y prêtent, c'est par là que commence notre travail d'automatisation IA.

