Construire un agent IA en 2026, ce n’est plus juste appeler une API LLM avec un prompt. C’est concevoir un système autonome capable d’utiliser des outils, lire et écrire des fichiers, exécuter du code, communiquer avec des services externes, et boucler intelligemment jusqu’à atteindre un objectif. Le Claude Agent SDK, lancé par Anthropic en 2025 et stable en 2026, est l’une des bibliothèques les plus complètes pour faire ça en production. Il propulse Claude Code (l’outil officiel d’Anthropic) et permet à n’importe quel développeur de créer ses propres agents intelligents avec quelques lignes de TypeScript ou Python. Voici le guide complet.

Ce pilier couvre les concepts fondamentaux et l’architecture. Les satellites approfondissent : construire un agent custom, créer un MCP server custom métier, orchestrer des sub-agents, et configurer hooks et permissions.

Qu’est-ce que le Claude Agent SDK ?

Le Claude Agent SDK est une bibliothèque officielle Anthropic disponible en TypeScript (@anthropic-ai/claude-agent-sdk) et Python (claude-agent-sdk) qui fournit toute l’infrastructure nécessaire pour construire des agents IA basés sur Claude. Il abstrait :

La boucle agentique : appel LLM, exécution d’outils, retour des résultats au LLM, jusqu’à atteindre l’objectif
L’écosystème d’outils : système de fichiers, bash, web fetch, recherche, et tout outil custom que vous définissez
Le protocole MCP (Model Context Protocol) : standard ouvert pour connecter des serveurs externes (DB, APIs métier, fichiers, etc.) à votre agent
Sub-agents et orchestration : un agent peut déléguer à d’autres agents spécialisés
Hooks et permissions : contrôler finement ce que l’agent peut faire et quand demander confirmation à l’utilisateur
Streaming et partial output : voir l’agent réfléchir en temps réel
Compaction de contexte : gérer automatiquement les conversations longues qui dépassent la fenêtre de contexte

Concrètement, le SDK est ce qui anime Claude Code, l’agent CLI officiel d’Anthropic que vous lancez avec claude dans un terminal. Vous pouvez utiliser le même moteur pour vos propres outils internes.

Cas d’usage en 2026

Agent dev interne qui sait lire votre codebase, écrire des PR, lancer les tests — comme Claude Code mais customisé pour votre stack
Agent support client qui consulte votre base de connaissances, votre CRM, vos tickets, et propose des réponses argumentées
Agent data analyst qui interroge votre data warehouse, génère des graphiques, rédige des rapports
Agent ops qui peut diagnostiquer un incident en lisant les logs, comparant aux métriques, et suggérant des actions
Agent métier spécifique : gestion de planning, validation de devis, audit conformité, etc.

Modèle de tarification (à savoir avant)

Un agent Claude consomme des tokens à chaque tour de boucle. Pour un agent typique qui résout une tâche en 5-15 tours, comptez quelques centaines de milliers de tokens, soit ~0.50 à 2 USD par exécution selon le modèle (Claude Sonnet 4.6 vs Opus 4.7) et la taille du contexte. C’est important : avant de scaler en production, mesurez le coût par exécution moyen et ajoutez du caching de prompt pour économiser ~50-80 % sur les exécutions répétitives.

Pour les usages internes (productivité d’équipe), le ROI est massif : un agent qui économise 30 minutes de travail à un dev senior s’amortit en 1 USD de tokens. Pour les usages clients (chatbot facturé à l’utilisateur), surveillez le coût par requête comme un faucon.

Prérequis

Node.js 20+ ou Python 3.10+ (Bun fonctionne aussi pour le SDK TypeScript)
Une clef API Anthropic (créer un compte sur console.anthropic.com)
Connaissance de TypeScript ou Python intermédiaire
Notion de prompt engineering basique
Niveau attendu : intermédiaire à avancé
Temps : 1 heure pour le hello world, 1 journée pour un agent métier simple, 1 semaine pour un agent production-ready

