Un agent IA n'est pas un assistant plus intelligent. C'est un programme qui appelle Claude en boucle, exécute les outils qu'il réclame, réinjecte les résultats, et continue jusqu'à ce que la tâche soit finie. Le Claude Agent SDK est la bibliothèque officielle d'Anthropic qui gère cette boucle à ta place. Si tu as déjà exploré Claude via l'interface ou les Projects et que tu veux passer à l'exécution autonome, c'est l'outil à comprendre avant de briefer ton équipe ou un prestataire. Ce guide complet pour apprendre Claude couvre les fondamentaux ; ici on entre dans la couche agentique.
L'objectif de cet article : te donner les critères d'arbitrage (quand un agent se justifie, quel modèle choisir, combien ça coûte) et te montrer un premier agent en Python qui tient en une trentaine de lignes. Pas de tutoriel exhaustif, pas de storytelling. Une vue produit sur ce que le SDK change concrètement.
Qu'est-ce que le Claude Agent SDK
Le Claude Agent SDK est une bibliothèque officielle Anthropic disponible en Python (pip install claude-agent-sdk) et en TypeScript (npm install @anthropic-ai/claude-agent-sdk). Il s'agit de l'évolution du Claude Code SDK, renommé en septembre 2025 pour élargir le périmètre au-delà de la génération de code : automatisation métier, extraction documentaire, orchestration d'outils internes.
La différence avec un appel brut à l'endpoint /v1/messages de l'API Anthropic est architecturale, pas cosmétique. Sans SDK, tu écris toi-même la boucle : tu envoies un message, tu récupères une réponse qui contient éventuellement un tool_use block, tu exécutes l'outil, tu formates le résultat en tool_result, tu réinjectes tout l'historique dans le prochain appel, tu gères les erreurs et les timeouts. Compte plusieurs centaines de lignes pour un agent robuste. Avec le SDK, une fonction query() encapsule tout ça, et ton code se concentre sur ce qui est spécifique à ton cas : le system prompt, les outils personnalisés, les garde-fous.
Agent vs assistant : ce qui change vraiment
Un assistant conversationnel comme Claude.ai ou Claude Projects attend une question, répond, attend la suivante. L'humain reste dans la boucle à chaque tour. Un agent tourne sans intervention entre le prompt initial et le résultat final. Il décide quand appeler quel outil, comment enchaîner, quand s'arrêter.
Trois critères pour décider si tu as besoin d'un agent plutôt que d'un assistant :
| Critère | Assistant suffit | Agent nécessaire |
|---|---|---|
| Nombre d'étapes | 1 à 3 étapes, humain valide | Plus de 3 étapes chaînées |
| Accès aux données | Données collées dans le prompt | Lecture live (fichiers, API, web) |
| Supervision | Validation à chaque étape | Exécution sans supervision |
Exemple concret : trier 200 factures PDF par fournisseur et générer un récapitulatif par entité. Un assistant peut te dire comment faire. Un agent le fait, en ouvrant chaque PDF, en extrayant l'émetteur, en écrivant les fichiers dans les bons dossiers.
Les briques du SDK : modèle, outils, contexte, permissions
Quatre paramètres à arbitrer avec ton équipe avant d'écrire une ligne de code.
Le modèle. Sonnet 4.6 est le défaut recommandé pour la majorité des agents : bon équilibre vitesse/intelligence, fenêtre de 1M tokens, environ 3 $ le million de tokens en entrée et 15 $ en sortie. Opus 4.7 ou 4.8 pour les tâches de raisonnement long-format ou d'analyse complexe (5 $ / 25 $). Haiku 4.5 pour les gros volumes simples : classification, extraction basique, routage (1 $ / 5 $). Fable 5, sorti en juin 2026, est le tier au-dessus mais son tarif (10 $ / 50 $) le réserve aux tâches où l'écart de qualité justifie le coût.
Les outils. Le SDK expose des outils intégrés : exécution bash, lecture/écriture de fichiers, recherche web. Tu peux ajouter tes propres outils Python ou brancher des serveurs MCP externes (on y revient).
Le contexte. Le SDK gère la compaction automatique quand la fenêtre se remplit. Utile sur des tâches longues, mais tu perds en fidélité si tu ne surveilles pas ce qui est résumé.
Les permissions. Quatre modes : plan (l'agent décrit ce qu'il ferait sans exécuter), ask (validation humaine avant chaque outil), acceptEdits (validation seulement pour les modifs), bypassPermissions (aucune validation). Le dernier mode hors sandbox est une des erreurs les plus fréquentes que tu verras dans les prototypes.
Prérequis : clé API, environnement, budget
Checklist minimale avant de démarrer :
- Un compte sur console.anthropic.com et une clé API avec crédits (prévois 20 à 50 $ pour les premiers tests).
- Python 3.10+ ou Node 18+.
- Un terminal, idéalement dans un environnement isolé (venv Python, container Docker).
Pour la config détaillée de la clé et des variables d'environnement, la page configurer votre clé API Anthropic couvre les cas Windows, Mac et Linux. Si tu n'as pas encore paramétré ton poste, le pilier configurer Claude avant de coder un agent reprend l'ordre logique.
Ordre de grandeur de coût : un agent qui tourne 10 tours de boucle sur Sonnet 4.6, avec un contexte qui grossit progressivement, coûte environ 0,05 à 0,15 $ par exécution. Un test intensif de 200 runs pour valider un cas d'usage : entre 10 et 30 $. Ça reste dans le budget d'un prototype, mais un agent mal cadré (boucle infinie, mauvais modèle) peut consommer plusieurs dizaines de dollars en une nuit. Le max_turns est le premier garde-fou à poser.
Construire un premier agent en 30 lignes
L'agent ci-dessous lit un CSV de prospects, cherche chaque entreprise sur le web, et écrit un fichier enrichi. Le SDK gère seul les 6 ou 7 allers-retours avec Claude.
import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
options = ClaudeAgentOptions(
model="claude-sonnet-4-6",
system_prompt=(
"Tu es un assistant d'enrichissement commercial. "
"Lis prospects.csv, cherche chaque entreprise sur le web, "
"et écris prospects_enrichis.csv avec une colonne 'resume'."
),
allowed_tools=["bash", "file_edit", "web_search"],
permission_mode="acceptEdits",
max_turns=15,
)
async def run():
async with ClaudeSDKClient(options=options) as client:
await client.query("Enrichis le fichier prospects.csv")
async for message in client.receive_response():
print(message)
asyncio.run(run())Trois choses à noter. Le system_prompt décrit précisément le livrable attendu, sans laisser d'ambiguïté sur le nom de fichier. Les allowed_tools limitent ce que l'agent peut faire (pas d'accès réseau non prévu). Le max_turns=15 est le plafond de sécurité : si l'agent boucle, il s'arrête. Pour aller plus loin sur ce type de pattern, l'article premier agent Claude détaille les variantes.
Ajouter des outils personnalisés via MCP
Le Model Context Protocol (MCP) est le standard ouvert d'Anthropic pour connecter un agent à des systèmes tiers : Notion, HubSpot, Slack, une base Postgres, une API interne. Sans MCP, tu devrais écrire toi-même le client pour chaque système et l'exposer comme outil custom au SDK. Avec MCP, tu déclares le serveur MCP dans la config, et l'agent y accède comme à un outil natif.
Exemple de config dans les options du SDK :
mcp_servers={
"notion": {
"command": "npx",
"args": ["-y", "@notionhq/notion-mcp-server"],
"env": {"NOTION_API_KEY": "secret_xxx"}
}
}La liste des serveurs MCP disponibles couvre les intégrations les plus courantes. MCP est ce qui transforme un agent générique en agent métier : sans lui, ton agent lit des fichiers et cherche sur le web ; avec lui, il lit ton CRM, écrit dans ta base de connaissances, ouvre des tickets. Pour un tour complet du protocole, l'article serveur MCP Claude couvre la mise en place côté serveur.
Erreurs classiques et garde-fous
| Piège | Fix |
|---|---|
| bypassPermissions sur laptop principal | Toujours sandboxer (Docker, VM, container léger) |
| Pas de max_turns | Fixer un plafond dès la première ligne de code |
| System prompt vague | Décrire le livrable exact, nommer les fichiers, borner le périmètre |
| Pas de log des tool_use | Persister chaque appel d'outil en JSON pour débugger |
| Opus pour tout | Sonnet 4.6 par défaut, Opus seulement si le prototype échoue avec Sonnet |
Les trois premiers pièges expliquent la majorité des incidents que tu verras remonter. Le quatrième est ce qui distingue un prototype d'un système déboguable en production. Sur la sécurisation en général, l'article sécuriser un agent Claude couvre les patterns de containment.
Passer du prototype à la production
Ce que tu dois exiger de ton équipe (ou de ton prestataire) avant qu'un agent Claude atteigne un utilisateur final ou un système interne critique :
- Un environnement d'exécution isolé (Docker dédié, VM éphémère, container Modal ou E2B) sans accès à autre chose que ce qui est strictement nécessaire.
- Un monitoring des coûts par run avec alerte au-delà d'un seuil défini par cas d'usage.
- Une batterie de tests sur au moins 50 cas réels du métier, avec un taux de succès attendu documenté.
- Un plan de rollback : comment on coupe l'agent en 30 secondes si ça part de travers.
- Un périmètre d'autonomie écrit : qu'est-ce que l'agent peut faire seul, qu'est-ce qui exige une validation humaine.
Déployer un agent Claude en interne demande une réflexion produit, pas juste du code. Sur la partie architecture multi-agents et orchestration, l'article architecture agent Claude pose les bases.
Passer à la pratique
Le SDK n'est qu'un outil. Ce qui fait la différence entre un agent qui coûte 30 $ par mois et rend 8 heures à ton équipe, et un agent qui hallucine sur des données critiques, c'est la conception. Choix du périmètre, du modèle, des permissions, des garde-fous, des tests. Si tu veux structurer cette démarche avec un accompagnement dédié aux dirigeants qui déploient des agents en interne, tu peux piloter vos agents autonomes avec Ottho : cadrage produit, choix d'architecture, tests de charge et de sécurité, transfert à ton équipe.