Construire un agent IA avec le Claude Agent SDK : le guide pour développeurs

Si Claude Code est l’agent fini, le Claude Agent SDK est la boîte à outils qui permet de construire vos propres agents. Renommé en 2025 (ex-Claude Code SDK), il expose les mêmes briques qui font tourner Claude Code en CLI : boucle d’agent, gestion de contexte, outils, hooks, sous-agents, MCP — mais programmable depuis votre code Python ou TypeScript.

Ce guide couvre l’architecture, le premier agent qui marche en 20 lignes, et trois cas d’usage concrets où construire son propre agent bat l’usage direct de Claude Code.

Claude Code vs Claude Agent SDK : qui fait quoi ?

	Claude Code	Claude Agent SDK
Interface	CLI dans votre terminal	Bibliothèque Python ou TypeScript
Public	Développeurs en usage quotidien	Développeurs qui construisent des produits/pipelines
Où ça tourne	Sur votre machine	Où vous voulez (serveur, CI, Lambda, Docker…)
Personnalisation	CLAUDE.md, slash commands, Skills, hooks	Tout ce qui précède + contrôle total du code autour
Exemple typique	« Refactorise ce module »	« Un bot Slack qui triage les issues GitHub toute la nuit »

Règle simple : si vous voulez utiliser un agent, Claude Code. Si vous voulez intégrer un agent dans votre produit, votre CI ou votre backend, Agent SDK.

Architecture : les 4 briques

Le SDK repose sur quatre concepts (Claude API Docs, 2026) :

1. Tools — les actions que l’agent peut entreprendre (lire un fichier, lancer une commande, appeler une API).
2. Hooks — du code qui s’exécute à des moments-clés (avant un tool call, après un result, en fin de tâche).
3. MCP servers — les mêmes serveurs MCP que pour Claude Code, branchables au SDK.
4. Sub-agents — des agents délégués avec leur propre système prompt et leur propre toolset.

Les outils intégrés fournis par défaut : lecture/écriture de fichiers, exécution de commandes shell, requêtes HTTP, recherche web.

Installation et premier agent

Python

pip install claude-agent-sdk

En avril 2026, version 0.1.48 sur PyPI (Claude API Docs, 2026).

TypeScript / Node

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

Version 0.2.71 en avril 2026.

Hello world en 15 lignes (Python)

import anthropic
from claude_agent_sdk import Agent, tool

@tool
def get_weather(city: str) -> str:
    """Récupère la météo d'une ville."""
    return f"Il fait 18°C et nuageux à {city}."

agent = Agent(
    model="claude-opus-4-6",
    tools=[get_weather],
    system_prompt="Tu es un assistant météo concis."
)

async for msg in agent.query("Quel temps fait-il à Paris ?"):
    print(msg)

La fonction query renvoie un async iterator : vous consommez les messages au fur et à mesure que Claude réfléchit, appelle l’outil, observe le résultat, et décide de la suite. Le SDK gère l’orchestration (exécution des tools, contexte, retries), vous ne consommez que le stream (SerpApi Blog, 2026).

Définir des outils personnalisés

Un outil = une fonction que Claude peut appeler. Il a trois éléments :

• Un nom (dérivé du nom de la fonction ou explicite)
• Une description (le docstring Python ou le JSDoc)
• Un schéma de paramètres (dérivé des types ou explicite)

Exemple : outil qui appelle votre API interne

@tool
def search_customer(email: str) -> dict:
    """Cherche un client dans le CRM par son email. Retourne id, nom, plan."""
    response = httpx.get(
        f"https://crm.interne/api/customers",
        params={"email": email},
        headers={"Authorization": f"Bearer {API_TOKEN}"}
    )
    return response.json()

Claude lit la description et décide quand appeler cet outil en fonction de la demande utilisateur. Les descriptions précises sont cruciales : elles sont la seule chose que Claude a pour choisir ses actions.

Bonnes pratiques pour les outils

• Docstrings claires. C’est le prompt de l’outil. « Cherche un client par email » > « Query function ».
• Valeurs de retour structurées. Préférez dict / objets à des strings, Claude les interprète mieux.
• Gérez les erreurs en retour, pas en exception. {"error": "not found"} plutôt qu’une exception qui fait planter l’agent.
• Outils orthogonaux. Plutôt 5 outils bien cadrés qu’1 outil « fais ce qui faut ».

3 cas d’usage où l’Agent SDK bat Claude Code

1. Un bot qui triage les issues GitHub chaque nuit

Claude Code en CLI est interactif ; il n’est pas fait pour tourner sans humain. Avec l’Agent SDK, vous pouvez écrire un script qui :

1. Récupère toutes les issues ouvertes depuis 24 h via l’API GitHub.
2. Lit le contenu de chaque issue + le code pertinent du repo.
3. Propose un label, une priorité, et éventuellement un premier diagnostic.
4. Commente l’issue avec son analyse.
5. Se lance via un cron à 2 h du matin.

Temps d’implémentation : un après-midi. Gain : l’équipe arrive le matin avec toutes les issues pré-triées et les plus simples déjà diagnostiquées.

2. Un assistant code dans votre propre produit

Si vous construisez un SaaS pour développeurs, vous voulez probablement un assistant intégré. Le SDK permet de le faire tourner avec votre propre logique autour : authentification utilisateur, limitation de quotas, logs métier, UI custom.

Exemple d’architecture :

Frontend React → Votre API Node →
    Agent SDK (query stream) →
        Tools (vos API internes + MCP génériques) →
    Stream renvoyé au frontend via SSE

