L'Agent SDK

Le Claude Agent SDK (anciennement SDK Claude Code) vous permet d’exécuter Claude Code de façon programmatique depuis vos propres applications et scripts, en Python et en TypeScript. Il donne les mêmes outils, la même boucle agentique et la même gestion du contexte que le terminal, intégrés dans des workflows plus larges : un hook Git qui relit les changements avant un commit, une tâche de CI qui vérifie une convention qu’aucun linter ne sait exprimer, un générateur de documentation, un agent métier qui lit des fichiers et appelle des outils.

Un malentendu mérite d’être levé tout de suite. Le SDK n’est ni une version allégée ni un client API de bas niveau : il exécute le même binaire Claude Code que votre terminal, qu’il embarque dans son paquet. Si vous voulez seulement appeler l’API Claude depuis votre code, c’est le Client SDK de la plateforme qu’il vous faut ; si vous voulez qu’Anthropic héberge l’agent, ce sont les Managed Agents. Et pour un langage autre que Python ou TypeScript, lancez le CLI en sous-processus avec claude -p "…" --output-format json.

Installer et s’authentifier

Il faut Node.js 18.14 ou Python 3.10 au minimum :

# TypeScript
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx

# Python
uv add claude-agent-sdk      # ou : pip install claude-agent-sdk

Le SDK lit une clé d’API de la Claude Console dans la variable ANTHROPIC_API_KEY de l’environnement du processus ; il ne charge pas les fichiers .env tout seul. Il accepte aussi Amazon Bedrock (CLAUDE_CODE_USE_BEDROCK=1), Agent Platform de Google Cloud (CLAUDE_CODE_USE_VERTEX=1) et Microsoft Foundry (CLAUDE_CODE_USE_FOUNDRY=1). Un point de licence est à connaître : sauf accord préalable, Anthropic n’autorise pas un produit tiers bâti sur le SDK à proposer la connexion claude.ai ni ses limites d’usage à ses utilisateurs ; un tel produit s’authentifie par clé d’API.

Utilisation de base

L’exemple officiel construit un agent qui trouve et corrige des bugs dans un fichier. Voici sa version TypeScript, dans agent.ts :

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Review utils.py for bugs that would cause crashes. Fix any issues you find.",
  options: {
    allowedTools: ["Read", "Edit", "Glob"],
    permissionMode: "acceptEdits"
  }
})) {
  if (message.type === "assistant" && message.message?.content) {
    for (const block of message.message.content) {
      if ("text" in block) console.log(block.text);
      else if ("name" in block) console.log(`Tool: ${block.name}`);
    }
  } else if (message.type === "result") {
    console.log(`Done: ${message.subtype}`);
  }
}

Et la même chose en Python, dans agent.py :

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async def main():
    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"],
            permission_mode="acceptEdits",
        ),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")

asyncio.run(main())

Lancez avec npx tsx agent.ts ou uv run agent.py. Trois éléments structurent le code. query est le point d’entrée qui crée la boucle agentique ; il renvoie un itérateur asynchrone, d’où le for await. prompt dit ce que vous voulez ; Claude choisit ses outils. options configure l’agent : ici, trois outils pré-approuvés et le mode acceptEdits pour que les modifications de fichiers passent sans confirmation. La boucle livre un message à chaque étape : le raisonnement, un appel d’outil, son résultat, puis l’issue finale, et vous réagissez en cours de route au lieu d’attendre la fin.

Permissions

C’est le point qui change le plus par rapport aux anciennes versions. Depuis la version 2.1.302 de Claude Code, un agent SDK (comme claude -p) démarre en mode default, le mode Manual, et refuse tout appel d’outil qui exigerait une confirmation tant que personne ne l’a approuvé. Un script d’analyse en lecture seule fonctionne tel quel, puisque les lectures ne demandent rien ; dès qu’il doit écrire ou lancer une commande, vous devez le dire. Quatre moyens : une liste allowedTools qui nomme les outils ou des règles comme Bash(npm test) ; un mode de permission (acceptEdits, auto, où un classifieur examine chaque action, ou bypassPermissions, réservé aux conteneurs isolés) ; un hook PreToolUse ; ou un rappel canUseTool qui reçoit chaque demande et décide dans votre code. Les règles deny s’appliquent même en bypassPermissions, et disallowedTools retire un outil tout à fait.

Le geste est délibérément explicite : vous n’ouvrez pas les droits en bloc, vous nommez ce que vous acceptez de confier à ce script précis.

Ce que le SDK hérite

Lancé depuis la racine du projet, le SDK charge tout ce qu’une session interactive chargerait : CLAUDE.md, les skills et commandes de .claude/, les serveurs MCP, les hooks des fichiers de réglages, la mémoire. Un script travaille donc avec le même contexte que votre terminal, ce qui supprime les écarts entre ce que vous testez à la main et ce que votre pipeline exécute la nuit. Attention à l’autre face de cette propriété : les hooks d’un dépôt que vous ne connaissez pas s’exécutent aussi, sans dialogue de confiance en mode non interactif. Avant de scripter sur un dépôt tiers, relisez son dossier .claude/, ou démarrez avec --bare.

Le SDK expose aussi des sessions pour les conversations en plusieurs tours (ClaudeSDKClient en Python), des hooks écrits comme des fonctions de votre langage, des sous-agents, des outils personnalisés, des sorties structurées validées par un schéma JSON, et le suivi des coûts. La page Hosting the Agent SDK couvre le déploiement en conteneur, en CI et dans le cloud.

Applications pratiques

Un hook Git est un candidat naturel : le SDK relit les changements avant un commit et refuse ceux qui ne tiennent pas la route. En CI, il ajoute des vérifications que les linters ne savent pas exprimer, parce qu’elles supposent de comprendre l’intention et pas seulement la syntaxe. Il génère de la documentation à partir des sources, cette tâche que personne ne fait spontanément. Et c’est lui qui fait tourner, au fond, l’intégration GitHub de la leçon 11. La bonne question n’est pas « que sait faire le SDK », puisqu’il sait faire tout ce que fait Claude Code, mais « quelle tâche répétitive de mon pipeline mériterait un lecteur attentif ».

À vous de jouer

1. Créez un dossier my-agent, installez le SDK de votre langage et exportez ANTHROPIC_API_KEY.
2. Créez utils.py avec une fonction calculate_average(numbers) qui divise par len(numbers) sans tester la liste vide, puis lancez l’agent ci-dessus. Ouvrez utils.py : la garde a été ajoutée.
3. Retirez permissionMode et relancez : observez que les modifications sont refusées. Remettez-le.
4. Ajoutez Bash aux outils et demandez : « Write unit tests for utils.py, run them, and fix any failures. »

Sources officielles : Agent SDK overview · Quickstart · Configure permissions · Migrate to Claude Agent SDK

Points clés à retenir

• Paquets @anthropic-ai/claude-agent-sdk (npm) et claude-agent-sdk (PyPI), qui embarquent le binaire Claude Code ; clé d’API dans ANTHROPIC_API_KEY
• query() renvoie un flux de messages ; options fixe les outils autorisés et le mode de permission
• Depuis la 2.1.302, un agent démarre en mode default et refuse ce qui demanderait confirmation : nommez les outils dans allowedTools ou choisissez un mode
• Le SDK hérite de CLAUDE.md, des skills, des serveurs MCP et des hooks du projet, y compris sur un dépôt que vous n’avez pas relu
• Hooks Git, CI, documentation, agents métier : partout où un accès programmatique à Claude Code serait utile