Le Claude Agent SDK

Jusqu'ici, le cours a présenté Claude Code en mode interactif, dans le terminal. Le Claude Agent SDK ouvre une autre voie : utiliser la même mécanique depuis votre propre code, en Python ou en TypeScript, pour construire des agents qui travaillent sans humain devant l'écran. Les informations de cette leçon ont été vérifiées sur la documentation officielle de Claude Code (section « Agent SDK ») le 23 septembre 2026.

Du SDK Claude Code au Claude Agent SDK

Le produit s'appelait auparavant « SDK Claude Code ». Anthropic l'a renommé Claude Agent SDK pour refléter un usage qui dépasse le code : un agent de recherche, d'assistance ou de traitement documentaire repose sur la même boucle. Les paquets ont changé de nom en conséquence :

Si vous tombez sur un tutoriel qui utilise les anciens noms, il date d'avant ce changement.

Le principe : la boucle agentique en bibliothèque

Le SDK reprend la boucle qui fait fonctionner Claude Code :

1. Claude reçoit votre consigne, le prompt système et la liste des outils ;
2. il répond par du texte, des demandes d'appels d'outils, ou les deux ;
3. le SDK exécute les outils demandés et renvoie les résultats à Claude ;
4. le cycle recommence jusqu'à une réponse sans appel d'outil ;
5. le SDK émet un message de résultat avec le texte final, l'usage de tokens, le coût et l'identifiant de session.

Différence majeure avec un appel classique à l'API : vous n'écrivez pas vous-même cette boucle. Claude exécute les outils directement, au lieu de vous demander de les implémenter.

Un premier agent

Voici un agent TypeScript qui relit un fichier et corrige les bugs qu'il trouve. Les noms utilisés (query, allowedTools, permissionMode, maxTurns) sont ceux de la documentation officielle :

import { query } from "@anthropic-ai/claude-agent-sdk";
 
for await (const message of query({
  prompt:
    "Relis src/panier.ts, repère les cas qui font planter le calcul du total et corrige-les.",
  options: {
    allowedTools: ["Read", "Edit", "Glob"],
    permissionMode: "acceptEdits",
    maxTurns: 20,
  },
})) {
  if (message.type === "result") {
    console.log(message.subtype);
  }
}

query() renvoie un itérateur asynchrone : chaque message correspond à une étape de la boucle (initialisation, texte de Claude, appel d'outil, résultat d'outil), et le dernier est de type result. Son champ subtype vaut success si la tâche a abouti, ou un code d'erreur si une limite a été atteinte. En Python, la même fonction s'importe depuis claude_agent_sdk. Le SDK s'authentifie avec la variable d'environnement ANTHROPIC_API_KEY.

Ce que le SDK apporte

La documentation liste les capacités de Claude Code disponibles dans le SDK :

• outils intégrés : Read, Edit, Write, Glob, Grep, Bash, WebSearch, WebFetch, et des outils d'orchestration ;
• permissions : allowedTools pré-approuve des outils, disallowedTools en interdit, et un mode de permission fixe le niveau de supervision (le mode plan explore sans modifier les fichiers) ;
• hooks : des fonctions de votre application appelées à des moments clés, par exemple PreToolUse pour bloquer une commande dangereuse avant son exécution, ou PostToolUse pour auditer un résultat ;
• sous-agents : l'agent principal délègue une sous-tâche à un agent spécialisé qui démarre avec un contexte neuf et ne renvoie que sa réponse finale (voir la leçon Les sous-agents et la notion de sous-agent) ;
• sessions : l'identifiant de session permet de reprendre une conversation plus tard avec tout son contexte, ou de la dupliquer pour tester une autre approche ;
• MCP, skills et mémoire : serveurs MCP, skills et fichiers CLAUDE.md se chargent comme dans Claude Code.

Les garde-fous en mode programmatique

Sans humain pour valider chaque action, l'encadrement devient critique :

• limitez les outils au strict nécessaire : un agent d'analyse n'a besoin que de Read, Glob et Grep ;
• plafonnez la boucle avec maxTurns et un budget maximal, pour éviter qu'une consigne trop ouverte tourne longtemps ;
• traitez tous les résultats : vérifiez le subtype avant d'utiliser la réponse, et prévoyez les erreurs d'exécution ;
• isolez l'environnement : le mode qui contourne toutes les permissions est réservé à la CI, aux conteneurs ou aux environnements isolés.

SDK, CLI ou API : que choisir ?

• La CLI interactive pour le travail exploratoire au quotidien ;
• la CLI en mode non interactif (claude -p) pour un script shell ou une étape de CI simple ;
• le Claude Agent SDK pour intégrer un agent complet dans une application Python ou TypeScript que vous exploitez ;
• le SDK client de l'API si vous voulez tout contrôler et écrire vous-même la boucle d'outils.

En résumé

Le Claude Agent SDK transforme Claude Code en brique logicielle : une fonction query(), un flux de messages, et les mêmes outils, hooks, sous-agents et sessions que dans le terminal. La leçon suivante l'applique à l'automatisation CI/CD. Retrouvez aussi la certification Certified Architect.