C’est ce qu’utilisent plusieurs plateformes d’IA de code en marque blanche : Claude Agent SDK dessous, enrobage produit par-dessus (Promptfoo, 2026).

3. Un pipeline d’audit GEO massif

Pour un site de 10 000+ pages, lancer Claude Code interactivement n’est pas tenable. Un pipeline Agent SDK :

async def audit_page(url: str) -> AuditReport:
    agent = Agent(
        model="claude-haiku-4-5",  # rapide et peu cher
        tools=[fetch_url, extract_schema, check_consistency],
        system_prompt=AUDIT_GEO_PROMPT,
    )
    async for msg in agent.query(f"Audite {url}"):
        if msg.type == "final":
            return parse_report(msg.content)

# Batch parallèle sur 10k pages
reports = await asyncio.gather(*[audit_page(url) for url in all_urls])

Avec Haiku 4.5 à 1 $ / 5 $ par million de tokens, auditer 10 000 pages coûte typiquement 30 à 80 $ — contre des semaines de travail humain équivalent.

Hooks, sous-agents, MCP — tout est là

Tout ce qui existe dans Claude Code existe dans le SDK, mais programmable :

agent = Agent(
    model="claude-opus-4-6",
    tools=[...],
    hooks={
        "post_tool_call": log_to_datadog,
        "stop": send_slack_notification,
    },
    mcp_servers=[
        {"name": "postgres", "url": "stdio://..."},
        {"name": "sentry", "url": "stdio://..."},
    ],
    subagents=[
        {"name": "security-reviewer", "config_path": ".claude/agents/sec.md"},
    ],
)

Vous configurez en code ce que vous configureriez dans settings.json pour Claude Code. Tout est injectable, testable, versionnable.

Prompt caching : l’optimisation qui change tout

Un agent qui tourne à l’échelle répète énormément son système prompt (souvent plusieurs milliers de tokens). Le prompt caching d’Anthropic permet de mettre en cache ces tokens et de ne payer qu’une fraction du prix sur les appels suivants.

En pratique, pour un agent avec un gros système prompt :

• Sans cache : vous payez 5 $/MTok input sur chaque requête.
• Avec cache : vous payez 5 $/MTok sur la première requête, puis 10 % du prix (0,50 $/MTok) sur les suivantes pendant 5 minutes.

Pour un pipeline qui traite 10 000 items avec un gros contexte, la facture peut être divisée par 5 à 10. C’est le levier d’optimisation n°1 d’un agent en production, à activer systématiquement dès que votre système prompt dépasse 1 000 tokens.

Monitoring et observabilité

Un agent qui tourne en production a besoin d’observabilité. Le SDK expose chaque étape via le stream :

• Quels tools ont été appelés, avec quels paramètres
• Les résultats retournés
• Le raisonnement intermédiaire (en mode thinking)
• Les tokens consommés, le coût par requête

Branchez votre solution habituelle (Datadog, Grafana, OpenTelemetry) via les hooks. La règle qui revient : loguer le plan avant l’exécution. Si un agent prend une décision coûteuse ou destructive, vous voulez le savoir.

Limites et gotchas

1. Latence. Un agent qui enchaîne 5 tool calls + réflexion prend 5 à 30 secondes. Ce n’est pas un appel d’API classique. Prévoyez votre UX en conséquence (streaming, feedback utilisateur).

2. Coûts variables. Contrairement à un endpoint classique où vous contrôlez input/output, un agent décide lui-même combien d’itérations. Mettez des limites strictes (max_iterations, max_tokens) pour éviter les dérives.

3. Non-déterminisme. Le même prompt peut produire des séquences d’actions différentes d’un run à l’autre. Pour les cas critiques, validez toujours les outputs avant action.

4. Permissions des tools. Un outil qui peut modifier votre base de données est un risque. Implémentez toujours : lecture par défaut, écriture sur confirmation explicite, actions destructives jamais automatisables.

Quand ne PAS utiliser l’Agent SDK

• Appel LLM simple (générer un texte, classifier, résumer) → utilisez directement l’API messages classique, l’overhead agent n’apporte rien.
• Workflow déterministe (étapes A → B → C connues d’avance) → utilisez un orchestrateur classique avec LLM en call unique à chaque étape, moins de surprises.
• Budget très serré → l’agent itère et consomme plus. Si vous avez besoin de prévisibilité budgétaire, préférez les patterns classiques.

L’Agent SDK est pour les cas où vous voulez que le modèle décide de la suite des actions, pas pour les cas où vous savez déjà la séquence.

Pour aller plus loin

• Documentation officielle : platform.claude.com/docs/en/agent-sdk/overview
• Dépôt TypeScript : anthropics/claude-agent-sdk-typescript
• Claude Code en 2026, le guide complet
• Sous-agents, MCP et hooks en équipe
• Claude Code Skills : créer ses propres compétences

En résumé

L’Agent SDK n’est pas « Claude Code en bibliothèque ». C’est le moteur sous Claude Code, exposé. À utiliser quand vous voulez :

• Automatiser une tâche sans humain dans la boucle
• Intégrer un agent dans votre propre produit
• Traiter un volume que l’interactif ne peut pas absorber
• Piloter finement les hooks, tools et MCP en code

Les gains d’usage se mesurent en heures économisées par nuit (triage automatique) ou en ordres de grandeur de coût (pipeline batch avec Haiku + prompt caching). Le ticket d’entrée est faible : un script de 20 lignes Python fait déjà un agent qui marche. Tout ce qu’il faut après, c’est de la rigueur produit — permissions, limites, observabilité — comme pour tout système qui prend des décisions sans supervision humaine.