Étape 1 — Installation

# TypeScript / Node / Bun
bun add @anthropic-ai/claude-agent-sdk
# ou : npm install @anthropic-ai/claude-agent-sdk

# Python
pip install claude-agent-sdk
# ou : uv add claude-agent-sdk

Configurez la clef API dans une variable d’environnement :

export ANTHROPIC_API_KEY="sk-ant-api03-..."

Étape 2 — Premier agent

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

const result = query({
  prompt: "Quels sont les 3 derniers articles modifiés dans ce dossier ?",
  options: {
    permissionMode: "acceptEdits",
    cwd: "./",
  },
});

for await (const message of result) {
  if (message.type === "assistant") {
    console.log(message.content);
  }
}

Exécutez avec bun run agent.ts. L’agent va explorer le dossier courant, lister les fichiers, regarder les dates de modification, et synthétiser une réponse — exactement comme Claude Code le ferait.

Étape 3 — Outils built-in

Le SDK fournit nativement les outils suivants (dérivés de Claude Code) :

Read : lire un fichier (avec offset/limit)
Write : créer un fichier
Edit : modifier un fichier (remplacement de chaîne)
Glob : rechercher fichiers par pattern
Grep : recherche dans le contenu (basée ripgrep)
Bash : exécuter une commande shell
WebFetch : récupérer une page web
WebSearch : recherche web
TodoWrite : gérer une liste de tâches structurée

Vous pouvez les activer ou désactiver finement via options.allowedTools et options.disallowedTools.

Étape 4 — Outils custom

Pour étendre l’agent avec des capacités métier :

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

const sendInvoice = tool(
  "sendInvoice",
  "Envoie une facture par email à un client",
  {
    clientEmail: z.string().email(),
    amount: z.number().positive(),
    items: z.array(z.string()),
  },
  async (args) => {
    // Logique métier : appel API facture, email, DB...
    await emailService.send({
      to: args.clientEmail,
      subject: `Facture - ${args.amount} FCFA`,
      items: args.items,
    });
    return { success: true, sent: true };
  },
);

// Utiliser dans une query
const result = query({
  prompt: "Envoie une facture de 50000 FCFA à client@exemple.sn pour 'Formation Bun'",
  options: {
    customTools: [sendInvoice],
  },
});

L’agent va parser la demande, appeler sendInvoice avec les bons paramètres, traiter la réponse, et confirmer à l’utilisateur. Voir notre tutoriel agent custom pour des exemples complets.

Étape 5 — MCP servers

Plutôt que d’écrire chaque outil dans votre code, vous pouvez exposer une API métier via un MCP server que l’agent utilise. C’est l’approche recommandée pour les workloads complexes : un MCP server est un processus séparé (TypeScript, Python, Go, n’importe quel langage) qui expose des outils via un protocole standard. L’agent Claude consomme automatiquement ces outils.

Avantages du MCP : réutilisable entre plusieurs agents, testable indépendamment, plus simple à versionner, et compatible avec d’autres clients que Claude (Cursor, Continue, etc.). Voir notre tutoriel MCP server custom.

Étape 6 — Hooks et permissions

Pour un usage en production, vous voulez contrôler ce que l’agent peut faire. Le SDK propose :

permissionMode : "default", "acceptEdits", "plan", "bypassPermissions"
Hooks PreToolUse / PostToolUse : intercepter chaque appel d’outil pour le valider, le logger, ou le bloquer
UserPromptSubmit hook : modifier ou enrichir le prompt utilisateur avant envoi à Claude
Stop hook : exécuter du code à la fin de chaque réponse de Claude

Voir le tutoriel dédié hooks et permissions Claude Agent SDK.

Étape 7 — Sub-agents

Quand un agent doit faire plusieurs choses différentes (analyser du code ET écrire de la documentation ET lancer des tests), il est souvent plus efficace de déléguer à des sub-agents spécialisés. Le SDK supporte ça nativement via l’outil Agent. Chaque sub-agent a son propre system prompt, ses propres outils, son propre contexte.

