Agent SDK : intégrer les fonctionnalités de Claude Code dans votre propre programme
📚 Navigation de la série : L'article précédent 44 GitHub Actions vous a appris à intégrer Claude dans l'IC, lui permettant de travailler automatiquement dans les PR et les pipelines. Cette étape va plus loin — au lieu de simplement l'intégrer aux pipelines, utilisez l'ensemble des capacités de Claude Code comme une bibliothèque à intégrer dans vos propres programmes et services. L'Agent SDK is le canal officiel qui vous permet de « démarrer un agent Claude par programmation ».
Les amis, parlons aujourd'hui de quelque chose qui vous fera passer du statut d'« utilisateur d'outils » à celui de « créateur d'outils ».
Dans les plus de quarante articles précédents, vous avez toujours été un utilisateur de Claude Code — en tapant claude dans le terminal, en dialoguant avec lui et en le regardant modifier du code. C'est sa « face visible ». Mais il y a aussi une « face cachée » que vous n'avez très probablement jamais touchée : son noyau — cet ensemble de boucles d'agent qui lit des fichiers, exécute des commandes et réfléchit avant d'agir — peut être directement appelé par votre code.
C'est l'Agent SDK (Agent Software Development Kit, un ensemble de bibliothèques pour appeler le noyau de Claude Code par programmation en Python / TypeScript). Pour faire simple, il transforme « ce qu'est Claude Code » d'un outil en ligne de commande en une fonction dans votre programme. En écrivant quelques lignes de code, vous pouvez exécuter dans votre propre application un agent d'IA autonome capable de lire du code, de modifier des fichiers et de parcourir le réseau.
Vous mesurerez pleinement l'importance de cet outil lorsque vous voudrez créer un « petit robot de revue automatique de PR ». Au début, en appelant honnêtement l'API brute, le simple fait de « faire lire un fichier au modèle » nécessitait d'écrire beaucoup de code — insérer le contenu du fichier dans la requête, intercepter la demande du modèle disant « je veux lire X », effectuer la lecture réelle, puis renvoyer le résultat... de nombreux allers-retours fastidieux. En passant à l'Agent SDK, toutes ces corvées disparaissent, et en trois lignes de code, Claude lit le fichier lui-même et corrige le bug. Aujourd'hui, nous allons vous baliser ce chemin.
Après avoir lu cet article, vous obtiendrez :
- Une explication simple de ce qu'est l'Agent SDK et de la partie de Claude Code qu'il « extrait pour votre usage »
- La différence réelle entre le SDK et le CLI que vous tapez tous les jours — le même noyau, deux « entrées » différentes
- La différence fondamentale avec l'« API brute » (si vous ne comprenez pas cela, vous penserez réinventer la roue)
- Comment choisir entre les deux versions TypeScript et Python, quel paquet installer et quels sont les prérequis
- Un agent minimal avec sa sortie attendue que vous pouvez reproduire pas à pas : lui faire trouver et corriger un bug par lui-même
- Une réflexion claire sur « à qui s'adresse cet outil et si vous devriez l'apprendre »
01 Comprendre d'abord : ce que l'Agent SDK « extrait » de Claude Code
Pour faire simple : l'Agent SDK consiste à transformer le noyau de Claude Code en une bibliothèque, vous permettant d'appeler par programmation (en Python ou TypeScript) un agent Claude identique à celui du CLI.
Rappelez-vous de la « boucle d'agent » présentée à l'article 03 — le travail de Claude consiste essentiellement à tourner en boucle autour de « réfléchir → agir → observer » : concevoir clairement l'étape suivante, appeler un outil pour la réaliser (lire un fichier, exécuter une commande), observer le résultat pour décider de l'étape suivante. Lorsque vous utilisez claude dans le terminal, vous bénéficiez de cette boucle et d'un ensemble d'outils intégrés (Read, Edit, Bash, etc., voir article 03).
Prise de conscience clé : cette boucle et ces outils ne sont pas exclusifs au CLI, ils peuvent être directement appelés par votre code. L'explication officielle est très directe :
L'Agent SDK vous fournit les mêmes outils, boucle d'agent et gestion de contexte que Claude Code, programmables en Python et TypeScript.
Analogie : ramener la machine à café automatique d'un café dans votre propre cuisine. Vous allez tous les jours au café du coin commander un café (c'est l'utilisation du CLI), et cela vous convient très bien. Mais un jour, vous décidez de proposer ce même café dans votre propre établissement de petit-déjeuner — vous ne pouvez pas demander à vos clients d'aller dans ce café. Vous installez donc la même machine dans votre propre boutique : c'est toujours le même noyau de mouture, d'extraction et d'émulsion de lait, sauf qu'il est désormais intégré à votre propre processus, et vous décidez par programmation quand servir une tasse, à qui et avec quelle formule de petit-déjeuner. L'Agent SDK est cette « machine transportable » — le même noyau, exécuté au sein de votre propre programme.
Qu'a-t-il donc « extrait » ? La liste officielle est très claire, et tout ce qui fait la force de Claude dans le CLI s'y retrouve au complet :
- Outils intégrés : Read, Write, Edit, Bash, Glob, Grep, WebSearch sont prêts à l'emploi, vous n'avez pas à implémenter vous-même l'exécution des outils
- Boucle d'agent : le SDK gère pour vous l'enchaînement réfléchir → agir → observer
- Gestion de contexte : il garde en mémoire les fichiers lus et l'historique de la conversation
- Au-delà de cela, les hooks, les sous-agents, MCP, le contrôle des permissions et la reprise de session — tous les points d'extension du CLI peuvent être appelés par programmation
Dans des scénarios réels, quand penserez-vous à l'utiliser ? Voici trois idées courantes :
- « Je veux créer un robot Slack qui, lorsqu'un journal d'erreurs est envoyé, va localiser l'erreur dans le dépôt de code et proposer une suggestion de correction » — cela nécessite d'intégrer l'agent dans votre service Slack
- « Je veux exécuter une tâche planifiée qui parcourt automatiquement chaque nuit le dépôt de code à la recherche des TODO et génère un rapport » — cela nécessite d'appeler l'agent par programmation et de pouvoir récupérer sa sortie
- « Je veux ajouter une fonctionnalité d'“assistant IA” à mon produit, où Claude manipule directement les fichiers de projet de l'utilisateur en arrière-plan » — c'est encore plus indispensable de passer par le SDK
Ces trois tâches seraient fastidieuses à réaliser avec le CLI — le CLI est conçu pour « un humain assis devant son terminal » ; alors que les cas ci-dessus sont des cas de « déclenchement automatique par programme et récupération automatique des résultats ». C'est précisément le terrain de jeu du SDK.
💡 Résumé en une phrase : L'Agent SDK transforme le noyau de Claude Code (outils + boucle d'agent + gestion de contexte) en une bibliothèque, vous permettant d'appeler par programmation un agent Claude identique à celui du CLI, afin de l'intégrer dans vos propres programmes et services.
02 La différence réelle entre le SDK et le CLI : un même noyau, deux entrées
C'est le point sur lequel il est le plus facile de s'embrouiller, alors clarifions-le une fois pour toutes : l'Agent SDK et le CLI que vous utilisez quotidiennement partagent exactement la même base sous-jacente, la seule différence réside dans l'« entrée » — l'une pour la saisie manuelle humaine, l'autre pour l'appel par programme.
La formule officielle résume parfaitement cela :
Même fonctionnalité, interface différente.
Analogie : la même machine à café, commande directe en boutique vs intégration dans un distributeur automatique pour un service en continu. C'est toujours la même machine à café (le même noyau). Posée sur le comptoir, le serveur prépare le café à la demande du client et peut lui demander à tout moment « avec ou sans sucre ? » — c'est le CLI, adapté quand l'humain est présent et ajuste en temps réel. Placez cette même machine dans un distributeur automatique sans personnel, insérez des pièces, appuyez sur le bouton, le café coule automatiquement sans surveillance — c'est le SDK, adapté au « déclenchement automatique par programme, à l'exécution par lots et sans intervention humaine ». La machine reste identique, ce qui change, c'est l'entité qui appuie sur le bouton.
Pour savoir lequel utiliser et quand, voici le tableau comparatif officiel :
| Cas d'usage | Meilleur choix |
|---|---|
| Développement interactif (vous êtes devant le terminal pour coder et ajuster) | CLI |
| Tâche ponctuelle (lui demander temporairement de faire quelque chose) | CLI |
| CI/CD pipeline (exécution automatique dans un pipeline) | SDK |
| Applications personnalisées (intégration dans votre propre produit) | SDK |
| Automatisation en production (sans surveillance, exécution à long terme) | SDK |
L'astuce pour utiliser ce tableau : demandez-vous si vous allez rester assis devant pour surveiller, ou si c'est un programme qui s'exécute automatiquement. Humain présent pour interagir à tout moment — CLI ; programme qui démarre et récupère les résultats automatiquement — SDK.
De plus, l'explication officielle lève un doute fréquent sur l'intérêt d'apprendre les deux :
De nombreuses équipes utilisent les deux : le CLI pour le développement quotidien et le SDK pour la production. Les flux de travail se transposent directement entre les deux.
C'est tout à fait vrai. C'est ainsi que font beaucoup de développeurs : la journée pour coder, ils utilisent claude dans le terminal au gré des besoins (CLI) ; et lorsqu'un processus a été répété manuellement pour la cinquième fois et devient fastidieux, ils écrivent un script avec le SDK pour l'automatiser en arrière-plan. Les principes de rédaction des prompts, de choix des outils et de configuration des permissions sont strictement identiques — toute l'expérience accumulée sur le CLI est directement réutilisable avec le SDK.
Ne les opposez donc pas. Disons-le ainsi : le CLI est votre entrée pour une « utilisation directe », le SDK est votre entrée pour « déléguer l'exécution à un programme », tous deux reposant sur le même Claude Code. Voici un schéma pour illustrer cette relation :
Ce schéma montre que le haut présente deux « entrées » distinctes — la saisie humaine via le CLI et l'appel par programme via le SDK ; mais les deux chemins mènent au même noyau de Claude Code, pour finalement réaliser le même ensemble de tâches. C'est pourquoi on parle de « même noyau, deux entrées ».
💡 Résumé en une phrase : Le CLI et le SDK partagent le même noyau mais offrent deux entrées — le CLI pour une utilisation interactive en direct par l'utilisateur, et le SDK pour l'exécution automatique par lots par un programme ; ils s'utilisent souvent ensemble, et l'expérience acquise sur le CLI est totalement transposable au SDK.
03 Ne pas confondre : l'Agent SDK n'est pas l'« API brute », la différence réside dans « qui exécute la boucle d'outils »
C'est la distinction la plus importante de cet article. Si vous ne la comprenez pas, vous risquez de penser utiliser le SDK alors que vous réinventez une roue que Claude a déjà construite pour vous.
Vous avez peut-être entendu parler de l'« API d'Anthropic » ou du « Client SDK » (les bibliothèques clientes permettant de communiquer directement avec l'API du modèle). Bien que leurs noms soient proches et qu'ils permettent tous deux d'appeler Claude, les tâches qu'ils accomplissent n'ont rien à voir. Voici comment les distinguer en une phrase :
Le Client SDK vous fournit un « modèle sachant parler », et vous devez écrire vous-même la boucle d'outils ; l'Agent SDK vous fournit un « agent sachant travailler », et il exécute la boucle d'outils pour vous.
L'explication officielle est très claire :
L'Anthropic Client SDK vous fournit un accès direct à l'API : vous envoyez des invites et implémentez vous-même l'exécution des outils. L'Agent SDK vous fournit Claude avec l'exécution intégrée des outils.
Analogie : acheter des grains de café verts à torréfier et infuser soi-même vs acheter une machine à café automatique. Le Client SDK est comme si le marchand vous vendait uniquement des grains de café verts — les grains sont excellents (le modèle est très puissant), mais pour en faire une tasse, la torréfaction, la mouture, la chauffe de l'eau, l'extraction et l'émulsion du lait doivent être réalisées par vos soins. L'Agent SDK vous fournit directement une machine automatique — vous appuyez sur « Americano », elle moud, extrait et vous sert directement votre tasse. Le modèle sous-jacent est le même, la différence réside dans « qui prend en charge toutes les étapes intermédiaires ».
En regardant le code, la différence saute aux yeux. Voici le comparatif officiel (en Python), observez la différence de volume de code :
# Client SDK : vous devez implémenter vous-même la boucle d'outils
response = client.messages.create(...)
while response.stop_reason == "tool_use":
result = your_tool_executor(response.tool_use) # Vous devez exécuter vous-même l'outil
response = client.messages.create(tool_result=result, **params) # Puis renvoyer le résultat au modèle
# Agent SDK : Claude exécute lui-même les outils
async for message in query(prompt="Fix the bug in auth.py"):
print(message)Voyez-vous la différence ? Cette boucle while du Client SDK — « le modèle demande à utiliser un outil → vous l'exécutez → vous lui renvoyez le résultat → le modèle poursuit sa réflexion » — correspond précisément aux tâches laborieuses mentionnées au début. Le modèle se contente de « dire » qu'il veut lire auth.py, mais l'action réelle de lecture doit être écrite par vos soins, puis vous devez réinjecter manuellement le contenu. Vous devez concevoir cette « boucle d'outils » de bout en bout.
L'Agent SDK encapsule toute cette boucle while à l'intérieur de l'appel query(). Vous formulez simplement votre demande « corrige le bug dans auth.py », et l'agent décide lui-même du fichier à lire, le lit, le modifie et le vérifie, pendant que vous recevez simplement le flux de messages.
C'est précisément l'origine du problème évoqué plus haut. Lors de la création d'un robot de revue de PR, on se heurte souvent les premiers jours à la complexité de cette boucle while — intercepter le tool_use du modèle, coder la lecture de fichier ou le git diff, renvoyer les résultats, gérer les cas limites complexes. Dès que l'on découvre que l'Agent SDK prend en charge toute cette couche, ces centaines de lignes de code de transition peuvent être réduites instantanément à un simple appel à query(). Retenez bien ce comparatif :
| Critère de comparaison | Client SDK (API brute) | Agent SDK |
|---|---|---|
| Ce qui vous est fourni | Un modèle sachant parler | Un agent sachant travailler |
| Qui exécute les outils | Votre code doit les exécuter | Claude les exécute automatiquement |
| La boucle d'outils while | À implémenter de bout en bout | Prise en charge par le SDK |
| Outils intégrés (lecture/écriture de fichiers, commandes) | Aucun, tout est à coder | Prêts à l'emploi |
| Idéal pour | Personnalisation extrême, pas d'opérations sur le système de fichiers | Un agent capable de travailler directement sur vos fichiers |
Règle de décision : si vous avez besoin d'« un agent capable de lire directement vos fichiers, d'exécuter vos commandes et de modifier votre code », choisissez l'Agent SDK et évitez d'avoir à gérer cette boucle while. Ne considérez le Client SDK que si vous n'avez pas besoin d'opérations sur le système de fichiers, si vous souhaitez une simple conversation textuelle et si vous devez contrôler précisément chaque étape.
💡 Résumé en une phrase : Agent SDK ≠ API brute — l'API brute (Client SDK) vous donne le modèle et vous laisse coder la boucle d'outils ; l'Agent SDK vous donne l'agent et gère la boucle d'outils à votre place. Pour avoir un « Claude capable d'agir », optez pour l'Agent SDK et économisez tout ce code de transition.
04 Deux langages : TypeScript et Python, lequel installer et prérequis
L'Agent SDK officiel est proposé dans deux versions selon vos préférences : TypeScript et Python. Leurs fonctionnalités sont identiques, et la documentation officielle fournit chaque exemple dans les deux langages. Ne vous demandez donc pas « laquelle est la plus complète » — choisissez simplement le langage que votre équipe et vos projets utilisent déjà.
Le choix est simple : utilisez le SDK correspondant au langage de votre application. Backend Node.js ou écosystème frontend — TypeScript ; science des données, scripts ou ingénierie d'IA — Python. Suivez simplement votre projet.
Quel paquet installer et prérequis
Les commandes d'installation et les prérequis diffèrent selon le langage (conformément à la documentation officielle) :
| TypeScript | Python | |
|---|---|---|
| Commande d'installation | npm install @anthropic-ai/claude-agent-sdk | pip install claude-agent-sdk |
| Version requise | Node.js 18+ | Python 3.10+ |
| Faut-il installer Claude Code séparément ? | Non (le SDK intègre le binaire requis) | Voir l'explication ci-dessous |
La version TypeScript offre un détail pratique souligné par la documentation officielle :
Le SDK TypeScript intègre un binaire Claude Code local pour votre plateforme en tant que dépendance facultative, vous n'avez donc pas besoin d'installer Claude Code séparément.
En d'autres termes, le SDK TS fonctionne dès son installation, sans nécessiter d'installer Claude Code au préalable.
Côté Python, attention à un piège de version également signalé officiellement — le paquet requiert Python 3.10 ou supérieur. Si pip renvoie une erreur No matching distribution found for claude-agent-sdk, c'est très probablement parce que votre version de Python est trop ancienne. Vérifiez votre version :
python3 --version # macOS / Linux
py --version # WindowsMettez à jour si elle est inférieure à 3.10. Sur un ancien Mac, il est facile de se faire piéger : la commande python système par défaut est souvent en version 3.9 et renvoie cette erreur No matching distribution, tandis que passer à la version 3.11 permet de l'installer instantanément.
Clé d'API requise
Dans les deux cas, vous devez disposer d'une clé d'API Anthropic (le jeton d'authentification pour appeler les modèles) avant l'exécution. Il est conseillé de créer un fichier .env à la racine de votre projet :
ANTHROPIC_API_KEY=votre-cle-d-apiObtenez votre clé depuis la console Claude (platform.claude.com) ; c'est un identifiant d'accès confidentiel, ne le soumettez jamais dans git — veillez à l'ajouter à votre
.gitignore. Le detail de la configuration de cette API a été présenté à l'article 04.
Voici un rappel important concernant la facturation, mis en évidence au début de la documentation officielle (votre budget est en jeu, lisez attentivement) :
À compter du 15 juin 2026, l'utilisation de l'Agent SDK et de
claude -pdans le cadre des plans d'abonnement sera déduite d'un nouveau crédit mensuel pour l'Agent SDK, distinct de votre limite d'utilisation interactive.
En clair : le budget d'utilisation interactive de votre abonnement (pour discuter dans le terminal) et le budget pour l'Agent SDK seront gérés sur deux comptes séparés à partir de cette date. Ne supposez donc pas que « comme j'ai un abonnement, je peux utiliser le SDK de manière illimitée » — le SDK fait l'objet d'une facturation distincte. Référez-vous aux règles détaillées de la documentation officielle.
💡 Résumé en une phrase : Les deux SDK partagent les mêmes fonctionnalités, choisissez selon votre langage — TS via
npm install @anthropic-ai/claude-agent-sdk(Node 18+, binaire inclus sans installation requise du CLI), Python viapip install claude-agent-sdk(Python 3.10+ requis) ; tous deux nécessitentANTHROPIC_API_KEYet la facturation du SDK est distincte de celle du CLI interactif.
05 Analyser le code : query() est le point d'entrée
Rien ne vaut un exemple de code concret pour bien comprendre. Le point d'entrée principal de l'Agent SDK est unique : query(). Maîtrisez-le pour ouvrir toutes les portes du SDK.
Décortiquons l'exemple minimal officiel. Commençons par la version Python :
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
# Boucle d'agent : Claude génère le flux de messages au fil de ses actions
async for message in query(
prompt="Find and fix the bug in auth.py",
options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
):
print(message) # Claude lit le fichier, trouve le bug et le corrige
asyncio.run(main())La version TypeScript suit exactement la même logique :
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Find and fix the bug in auth.ts",
options: { allowedTools: ["Read", "Edit", "Bash"] }
})) {
console.log(message); // Claude lit le fichier, trouve le bug et le corrige
}C'est tout. Décomposons les trois éléments clés (synthèse de la documentation officielle) :
① query() — le point d'entrée principal de la boucle d'agent. Il renvoie un « itérateur asynchrone » (async iterator, un objet capable de produire des messages un par un). Vous utilisez donc async for (ou for await en TS) pour intercepter en continu chaque message émis par Claude pendant qu'il travaille : ses réflexions, les outils qu'il appelle, les retours des outils et le résultat final.
② prompt — ce que vous voulez qu'il fasse. Identique à la phrase que vous taperiez dans le CLI. Ici, « trouve et corrige le bug dans auth.py ». Claude détermine lui-même les outils nécessaires.
③ options — la configuration de cet agent. L'option la plus courante est allowed_tools (TS : allowedTools), qui permet d'approuver au préalable les outils qu'il est autorisé à utiliser. L'exemple ci-dessus fournit Read, Edit et Bash, ce qui signifie « tu as l'autorisation de lire les fichiers, de les modifier et d'exécuter des commandes ».
Notez que cette boucle async for / for await tourne jusqu'à ce que Claude termine sa tâche ou rencontre une erreur. À chaque itération, elle émet un message. Le SDK gère en arrière-plan l'exécution des outils, la gestion du contexte et les tentatives en cas d'erreur. Vous n'avez qu'à consommer le flux. La documentation officielle l'explique ainsi :
Le SDK gère l'orchestration (exécution des outils, gestion du contexte, tentatives de reconnexion), vous n'avez donc qu'à consommer le flux.
C'est là le principal avantage par rapport à l'API brute — vous constaterez que ce code ne contient aucune boucle d'outils while, cette dernière étant entièrement encapsulée dans query().
Ajoutons un point crucial sur la relation entre les outils fournis et les permissions (faisant écho à l'article 20). Les outils déclarés dans allowed_tools déterminent l'étendue des actions autorisées pour l'agent. La documentation officielle propose ce tableau comparatif très clair :
| Outils fournis | Actions autorisées pour l'agent |
|---|---|
Read, Glob, Grep | Analyse en lecture seule (lecture possible, aucune modification) |
Read, Edit, Glob | Analyse + Modification du code |
Read, Edit, Bash, Glob, Grep | Automatisation complète (lecture, modification et exécution de commandes) |
Vous souhaitez créer un agent sécurisé « en lecture seule » ? Fournissez-lui uniquement Read, Glob et Grep. C'est encore plus sûr qu'une validation manuelle temporaire dans le CLI : l'agent ne disposant pas de l'outil Edit, il lui est techniquement impossible de modifier quoi que ce soit.
Pour les utilisateurs de Python : en plus de l'appel ponctuel
query(), le SDK Python propose égalementClaudeSDKClient— une encapsulation dequery()permettant à plusieurs appels de partager automatiquement la même session, sans avoir à transmettre manuellement le paramètreresume. C'est idéal pour les interfaces de chat ou les REPL nécessitant plusieurs tours de conversation ; pour les tâches ponctuelles, l'appel àquery()suffit largement.
💡 Résumé en une phrase : L'entrée du SDK est
query()— passez-lui leprompt(la tâche à accomplir) et lesoptions(configuration, notammentallowed_toolsqui définit les outils autorisés), et il renvoie un flux de messages à intercepter avecasync for; la boucle d'outilswhilede l'API brute est entièrement gérée en interne parquery().
06 Pratique : exécuter en 5 minutes un agent capable de « trouver et corriger un bug par lui-même »
La théorie c'est bien, la pratique c'est mieux. Cette section vous guide pour exécuter vous-même l'agent d'initiation classique de la documentation officielle — nous allons introduire volontairement des bugs dans un code pour que l'agent les détecte et les corrige. Ce test est autonome et ne nécessite aucun projet existant complexe. Suivez simplement les étapes ci-dessous avec Python (la logique reste identique pour TS, les commandes équivalentes sont précisées).
Étape 1 : Créer un dossier vide et s'y rendre
mkdir mon-agent
cd mon-agentÉtape 2 : Installer le SDK et configurer la clé
En Python (en utilisant un environnement virtuel venv) :
python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdkPour TypeScript, utilisez à la place la commande
npm install @anthropic-ai/claude-agent-sdk.
Créez ensuite un fichier .env dans le dossier mon-agent et insérez votre clé :
ANTHROPIC_API_KEY=votre-cle-d-apiRésultat attendu : La commande pip install se termine en affichant Successfully installed claude-agent-sdk-.... L'affichage de Successfully installed confirme que le SDK est installé. Si vous obtenez l'erreur No matching distribution found, c'est que votre version de Python est inférieure à 3.10, veuillez la mettre à jour (voir section 04).
Étape 3 : Créer un fichier contenant des bugs
Dans le dossier mon-agent, créez un fichier utils.py et collez-y le code suivant (il s'agit du code d'exemple officiel, contenant deux bugs provoquant des plantages) :
def calculate_average(numbers):
total = 0
for num in numbers:
total += num
return total / len(numbers)
def get_user_name(user):
return user["name"].upper()Les deux bugs sont : l'appel à calculate_average([]) avec une liste vide provoque une division par zéro ; et l'appel à get_user_name(None) génère une erreur de type TypeError.
Étape 4 : Écrire le code de l'agent
Créez un fichier agent.py et collez-y le code suivant (version d'initiation officielle avec commentaires en français) :
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage
async def main():
# Boucle d'agent : Claude génère le flux de messages au fil de ses actions
async for message in query(
prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob"], # Approbation préalable de ces outils
permission_mode="acceptEdits", # Approbation automatique des modifications de fichiers
),
):
# Affichage uniquement des messages lisibles par l'utilisateur
if isinstance(message, AssistantMessage):
for block in message.content:
if hasattr(block, "text"):
print(block.text) # Réflexion de Claude
elif hasattr(block, "name"):
print(f"Tool: {block.name}") # Outil en cours d'appel
elif isinstance(message, ResultMessage):
print(f"Done: {message.subtype}") # Résultat final
asyncio.run(main())Nous avons ajouté ici une option non détaillée à la section 05 : permission_mode="acceptEdits" — approuver automatiquement les modifications de fichiers, afin que l'agent ne s'arrête pas pour vous demander votre accord lors de la modification des fichiers (idéal pour ce type de script de confiance). La documentation officielle propose plusieurs modes de permission :
| Mode | Comportement | Cas d'usage |
|---|---|---|
acceptEdits | Approuve automatiquement les modifications de fichiers et les commandes courantes du système de fichiers, demande l'accord pour le reste | Flux de travail de développement de confiance (utilisé dans cet exemple) |
bypassPermissions | N'affiche aucune invite d'autorisation, exécute tous les outils directement | CI dans un bac à sable, environnement entièrement sécurisé |
default | Nécessite de fournir une fonction de rappel pour gérer les autorisations | Personnalisation du processus d'approbation |
dontAsk | Refuse directement tout outil non pré-approuvé, sans invite | CI verrouillée, scripts automatisés |
plan | Autorise uniquement les outils en lecture seule, Claude analyse mais ne modifie pas les fichiers | Phase de planification avant d'autoriser l'exécution |
Étape 5 : Exécuter le script
python agent.pyPour TypeScript, utilisez la commande
npx tsx agent.ts.
Résultat attendu : Le terminal affiche en continu les étapes de travail de l'agent — d'abord ses réflexions (par exemple la nécessité de lire utils.py), puis les appels d'outils comme Tool: Read et Tool: Edit, et enfin la ligne Done: success. L'affichage de Done: success confirme que l'agent a terminé.
Étape 6 : Vérification — consulter les modifications dans utils.py
Ouvrez à nouveau utils.py. Résultat attendu : Vous constaterez que l'agent a ajouté du code de protection — par exemple une vérification dans calculate_average pour renvoyer 0 (ou lever une exception explicite) si la liste est vide, et une vérification dans get_user_name pour gérer le cas où user est None ou si la clé name est absente.
C'est là tout l'intérêt de l'Agent SDK, comme le souligne la documentation officielle :
C'est ce qui rend l'Agent SDK unique : Claude exécute directement les outils plutôt que de vous demander de les implémenter.
Tout au long du processus, l'agent a agi de manière autonome : lecture de utils.py pour comprendre le code → analyse des cas de plantage potentiels → modification du fichier pour ajouter la gestion des erreurs. Vous n'avez écrit aucun code métier, l'agent s'est chargé de tout.
En réalisant ce test, vous avez mis en œuvre l'ensemble du processus : « installation du SDK → configuration de la clé → appel à query() → définition des outils et permissions → réception du flux → vérification du résultat ». La structure reste la même pour tout futur développement d'agent — il suffira de modifier le prompt, d'ajuster allowed_tools et de configurer si nécessaire les permissions et MCP.
À ce sujet, la documentation officielle suggère de tester d'autres prompts pour observer les différents comportements d'un même code : par exemple
"Add type hints to all functions in utils.py"(ajouter des indications de type) ou"Write unit tests for utils.py, run them, and fix any failures"(écrire des tests unitaires, les exécuter et corriger les échecs — cela nécessite d'ajouterBashaux outils autorisésallowed_tools).
💡 Résumé en une phrase : La mise en œuvre d'un agent d'initiation se fait en six étapes — créer le dossier, installer le SDK et configurer la clé, créer un fichier contenant des bugs, écrire le code de l'agent utilisant
query(), l'exécuter avecpython agent.py, et vérifier que le fichier a été corrigé automatiquement. Rien ne vaut la pratique pour assimiler le fonctionnement.
07 À qui s'adresse cet outil : devez-vous l'adopter dès maintenant ?
Pour être tout à fait franc : l'Agent SDK n'est pas indispensable pour tout le monde immédiatement, mais quiconque souhaite automatiser des tâches avec Claude finira par s'y intéresser. Voici de quoi vous situer afin d'éviter de vous disperser.
Commençons par les cas où il est inutile. Si vous souhaitez uniquement utiliser Claude dans votre terminal pour vous aider à écrire du code, corriger des bugs ou exécuter des commandes — contentez-vous du CLI et n'utilisez pas le SDK. Le SDK sert à appeler Claude par programmation. Sans ce besoin d'intégration logicielle, il ne ferait qu'ajouter de la complexité inutile. Certains utilisateurs se précipitent sur le SDK après avoir découvert le CLI, pour finalement se retrouver bloqués sur des concepts d'asynchronisme ou d'itérateurs asynchrones, sans avancer sur leurs tâches principales — c'est une erreur de ciblage.
Dans quels cas devriez-vous l'utiliser ? Si vous vous reconnaissez dans l'un de ces trois besoins, l'apprentissage du SDK est justifié :
| Situation | Intérêt du SDK |
|---|---|
| « Je veux juste demander à Claude d'écrire du code dans le terminal » | ❌ Le CLI suffit largement, évitez le SDK |
| « Je répète manuellement le même processus pour la Nième fois et je veux l'automatiser » | ✅ Recommandé, écrivez un script avec le SDK pour l'exécuter en arrière-plan |
| « Je veux ajouter une fonctionnalité d'IA active et autonome à mon propre produit ou service » | ✅ Recommandé, c'est l'usage principal du SDK |
| « Je veux créer un robot ou une tâche planifiée qui exécute l'agent automatiquement » | ✅ Recommandé, le CLI est mal adapté à cet usage |
La documentation officielle suggère également un parcours d'évolution classique :
Une approche courante consiste à utiliser d'abord l'Agent SDK pour le prototypage local, puis à migrer vers les Managed Agents pour la production.
Ce terme de Managed Agents (agents managés) désigne un ensemble d'API REST hébergées par Anthropic pour exécuter vos agents et bacs à sable. Votre programme se contente d'envoyer des événements et de recevoir les résultats, sans avoir à gérer l'infrastructure d'exécution ni le stockage des sessions. À l'inverse, l'Agent SDK s'exécute directement dans votre propre processus. Voici la comparaison synthétisée à partir de la documentation officielle :
| Agent SDK | Managed Agents | |
|---|---|---|
| Lieu d'exécution | Votre propre processus, votre infrastructure | Infrastructure gérée par Anthropic |
| Interface | Bibliothèque Python / TypeScript | API REST |
| Fichiers manipulés | Fichiers réels de votre machine | Bac à sable isolé pour chaque session |
| Idéal pour | Prototypage local, agents devant manipuler directement votre système de fichiers | Production, pour s'affranchir de la gestion des bacs à sable et des sessions |
Pour la majorité des utilisateurs, la démarche est claire : commencez par valider vos idées localement avec l'Agent SDK (comme à la section 06), puis envisagez de migrer vers les Managed Agents lorsque vous passerez en production avec des volumes importants et que vous souhaiterez vous affranchir de la gestion d'infrastructure. Le SDK est votre point de départ pour l'apprentissage et le prototypage, les agents managés constituent l'étape suivante pour la mise en production — pour l'instant, concentrez-vous sur la maîtrise de l'Agent SDK.
Dernier point : automatiser des processus manuels répétitifs avec des scripts basés sur le SDK — par exemple, analyser chaque semaine les dépendances obsolètes de plusieurs dépôts et générer automatiquement un rapport synthétique. La satisfaction de voir, le lendemain matin, un rapport généré automatiquement par un outil autonome que l'on a soi-même conçu est une expérience que le CLI ne peut pas vous offrir. Si vous faites face à des tâches manuelles répétitives, c'est le moment de vous tourner vers le SDK.
💡 Résumé en une phrase : Utilisation simple de Claude dans le terminal → CLI ; besoin d'automatiser un processus répétitif ou d'intégrer un agent actif dans un produit → SDK. La démarche recommandée est de débuter localement avec l'Agent SDK, puis de migrer vers les Managed Agents pour les besoins de production.
08 Synthèse
Dans cet article, nous avons exploré la « face cachée » de Claude Code — la possibilité d'intégrer son noyau sous forme de bibliothèque dans votre propre code via l'Agent SDK.
Récapitulatif des points clés :
| Question | Réponse | Point clé |
|---|---|---|
| Qu'est-ce que l'Agent SDK | Le noyau de Claude Code sous forme de bibliothèque | Outils, boucle d'agent et gestion de contexte programmables |
| Relation avec le CLI | Même noyau, deux entrées | CLI interactif pour l'humain, SDK pour l'appel par programme ; concepts partagés |
| Différence avec l'API brute | Responsabilité de la boucle d'outils | L'API brute nécessite d'implémenter la boucle while, le SDK la gère pour vous |
| Choix du langage | Selon le langage de votre projet | TS (Node 18+) ou Python (3.10+), fonctionnalités équivalentes |
| Point d'entrée | query() | Prend en charge le prompt et les options, renvoie un flux de messages |
| Intérêt d'apprentissage | Selon votre besoin d'automatisation/intégration | Inutile pour un usage exclusif du CLI, recommandé pour l'automatisation |
Vous êtes désormais capable de : expliquer simplement le rôle de l'Agent SDK, distinguer le SDK du CLI comme deux entrées d'un même noyau, différencier le SDK de l'API brute par la gestion de la boucle d'outils, choisir et installer la version TS ou Python appropriée, comprendre le fonctionnement de l'appel minimal à query() et mettre en œuvre un agent d'initiation capable de corriger un bug de manière autonome. Et surtout, vous savez s'il est opportun pour vous de commencer à l'utiliser.
Votre vision de Claude Code dépasse désormais le cadre du simple outil en ligne de commande pour englober un ensemble de capacités d'agent programmables et intégrables. Ce n'est plus seulement un outil à utiliser, c'est un composant pour vos propres créations.
L'article suivant 46 « Configuration de développement » aborde les aspects pratiques du développement d'agents au-delà du simple appel à query() : gestion sécurisée des clés d'API, distinction des configurations selon les environnements (développement / production), configuration des variables d'environnement pour l'utilisation de fournisseurs de modèles tiers... Toutes ces étapes de préparation indispensables y seront détaillées. Un agent fonctionnel en local mais incapable de contacter le modèle sur un serveur de production est souvent le signe d'un défaut de configuration — cet article vous évitera ces désagréments.