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 un framework qui permet de construire des agents IA en Python ou TypeScript en utilisant Claude comme cerveau. C'est d'ailleurs la même technologie qui fait tourner Claude Code (la CLI officielle 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 le framework officiel de développement d'agents fourni par Anthropic. Il permet d'utiliser de manière programmatique le même moteur qui fait tourner Claude Code.

Voici ses principales caractéristiques :

Parmi les trois modes de Claude : Chat, Cowork et Code, c'est le mode Claude Code qui repose sur la technologie de l'Agent SDK.

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

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)
            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.

Liste des outils intégrés

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

Il suffit de spécifier les autorisations dans allowed_tools pour utiliser ces outils. Vous n'avez pas besoin d'écrire le code de traitement des outils vous-même.

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 connectés à l'agent. En cas d'erreur, il est important de retourner isError: true plutôt que de lever une exception. Ainsi, la boucle de l'agent ne s'arrête pas et Claude peut tenter une nouvelle approche.

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.

Agent SDK vs Client SDK vs Claude Code

Claude dispose de trois interfaces destinées aux développeurs. Chacune a ses points forts, choisissez en fonction de votre objectif.

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

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/max)
)

2. Limitez les outils au minimum

Autoriser des outils inutilisés consomme inutilement la fenêtre de contexte. Ne spécifiez dans allowed_tools que les outils nécessaires à la tâche.

3. Gérez les erreurs avec isError

Si une exception est levée dans un outil personnalisé, toute la boucle de l'agent s'arrête. Retournez plutôt isError: true pour que Claude puisse tenter une récupération.

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.

Pour découvrir les bases de Claude, consultez également Comparaison détaillée des trois onglets de Claude : Chat, Cowork et Code.