Voir orchestration de sub-agents pour un guide pratique.

Étape 8 — Caching de prompt

Pour réduire le coût et la latence, activez le prompt caching d’Anthropic. Les sections marquées comme cachables (system prompt, exemples, contexte fixe) sont stockées 5 minutes dans une cache spécifique et coûtent 10 % du prix normal aux appels suivants.

const result = query({
  prompt: "...",
  options: {
    systemPrompt: { type: "preset", preset: "claude_code" },
    enableCaching: true,        // active le caching
    model: "claude-sonnet-4-6",
  },
});

Sur des agents qui traitent 100+ requêtes par jour avec un long system prompt, le caching divise la facture par 3 à 5.

Étape 9 — Modèles disponibles

claude-opus-4-7 — le plus capable, le plus cher, pour les tâches complexes
claude-sonnet-4-6 — équilibre coût/performance, recommandé par défaut
claude-haiku-4-5 — le plus rapide et économique, pour les tâches simples ou les sub-agents légers

Tip d’orchestration : utilisez Sonnet pour l’agent principal, et Haiku pour des sub-agents spécialisés (recherche fichier, formatage, summarisation). Vous gagnez 70 % du coût sans dégrader la qualité globale.

Adaptation Afrique de l’Ouest

Pour les développeurs et PME ouest-africaines, le Claude Agent SDK ouvre des cas d’usage concrets : assistant comptable interne, agent de relance facture WhatsApp, audit automatique de site, génération de rapports métier. La clef API Anthropic est facturée en USD (Visa/Mastercard internationale, Wave Visa virtuelle accepté), et les agents tournent sur n’importe quel VPS — Hetzner, OVH ou hébergeur sénégalais.

Pour limiter les coûts, démarrez avec Haiku, mesurez la qualité, et ne basculez sur Sonnet que pour les tâches qui le justifient.

Erreurs fréquentes

Erreur	Cause	Solution
401 Unauthorized	Clef API absente ou invalide	Vérifier ANTHROPIC_API_KEY
Coût explose	Pas de caching, prompt trop long	Activer enableCaching, réduire system prompt
Boucle infinie d’agent	Objectif mal défini	Préciser le critère d’arrêt dans le prompt
Agent fait n’importe quoi	Permissions trop larges	Limiter allowedTools et permissionMode
Latence élevée	Modèle Opus utilisé partout	Sonnet par défaut, Opus uniquement quand nécessaire

Pour aller plus loin

Construire un agent custom Claude SDK
MCP server custom pour votre métier
Sub-agents et orchestration
Hooks et permissions Claude Agent SDK
Documentation officielle : docs.anthropic.com/en/api/agent-sdk
Spec MCP : modelcontextprotocol.io

FAQ

Faut-il Claude Code ou le SDK ?

Claude Code est l’agent prêt à l’emploi (CLI) basé sur le SDK. Pour de l’usage personnel ou en équipe dev, Claude Code suffit. Pour intégrer un agent dans votre produit, votre service, votre app web, vous utilisez le SDK directement.

Le SDK est-il payant ?

Le SDK lui-même est open-source et gratuit (MIT). Vous payez uniquement les tokens consommés par les appels Claude. Tarif Sonnet 4.6 fin 2026 : ~3 USD par million de tokens input, ~15 USD par million de tokens output. Avec le prompt caching activé, ça baisse drastiquement.

Peut-on utiliser le SDK avec d’autres LLM ?

Le SDK est conçu pour Claude (les hooks, le format de tool use, les capacités). Pour utiliser GPT ou Llama, il existe d’autres SDK (OpenAI Agents SDK, Vercel AI SDK, LangGraph). Vous pouvez les coexister dans le même projet.

Claude Agent SDK 2026 : guide complet (construire des agents IA en production)