Qu'est-ce que le Claude Agent SDK ? Guide complet du développement d'agents IA

« Si seulement l'IA pouvait recevoir mes instructions puis réfléchir et travailler de manière autonome... » C'est exactement ce que permet un agent IA. Le Claude Agent SDK, fourni par Anthropic, est une bibliothèque qui permet de construire des agents IA en Python ou TypeScript en utilisant Claude comme cerveau. Il met à la disposition de vos propres programmes les mêmes outils, la même boucle d'agent et la même gestion du contexte que celles qui font tourner Claude Code, l'agent de programmation officiel d'Anthropic.

Dans cet article, nous allons explorer de manière structurée les concepts fondamentaux du Claude Agent SDK, les méthodes d'implémentation et les cas d'utilisation.

Qu'est-ce qu'un agent IA ?

Un agent IA diffère de l'IA traditionnelle de type « question → réponse ». Sa particularité est de décomposer les tâches de manière autonome, utiliser des outils, évaluer les résultats et décider de l'action suivante.

Par exemple, si vous demandez « corrige le bug dans auth.py », l'agent procède ainsi :

1. Lire le fichier pour comprendre le code
2. Rechercher les fichiers associés pour avoir une vue d'ensemble
3. Identifier la cause du bug
4. Corriger le code
5. Exécuter les tests pour vérifier le bon fonctionnement
6. Faire un rapport des résultats

Sans intervention humaine, l'agent décide et effectue lui-même toutes ces étapes. Voilà la puissance d'un agent.

Présentation du Claude Agent SDK

Le Claude Agent SDK est la bibliothèque officielle d'Anthropic pour construire des agents. La documentation officielle le décrit comme une bibliothèque qui exécute le binaire de Claude Code. Autrement dit, c'est le SDK qui pilote Claude Code, et non l'inverse. Les SDK Python et TypeScript embarquent ce binaire : dans la plupart des environnements, il n'est donc pas nécessaire d'installer Claude Code séparément.

Voici ses principales caractéristiques :

L'Agent SDK sert à intégrer l'agent qui fonctionne dans Code (Claude Code) de Claude à vos propres applications et scripts, en dehors de cette interface.

Comment fonctionne la boucle d'agent

Le cœur de l'Agent SDK est la boucle d'agent. C'est un mécanisme qui exécute automatiquement le cycle « Claude réfléchit, utilise un outil, vérifie le résultat, puis réfléchit à nouveau ».

Voici le déroulement détaillé :

1. Réception du prompt : les instructions de l'utilisateur sont transmises à Claude
2. Décision de Claude : analyse les instructions et détermine l'action nécessaire
3. Exécution d'outils : appelle des outils comme Bash, Edit, Read pour effectuer le travail
4. Traitement des résultats : renvoie les résultats d'exécution à Claude
5. Continuation ou fin de la boucle : s'il reste du travail, retour à l'étape 2. Si c'est terminé, une réponse textuelle est renvoyée

Le point essentiel est que la boucle se termine quand il n'y a plus d'appels d'outils. Lorsque Claude juge qu'aucun outil n'est plus nécessaire, la réponse textuelle finale est renvoyée.

Premiers pas : installation et code de base

Installation

Disponible en Python ou TypeScript.

# Python
pip install claude-agent-sdk

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

Il faut Node.js 18 ou plus récent, ou Python 3.10 ou plus récent (guide de démarrage officiel).

Authentification : utilisez une clé API (pas une connexion claude.ai)

Le SDK fonctionne avec la clé API définie dans la variable d'environnement ANTHROPIC_API_KEY. Pour passer par Amazon Bedrock, Google Cloud (la version opérée par Google) ou Microsoft Foundry, définissez CLAUDE_CODE_USE_BEDROCK=1, CLAUDE_CODE_USE_VERTEX=1 ou CLAUDE_CODE_USE_FOUNDRY=1 et configurez les identifiants de ce cloud. Le SDK ne charge pas automatiquement les fichiers .env : définissez la variable dans le shell où tourne l'agent. La configuration et les tarifs de Claude sur Google Cloud sont détaillés dans Utiliser Claude sur Vertex AI.

