Agent SDK Claude, bâtir ton premier agent custom en 12 minutes

Le jour où ton chatbot Claude doit enchaîner plusieurs actions tout seul, chercher, lire, exécuter, puis revenir te répondre, le branchement simple montre vite ses limites. C'est exactement là que l'Agent SDK entre en jeu, et ce chapitre te montre comment.

Pour bien cadrer le choix, sache d'abord qu'on construit avec Claude à deux niveaux différents selon ce qu'on vise. Au premier niveau, tu utilises l'API Messages classique (l'API c'est l'interface de programmation qui permet à un programme externe de parler à Claude), tu envoies un prompt et tu reçois une réponse.

Tu gères toi-même les outils, la boucle agentique, et l'état. Au deuxième niveau, tu utilises l'Agent SDK qui te donne un wrapper officiel autour des primitives de Claude Code (tools, hooks, skills, MCP), et il te laisse construire un agent custom complet sans réinventer la plomberie.

En 12 minutes de lecture, tu comprends la différence entre Messages API et Agent SDK, tu vois 6 exemples canoniques publiés par Anthropic, et tu sais lancer ton premier agent en quelques lignes. Ce guide s'adresse à toute personne qui maîtrise déjà l'API Messages et qui veut passer à un vrai agent autonome.

Tu lis le chapitre 67 d'un manuel de 67 chapitres disponible sur claude-pour-les-debutants.fr.

Ce qu'est l'Agent SDK

Pour comprendre l'Agent SDK, tu peux le voir comme la couche d'orchestration officielle qu'Anthropic publie pour construire des agents Claude.

L'Agent SDK te donne accès aux mêmes primitives que celles utilisées par Claude Code en interne. Tu disposes de tools (Read, Write, Bash, Glob, Grep) prêts à brancher.

Tu peux ajouter tes propres tools custom. Tu peux configurer des hooks à des moments précis du cycle de vie. Tu peux invoquer des skills réutilisables. Tu peux connecter des serveurs MCP (le MCP, c'est en gros un standard de connecteur entre agents IA et services externes comme Slack ou Gmail).

✦ Tu obtiens un agent custom sans avoir à coder la boucle agentique toi-même.

✦ Tu gardes le contrôle complet sur l'orchestration et les permissions.

✦ Tu disposes de versions officielles en Python et en TypeScript.

→ L'Agent SDK est le pont entre l'API brute et un produit agentique complet.

Différence avec l'API Messages

Pour bien décider quel niveau utiliser, tu peux comparer les deux approches.

API Messages	Agent SDK
Tu envoies un prompt, tu reçois une réponse	Tu envoies un prompt, l'agent boucle jusqu'à finir
Tu gères toi-même les tools	Tu disposes des tools Claude Code par défaut
Tu écris la boucle agentique à la main	Tu disposes de la boucle officielle
Tu sérialises et persistes l'état toi-même	Tu disposes de la gestion d'état intégrée
Pas de hooks ni de skills	Tu disposes du système de hooks et skills

▸ Tu utilises l'API Messages pour un chatbot simple (un tour, une réponse).

▸ Tu utilises l'Agent SDK pour un agent qui doit faire plusieurs étapes autonomes (recherche, code, exécution).

↳ Tu peux commencer par l'API Messages et migrer vers l'Agent SDK quand ta boucle agentique custom devient compliquée à maintenir.

Passation des responsabilités d'un agent de l'API Messages vers l'Agent SDK, outils boucle et état

Les 7 exemples canoniques d'Anthropic

Tu peux t'inspirer de 7 cookbooks officiels qu'Anthropic publie pour le Claude Agent SDK.

▸ One-liner research agent (sorti en septembre 2025) est l'exemple le plus simple. Tu lui passes une question, il fait des recherches sur le web et il te livre un rapport synthétique.

▸ Chief of staff agent (sorti en septembre 2025) est un agent qui agit comme un chef de cabinet personnel. Il lit ton agenda, ton inbox, tes notes, et il te livre un briefing du jour.

▸ Observability agent (sorti en septembre 2025) est un agent qui monitore ta production. Il regarde tes logs, tes métriques, et il alerte sur les anomalies.

▸ Site reliability agent (sorti en février 2026) est un agent SRE qui répond aux alertes infrastructure. Il diagnostique, il propose un fix, et il peut le déployer après confirmation.

▸ Session browser (sorti en mars 2026) est un agent qui parse l'historique d'autres sessions Claude pour en extraire des éclairages et des patterns.

▸ Vulnerability detection agent (sorti en avril 2026) est un agent de sécurité qui scanne du code à la recherche de CVEs et de vulnérabilités connues.

▸ Migrating from OpenAI Agents SDK (sorti en mars 2026) est un guide pour ceux qui veulent migrer depuis le SDK Agents d'OpenAI vers celui d'Anthropic. Tu trouves les équivalences de patterns.

→ Tu trouves ces 7 exemples sur le repo github.com/anthropics/claude-cookbooks dans la section claude-agent-sdk.

Frise chronologique des 7 exemples officiels d'Anthropic, du research agent au détecteur de failles

Installation Python

Pour démarrer en Python avec l'Agent SDK, tu peux installer le paquet avec pip.

pip install claude-agent-sdk

Tu exportes ensuite ta clé API avec export ANTHROPIC_API_KEY=sk-ant-... pour que le SDK puisse appeler Anthropic.

↳ Tu peux aussi cloner directement le repo anthropics/claude-agent-sdk-python pour avoir les exemples et les tests sous la main.

Ton premier agent en quelques lignes

Pour construire un research agent minimaliste, tu peux écrire 10 lignes de code.

from claude_agent_sdk import Agent

agent = Agent(
    model="claude-opus-4-8",
    system_prompt="Tu es un research analyst. Tu vas chercher des informations sur le web et tu vas livrer un rapport synthétique avec sources.",
    tools=["web_search", "web_fetch"],
)

result = agent.run(
    "Quelles sont les 3 tendances IA les plus importantes de 2026 selon les analystes ?"
)

print(result.output)
print(f"Tools appelés : {result.tool_call_count}")
print(f"Tokens consommés : {result.usage.total_tokens}")

Tu remarques que tu n'écris pas la boucle agentique. Le SDK gère pour toi les 4 étapes du cycle (envoi de la question, sélection de l'outil, exécution de l'outil, intégration du résultat) en boucle jusqu'à ce que l'agent décide d'arrêter.

→ Tu obtiens un agent fonctionnel en moins de 10 lignes, là où la même chose avec l'API Messages brute te prendrait 100 lignes.

Schéma de la boucle agentique en 4 étapes que le SDK répète jusqu'à ce que l'agent ait fini

Configurer des hooks et des skills

Pour personnaliser le comportement de ton agent, tu peux brancher des hooks et des skills.

from claude_agent_sdk import Agent

agent = Agent(
    model="claude-opus-4-8",
    system_prompt="Tu es un code reviewer senior.",
    tools=["read", "grep", "glob"],
    skills_dir="./my-skills",
    hooks={
        "PreToolUse": [{
            "matcher": "Bash",
            "command": "./scripts/block-dangerous-bash.sh",
        }],
        "PostToolUse": [{
            "matcher": "Write",
            "command": "./scripts/log-writes.sh",
        }],
    },
)

result = agent.run("Review the PR in this directory and post a summary.")

Tu charges automatiquement les skills depuis ton dossier my-skills/ (chaque sous-dossier contient un SKILL.md). Tu branches un hook PreToolUse qui bloque les commandes Bash dangereuses.

Tu branches un hook PostToolUse qui logge chaque écriture de fichier.

↳ Tu retrouves la même logique de hooks que Claude Code, donc tu peux réutiliser tes scripts existants.

Connecter des serveurs MCP

Pour donner à ton agent l'accès à des services tiers (Slack, Gmail, Linear), tu peux connecter des serveurs MCP.

from claude_agent_sdk import Agent, MCPServer

agent = Agent(
    model="claude-opus-4-8",
    system_prompt="Tu es un assistant qui aide à trier les tickets clients.",
    tools=["read", "write"],
    mcp_servers=[
        MCPServer(
            url="https://mcp.slack.com/mcp",
            auth_token="xoxp-...",
        ),
        MCPServer(
            url="https://mcp.linear.app/mcp",
            auth_token="lin_api_...",
        ),
    ],
)

result = agent.run("Lis les 10 derniers messages du canal #support et crée les tickets Linear correspondants.")

Tu connectes Slack et Linear via leurs serveurs MCP officiels. L'agent peut maintenant lire les messages Slack et créer des tickets Linear sans que tu aies à coder l'intégration toi-même.

→ Tu trouves une liste de serveurs MCP officiels et communautaires sur le repo officiel du protocole MCP.

Le pattern observabilité

Pour debug ton agent en développement, tu peux activer l'observabilité complète.

from claude_agent_sdk import Agent

agent = Agent(
    model="claude-opus-4-8",
    system_prompt="...",
    tools=["read", "write", "bash"],
    verbose=True,
    log_file="./agent.log",
)

result = agent.run("...")

for step in result.steps:
    print(f"Step {step.index} : {step.action_type}")
    print(f"  Tool : {step.tool_name}")
    print(f"  Input : {step.tool_input}")
    print(f"  Output : {step.tool_output[:200]}")

Tu vois chaque étape du raisonnement de l'agent, chaque appel d'outil, et chaque sortie d'outil. Tu peux ensuite identifier où l'agent boucle, où il rate, ou où il consomme trop de tokens.

▸ Tu actives verbose=True uniquement en développement, jamais en production (sortie console massive).

▸ Tu logges plutôt vers un fichier JSON structuré pour la production, et tu utilises des outils d'observabilité dédiés (Langfuse, Helicone, Honeycomb) pour les agents qui tournent en continu.

Quand utiliser quel niveau

Pour décider quel niveau utiliser entre API Messages, Agent SDK, et Claude Code, tu peux suivre cette grille.

▸ Tu utilises API Messages pour un chatbot, une extraction de données structurées, une classification de textes (1 tour de question-réponse).

▸ Tu utilises Agent SDK pour un agent custom dans ton propre code, intégré dans ton produit SaaS ou ton workflow d'entreprise (plusieurs tours autonomes).

▸ Tu utilises Claude Code pour de l'usage interactif depuis ton terminal personnel (toi qui tape des commandes dans le terminal).

▸ Tu utilises Managed Agents pour un produit SaaS multi-utilisateurs avec passage à l'échelle cloud (Sessions + Vaults + Environments + Dreams).

↳ Tu peux combiner les niveaux. Ton produit peut utiliser l'Agent SDK pour la logique custom, branché à Managed Agents pour le passage à l'échelle.

Anneaux concentriques des 4 niveaux pour construire avec Claude, de Claude.ai au centre aux Managed Agents en périphérie, chaque cercle ajoutant de l'autonomie

Un dernier mot

Tu n'as pas besoin de l'Agent SDK pour la majorité de tes usages Claude.

Tu sors l'Agent SDK le jour où tu veux construire un vrai produit qui boucle en autonomie, qui utilise des tools, qui charge des skills, et qui se connecte à des services externes. Tu démarres avec l'exemple "one-liner research agent" pour comprendre l'API du SDK.

Tu migres ensuite vers les patterns plus avancés (chief of staff, observability, SRE) à mesure que tu construis ton propre agent. Tu mets en place dès le début un mécanisme d'observabilité pour debug ton agent quand il dérive.

Tu finis ce manuel avec une grille mentale claire de l'écosystème Claude. Tu sais comment Claude répond, ce qu'il sait et ne sait pas, comment lui parler avec un bon prompt, comment l'intégrer dans tes outils du quotidien, et comment construire des automatisations agentiques avancées.

Tu as la connaissance pour décider lequel des 4 niveaux (Claude.ai, API Messages, Agent SDK, Managed Agents) correspond à chacun de tes besoins.

→ Essaie Claude maintenant : claude.ai

→ Retour au manuel