Attention à la connexion claude.ai (abonnements Pro, Max, etc.). Sauf accord préalable, la documentation officielle n'autorise pas les développeurs tiers à proposer dans leurs produits la connexion ou les limites d'usage de claude.ai, y compris pour les agents construits avec l'Agent SDK. Les applications que vous créez avec le SDK doivent s'authentifier avec une clé API.

Agent minimal (Python)

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async def main():
    async for message in query(
        prompt="Trouve et corrige le bug dans src/auth.py",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Bash", "Grep"],
            max_turns=30,
        ),
    ):
        if isinstance(message, ResultMessage):
            if message.subtype == "success":
                print(message.result)
            if message.total_cost_usd is not None:
                print(f"Coût : ${message.total_cost_usd:.4f}")

asyncio.run(main())

Agent minimal (TypeScript)

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

for await (const message of query({
  prompt: "Trouve et corrige le bug dans src/auth.py",
  options: {
    allowedTools: ["Read", "Edit", "Bash", "Grep"],
    maxTurns: 30,
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Avec ce simple code, Claude lit les fichiers, cherche le bug, le corrige et fait un rapport du résultat. Attention toutefois : allowed_tools n'est pas la liste des outils que Claude a le droit d'utiliser, mais la liste des outils approuvés automatiquement, sans demande de confirmation. Comme cet exemple inclut Bash, les commandes shell choisies par Claude s'exécutent sans confirmation (à l'exception de quelques actions, comme certaines suppressions, qu'aucun réglage n'approuve automatiquement). Comme cet exemple ne fixe pas permission_mode, le mode vient de permissions.defaultMode dans vos fichiers de réglages ou, à défaut, de la valeur par défaut intégrée, qui était auto depuis la v2.1.285 dans les sessions qui ne récupèrent pas les feature flags, par exemple avec un fournisseur tiers (Bedrock, Google Cloud, Microsoft Foundry) ou avec la télémétrie désactivée (documentation officielle). Toutefois, depuis la v2.1.302 (16 octobre 2026), les sessions de l'Agent SDK et de claude -p qui ne précisent pas de mode de permission démarrent en default, y compris lorsqu'elles passent par un fournisseur tiers. Pour utiliser le mode auto, il faut le demander explicitement (en CLI : --permission-mode auto ; journal des modifications, vérifié le 18 octobre 2026). Le mode auto écarte les règles d'autorisation larges comme Bash : si vous comptez sur le comportement ci-dessus, passez explicitement permission_mode="default" (TS : permissionMode: "default") (documentation officielle). Testez-le dans un répertoire de travail que vous pouvez vous permettre d'abîmer. La section suivante explique comment restreindre réellement les outils.

Liste des outils intégrés

L'Agent SDK propose de nombreux outils prêts à l'emploi, sans avoir à écrire de code.

Vous n'avez pas besoin d'écrire de code de traitement pour utiliser les outils intégrés. L'essentiel est que « quels outils Claude voit » et « quels outils s'exécutent sans confirmation » sont deux réglages distincts. Voici ce qu'en dit la documentation officielle :

Par exemple, combiner allowed_tools=["Read"] avec permission_mode="bypassPermissions" approuve tout, y compris Bash, Write et Edit, pourtant absents de la liste (la documentation officielle met explicitement en garde contre cette combinaison). Pour mettre un outil hors de portée, retirez-le avec tools ou disallowed_tools. Pour travailler uniquement avec un ensemble fixe d'outils, associez allowed_tools à permission_mode="dontAsk", qui refuse tout ce qui demanderait sinon une confirmation.

Autre détail : sous macOS, Linux et WSL, Glob et Grep ne font pas partie des outils par défaut (ils en font partie sous Windows). Claude cherche alors avec find et grep via l'outil Bash. Nommer l'un ou l'autre dans tools ou allowed_tools les rend de nouveau disponibles (référence officielle des outils).

Créer des outils personnalisés

Si les outils intégrés ne suffisent pas, vous pouvez créer vos propres outils. Voyons par exemple comment créer un outil connecté à une API météo.

Version Python

from claude_agent_sdk import tool, create_sdk_mcp_server

@tool(
    "get_weather",
    "Obtenir la météo actuelle d'une ville donnée",
    {"city": str}
)
async def get_weather(args: dict) -> dict:
    city = args["city"]
    # En pratique, on appelle l'API
    weather_data = await fetch_weather_api(city)
    return {
        "content": [
            {"type": "text", "text": f"Météo à {city} : {weather_data}"}
        ]
    }

weather_server = create_sdk_mcp_server(
    name="weather",
    version="1.0.0",
    tools=[get_weather]
)

Version TypeScript

import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const getWeather = tool(
  "get_weather",
  "Obtenir la météo actuelle d'une ville donnée",
  { city: z.string().describe("Nom de la ville") },
  async (args) => {
    const data = await fetchWeatherApi(args.city);
    return {
      content: [{ type: "text", text: `Météo à ${args.city} : ${data}` }]
    };
  }
);

Les outils personnalisés sont créés en tant que serveurs MCP et transmis à l'agent via mcp_servers (TS : mcpServers). Le nom complet de chaque outil devient mcp__nom-du-serveur__nom-de-l-outil ; pour qu'il s'exécute sans confirmation, ajoutez ce nom à allowed_tools :

options=ClaudeAgentOptions(
    mcp_servers={"weather": weather_server},
    allowed_tools=["mcp__weather__get_weather"],
)

Si votre outil lève une exception, la boucle de l'agent ne s'arrête pas. Le serveur MCP du SDK l'intercepte et transmet tel quel le message de l'exception à Claude, sous forme de résultat d'erreur. Si vous interceptez l'erreur vous-même et renvoyez "is_error": True (TypeScript : isError: true), vous rédigez le message que lit Claude : quelle requête a échoué, et quoi essayer à la place. Dans les deux cas, Claude peut réessayer, passer par un autre outil ou expliquer l'échec (documentation officielle : outils personnalisés).

Traitement parallèle avec les sous-agents

Pour les tâches volumineuses, il est efficace de les diviser en sous-agents exécutés en parallèle. On peut ainsi déléguer des tâches spécialisées à d'autres agents sans polluer le contexte (la mémoire) de l'agent principal.

Quand les sous-agents sont-ils utiles ?

• Exécution de nombreux tests : même si les logs de résultats sont volumineux, le contexte principal n'est pas affecté
• Recherche en parallèle : examiner plusieurs modules simultanément et ne recevoir que les résultats
• Séparation des tâches spécialisées : confier la « revue de code » et l'« exécution des tests » à des agents distincts

Sous-agents personnalisés dans Claude Code

Dans Claude Code (CLI), il suffit de placer un fichier Markdown dans .claude/agents/ pour définir un sous-agent personnalisé.

# .claude/agents/reviewer.md
---
name: code-reviewer
description: Agent spécialisé en revue de code
tools: Read, Glob, Grep
model: sonnet
---

Vous êtes un réviseur de code senior.
Effectuez une revue du point de vue de la qualité
du code, de la sécurité et des bonnes pratiques.

En limitant l'accès aux outils (dans l'exemple ci-dessus, uniquement les outils de lecture), on évite que le réviseur modifie accidentellement le code.

Permissions, hooks et sessions

Ce sont ces trois éléments qui comptent le plus lorsqu'un agent passe en production. La documentation officielle les cite tous parmi les fonctionnalités de Claude Code disponibles dans le SDK.

Permissions : chaque appel est évalué dans un ordre fixe

Quand Claude demande un outil, le SDK évalue hooks → règles de refus → règles de confirmation → mode de permission → règles d'autorisation → le callback can_use_tool, dans cet ordre. Un appel qui correspond à une règle de refus (issue de disallowed_tools, par exemple) est bloqué même en mode bypassPermissions. Une exception : un mod (un plugin dont les hooks sont des fonctions) s'exécute aussi dans les sessions de l'Agent SDK qui le chargent (documentation officielle), et un mod qui répond à tool.check peut approuver un appel qu'une règle de refus a rejeté, sauf sur les machines dotées de réglages gérés ou avec une connexion à un forfait Team ou Enterprise (documentation officielle). N'installez que des mods d'auteurs de confiance ; pour en savoir plus, voir les mods de Claude Code expliqués. Le mode se choisit avec permission_mode (d'après la documentation officielle en septembre 2026) :

Hooks : exécuter votre propre code aux moments clés

Les hooks sont des callbacks déclenchés par des événements comme l'avant-exécution d'un outil (PreToolUse), l'après-exécution (PostToolUse) ou l'arrêt de l'exécution (Stop). Ils passent avant l'évaluation des permissions : une action que vous voulez bloquer dans tous les modes se place donc ici. Cet exemple, abrégé à partir de la documentation officielle, bloque l'écriture dans les fichiers .env :

from claude_agent_sdk import ClaudeAgentOptions, HookMatcher

async def protect_env_files(input_data, tool_use_id, context):
    file_path = input_data["tool_input"].get("file_path", "")
    if file_path.split("/")[-1] == ".env":
        return {
            "hookSpecificOutput": {
                "hookEventName": input_data["hook_event_name"],
                "permissionDecision": "deny",
                "permissionDecisionReason": "Cannot modify .env files",
            }
        }
    return {}

options = ClaudeAgentOptions(
    hooks={"PreToolUse": [HookMatcher(matcher="Write|Edit", hooks=[protect_env_files])]}
)

Sessions : reprendre là où vous vous étiez arrêté, ou bifurquer

Le SDK enregistre automatiquement sur disque l'historique de la conversation (prompts, appels d'outils, résultats et réponses) sous forme de session. Conservez le session_id du message de résultat et passez-le à resume lors du query() suivant : l'agent reprend en tenant compte des fichiers déjà lus et des décisions déjà prises. Pour reprendre la session la plus récente, utilisez continue_conversation=True (TS : continue: true) ; pour tester une autre approche sans toucher à l'original, fork_session=True (TS : forkSession: true). Les sessions ne conservent que la conversation : les modifications de fichiers ne sont pas annulées (documentation officielle : sessions).

Par ailleurs, les skills, les commandes et la mémoire présentes dans le dossier .claude/ de votre projet et dans ~/.claude/ sont chargées automatiquement, comme dans Claude Code. Les plugins, qui regroupent skills, agents, hooks et serveurs MCP, peuvent être chargés depuis un chemin local.

Agent SDK vs Client SDK vs Claude Code

La comparaison officielle recense quatre façons de construire avec Claude : l'Agent SDK, la CLI Claude Code, le Client SDK et Managed Agents. Commençons par les trois que vous exécutez sur votre propre machine ou vos serveurs.

Comment choisir :

• Travail de développement quotidien → Claude Code CLI
• Construire un système automatisé → Agent SDK
• Créer votre propre application IA → Client SDK
• Déléguer aussi l'exploitation de la boucle et du bac à sable → Managed Agents (un agent hébergé par Anthropic qui exécute les sessions dans un bac à sable cloud géré par Anthropic ou dans un bac à sable auto-hébergé, et qu'on utilise via le SDK de son langage, la CLI ant ou l'API REST)

Cas d'utilisation pratiques

Automatisation du développement de code

L'utilisation la plus courante. Quand vous dites « implémente cette fonctionnalité », l'agent examine la structure des fichiers, écrit le code et exécute même les tests.

# Automatisation de la correction de bugs
async for msg in query(
    prompt="Les tests du module d'authentification échouent. Trouve la cause et corrige",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Edit", "Bash", "Grep"],
        max_turns=20,
        max_budget_usd=2.00,  # Limite de coût à 2$
    ),
):
    pass

Intégration dans un pipeline CI/CD

En combinant avec GitHub Actions par exemple, vous pouvez créer des workflows qui effectuent automatiquement une revue de code à chaque PR, ou qui tentent une correction automatique en cas d'échec des tests.

Analyse de données et recherche

Des tâches de recherche nécessitant plusieurs étapes comme « analyse les patterns d'erreur dans les logs du dernier mois » peuvent aussi être confiées à l'agent. En combinant avec l'outil WebSearch, les informations les plus récentes peuvent également être intégrées.

Bonnes pratiques

1. N'oubliez pas le contrôle des coûts

L'agent fonctionne en boucle, ce qui peut consommer plus de tokens que prévu. Configurez toujours max_budget_usd ou max_turns.

options=ClaudeAgentOptions(
    max_budget_usd=5.00,   # Arrêt à 5$
    max_turns=30,           # Arrêt après 30 tours
    effort="medium",        # Profondeur du raisonnement (low/medium/high/xhigh/max)
)

xhigh est traité comme high sur les modèles qui ne le prennent pas en charge. Lorsqu'une limite met fin à l'exécution, le message de résultat final a pour subtype "error_max_budget_usd" pour max_budget_usd ou "error_max_turns" pour max_turns, et result est vide (None). Consultez subtype pour savoir pourquoi l'agent s'est arrêté.

Gardez à l'esprit que ce montant est une estimation calculée par le SDK à partir d'une grille tarifaire embarquée, et non votre facture réelle. Le budget ne compte que les dépenses de l'appel lui-même : ce qui a déjà été dépensé dans une session reprise avec resume n'est pas inclus. Pour des chiffres faisant foi, utilisez la page Usage de la Claude Console ou l'API Usage and Cost (documentation officielle : suivi des coûts).

2. Limitez les outils au minimum

Pour que Claude ne voie pas les outils inutiles, listez seulement ceux dont vous avez besoin dans tools, ou retirez-les par leur nom dans disallowed_tools. allowed_tools ne fait que supprimer la demande de confirmation ; il ne réduit pas les outils disponibles. Limitez aussi la liste d'approbation automatique au strict nécessaire pour la tâche.

3. Signalez les erreurs des outils avec is_error

Une exception dans un outil personnalisé n'arrête pas la boucle de l'agent : le SDK transmet le message de l'exception à Claude sous forme de résultat d'erreur. Mais un message d'exception brut ne suffit pas toujours à Claude pour décider de la suite. Interceptez-la vous-même et renvoyez "is_error": True (TypeScript : isError: true) avec ce qui a échoué et ce qu'il faut essayer à la place : Claude pourra se rétablir plus facilement.

4. Déléguez les traitements lourds aux sous-agents

Confiez aux sous-agents les traitements à sortie volumineuse comme l'exécution de tests ou l'analyse de logs. Cela évite de surcharger le contexte de l'agent principal.

5. Soyez précis dans vos prompts

Plutôt que « améliore le code », dites « ajoute un rate limiting à la fonction de login dans auth.py et écris les tests ». Des instructions précises permettent à l'agent de travailler efficacement.

Résumé

Le Claude Agent SDK est un framework qui réduit considérablement la barrière d'entrée au développement d'agents IA. En utilisant le même moteur que Claude Code, vous pouvez construire en Python ou TypeScript des agents capables d'exécuter des tâches de manière autonome.

Commencez par expérimenter le fonctionnement d'un agent de manière interactive avec Claude Code, puis passez à l'Agent SDK lorsque le besoin d'automatisation se fait sentir — c'est l'approche progressive recommandée.

Si vous préférez ne pas gérer vous-même la boucle, le sandbox et l'état, l'alternative entièrement managée d'Anthropic est Claude Managed Agents.

Pour découvrir les bases de Claude, consultez également Chat, Cowork et Code dans Claude.