Claude Code Agent SDK : Le Guide Complet pour Créer des Agents IA (2026)

Vous voulez créer votre premier agent IA mais ne savez pas par où commencer ? Le Claude Code Agent SDK d'Anthropic rend cela possible – même sans connaissances approfondies en programmation.

Dans ce guide complet, nous vous montrerons étape par étape comment créer des agents IA autonomes capables de gérer des tâches complexes de manière indépendante.

---

Ce que vous apprendrez dans ce guide

• Ce que sont les agents IA et en quoi ils diffèrent des chatbots
• Comment fonctionne le Claude Code Agent SDK
• Des exemples de code pratiques pour votre premier agent
• Outils, sous-agents et intégration MCP
• Meilleures pratiques pour des agents prêts pour la production

---

Qu'est-ce qu'un agent IA ? (Et pourquoi est-il différent de ChatGPT ?)

Avant de plonger dans le code, clarifions un concept fondamental : Qu'est-ce qui distingue un agent IA d'un chatbot ordinaire ?

Chatbot vs Agent

Un chatbot répond à vos questions. Un agent IA travaille de manière autonome vers un objectif, utilisant divers outils et prenant ses propres décisions en cours de route.

Le Pattern de Boucle d'Agent (Agent Loop)

Chaque agent IA suit un pattern fondamental – la fameuse Boucle d'Agent :

┌─────────────────────────────────────────────────────────────┐
│                    PATTERN AGENT LOOP                       │
├─────────────────────────────────────────────────────────────┤
│  1. COLLECTER LE CONTEXTE                                   │
│     └─▶ Comprendre la tâche, lire les données pertinentes   │
│                                                             │
│  2. EXÉCUTER UNE ACTION                                     │
│     └─▶ Utiliser les outils, exécuter des opérations        │
│                                                             │
│  3. VÉRIFIER LES RÉSULTATS                                  │
│     └─▶ L'action a-t-elle réussi ?                          │
│                                                             │
│  4. RÉPÉTER                                                 │
│     └─▶ Jusqu'à ce que l'objectif soit atteint              │
└─────────────────────────────────────────────────────────────┘

Exemple : Vous demandez à un agent de planifier un voyage. L'agent :

1. Collecte le contexte : Demande la date, le budget, les préférences
2. Exécute des actions : Recherche des vols, hôtels, activités
3. Vérifie : Tout correspond-il au budget ? Les horaires sont-ils compatibles ?
4. Répète : Jusqu'à ce qu'un plan de voyage complet soit prêt

---

Qu'est-ce que le Claude Code Agent SDK ?

Le Claude Code Agent SDK est le même framework qu'Anthropic utilise en interne pour Claude Code – leur puissant assistant de codage.

Il fournit tout ce dont vous avez besoin pour créer des agents IA prêts pour la production :

Fonctionnalités Principales du SDK

Pourquoi choisir le Claude Code Agent SDK ?

1. Éprouvé en production : Le même système qui alimente Claude Code
2. Boilerplate minimal : Moins de code, plus de fonctionnalités
3. Outils intégrés : Opérations sur fichiers, Bash, Web prêts à l'emploi
4. Natif MCP : Intégration transparente avec Model Context Protocol

---

Démarrage Rapide : Installation et Configuration

Prérequis

• Python 3.10 ou supérieur
• Clé API Anthropic (depuis console.anthropic.com)

Étape 1 : Installer le SDK

# Installer avec pip
pip install claude-agent-sdk

# Ou avec uv (recommandé pour une installation plus rapide)
uv pip install claude-agent-sdk

Étape 2 : Configurer la Clé API

# Définir comme variable d'environnement
export ANTHROPIC_API_KEY="sk-ant-..."

# Ou dans un fichier .env
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env

Étape 3 : Tester la Première Connexion

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

async def test_connection():
    options = ClaudeAgentOptions(
        model="sonnet",  # Claude Sonnet 4
        system_prompt="Vous êtes un assistant utile."
    )
    
    async with ClaudeSDKClient(options=options) as client:
        await client.query("Dites bonjour !")
        async for message in client.receive_response():
            print(message)

# Exécuter
import asyncio
asyncio.run(test_connection())

---

Exemple Pratique 1 : Agent Q&R Simple

Commençons avec l'agent le plus simple – celui qui répond aux questions :

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
from claude_agent_sdk.types import TextBlock
import asyncio

SYSTEM_PROMPT = """Vous êtes un assistant sympathique qui répond aux questions. 
Soyez précis et utile."""

async def simple_qa_agent():
    options = ClaudeAgentOptions(
        model="sonnet",
        system_prompt=SYSTEM_PROMPT,
        permission_mode="acceptEdits"  # Autorise les opérations de lecture
    )
    
    async with ClaudeSDKClient(options=options) as client:
        print("🤖 Agent Q&R prêt ! (Tapez 'exit' pour quitter)\n")
        
        while True:
            user_input = input("Vous : ").strip()
            
            if user_input.lower() in ['exit', 'quitter']:
                print("Au revoir !")
                break
            
            await client.query(user_input)
            
            print("Agent : ", end="")
            async for message in client.receive_response():
                if hasattr(message, 'content'):
                    for block in message.content:
                        if isinstance(block, TextBlock):
                            print(block.text, end="")
            print("\n")

if __name__ == "__main__":
    asyncio.run(simple_qa_agent())

Ce que fait ce code :

1. Crée un client avec un prompt système
2. Démarre une boucle interactive
3. Envoie l'entrée utilisateur à Claude
4. Retourne la réponse en streaming

---

Exemple Pratique 2 : Agent avec Mémoire

Un agent avec mémoire de conversation peut se souvenir des messages précédents :

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
from claude_agent_sdk.types import TextBlock
import asyncio

SYSTEM_PROMPT = """Vous êtes un assistant avec une mémoire. 
Vous vous souvenez de tout ce qui a été dit dans cette conversation.
Référencez les déclarations précédentes si pertinent."""

async def memory_agent():
    options = ClaudeAgentOptions(
        model="sonnet",
        system_prompt=SYSTEM_PROMPT,
        permission_mode="acceptEdits",
        # Le SDK gère automatiquement l'historique de conversation !
    )
    
    async with ClaudeSDKClient(options=options) as client:
        print("🧠 Agent Mémoire prêt !\n")
        print("Astuce : Posez des questions liées aux réponses précédentes.\n")
        
        while True:
            user_input = input("Vous : ").strip()
            
            if not user_input:
                continue
                
            if user_input.lower() == 'exit':
                break
            
            await client.query(user_input)
            
            print("Agent : ", end="")
            async for message in client.receive_response():
                if hasattr(message, 'content'):
                    for block in message.content:
                        if isinstance(block, TextBlock):
                            print(block.text, end="", flush=True)
            print("\n")

if __name__ == "__main__":
    asyncio.run(memory_agent())

Testez la mémoire :

Vous : Je m'appelle Max.
Agent : Bonjour Max ! Ravi de vous rencontrer.

Vous : Quel est mon nom ?
Agent : Votre nom est Max – vous venez de vous présenter !

---

Exemple Pratique 3 : Agent avec Outils

C'est ici que cela devient intéressant ! Les agents avec des outils peuvent effectuer de vraies actions :

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
from claude_agent_sdk.types import TextBlock, ToolUseBlock
import asyncio

SYSTEM_PROMPT = """Vous êtes un assistant de recherche avec accès aux outils.
Utilisez les outils disponibles pour accomplir les tâches :

- WebFetch : Récupère le contenu des pages web
- Read : Lit les fichiers locaux
- Grep : Recherche des patterns dans les fichiers
- Glob : Trouve des fichiers par patterns

Expliquez toujours quel outil vous utilisez et pourquoi."""

async def tool_agent():
    options = ClaudeAgentOptions(
        model="sonnet",
        system_prompt=SYSTEM_PROMPT,
        permission_mode="acceptEdits",
        allowed_tools=[
            "WebFetch",  # Récupérer du contenu web
            "Read",      # Lire des fichiers
            "Grep",      # Rechercher du texte
            "Glob",      # Trouver des fichiers
        ]
    )
    
    async with ClaudeSDKClient(options=options) as client:
        print("🔧 Agent Outils prêt !")
        print("Commandes : 'recherche [URL]', 'trouve [fichier]', etc.\n")
        
        while True:
            user_input = input("Vous : ").strip()
            
            if user_input.lower() == 'exit':
                break
            
            await client.query(user_input)
            
            async for message in client.receive_response():
                if hasattr(message, 'content'):
                    for block in message.content:
                        if isinstance(block, TextBlock):
                            print(f"Agent : {block.text}")
                        elif isinstance(block, ToolUseBlock):
                            print(f"🛠️ Utilisation outil : {block.name}")
                            print(f"   Paramètres : {block.input}")
            print()

if __name__ == "__main__":
    asyncio.run(tool_agent())

Outils Intégrés Disponibles

---

Exemple Pratique 4 : Agent Planificateur de Voyage Autonome

Construisons maintenant un agent entièrement autonome :

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
from claude_agent_sdk.types import TextBlock, ToolUseBlock, ToolResultBlock
import asyncio
import json

TRAVEL_SYSTEM_PROMPT = """Vous êtes un agent de planification de voyage autonome.

VOTRE OBJECTIF : Créer un plan de voyage complet selon les besoins de l'utilisateur.

VOTRE WORKFLOW :
1. Collecter toutes les informations nécessaires (date, budget, préférences)
2. Rechercher des options avec WebFetch
3. Créer un plan de voyage structuré
4. Présenter le plan et demander des retours

IMPORTANT :
- D'ABORD demander les informations manquantes
- Utiliser WebFetch pour des informations actuelles
- Créer un plan clair et structuré
- Proposer des alternatives

TOUJOURS commencer par une salutation amicale et demander la destination."""

async def travel_planner_agent():
    options = ClaudeAgentOptions(
        model="sonnet",
        system_prompt=TRAVEL_SYSTEM_PROMPT,
        permission_mode="acceptEdits",
        allowed_tools=["WebFetch", "Read", "Write"],
        max_turns=20  # Permet des boucles d'agent plus longues
    )
    
    async with ClaudeSDKClient(options=options) as client:
        print("✈️ Agent Planificateur de Voyage démarré !")
        print("=" * 50)
        
        # Salutation initiale de l'agent
        await client.query("Démarrer la planification de voyage pour un nouveau client.")
        
        async for message in client.receive_response():
            if hasattr(message, 'content'):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Agent : {block.text}")
        print()
        
        # Boucle interactive
        while True:
            user_input = input("Vous : ").strip()
            
            if user_input.lower() in ['exit', 'terminé', 'merci']:
                print("Agent : Je vous en prie ! Bon voyage ! 🌍✨")
                break
            
            await client.query(user_input)
            
            async for message in client.receive_response():
                if hasattr(message, 'content'):
                    for block in message.content:
                        if isinstance(block, TextBlock):
                            print(f"Agent : {block.text}")
                        elif isinstance(block, ToolUseBlock):
                            print(f"🔍 Recherche : {block.name}...")
            print()

if __name__ == "__main__":
    asyncio.run(travel_planner_agent())

---

Fonctionnalités Avancées : Intégration MCP

Le Model Context Protocol (MCP) permet l'intégration de services externes :

Inclure des Serveurs MCP

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

# Configuration du serveur MCP
MCP_CONFIG = {
    "utils": {
        "command": "npx",
        "args": ["-y", "mcp-remote", "https://your-mcp-server.com/api"]
    }
}

async def mcp_agent():
    options = ClaudeAgentOptions(
        model="sonnet",
        system_prompt="Vous avez accès aux outils MCP pour des fonctionnalités étendues.",
        permission_mode="acceptEdits",
        allowed_tools=[
            "WebFetch",
            "mcp__utils__save_note",   # Les outils MCP sont préfixés
            "mcp__utils__find_note",
        ],
        mcp_servers=MCP_CONFIG
    )
    
    async with ClaudeSDKClient(options=options) as client:
        await client.query("Créer une note avec le titre 'Important'")
        # ...

Créer Votre Propre Serveur MCP

# mcp_server.py - Serveur MCP simple
from mcp import Server

server = Server("my-tools")

@server.tool(name="save_note")
async def save_note(title: str, content: str) -> dict:
    """Sauvegarde une note."""
    # Votre logique ici
    return {"status": "success", "id": "note_123"}

@server.tool(name="find_note")
async def find_note(pattern: str) -> dict:
    """Trouve des notes par pattern."""
    # Votre logique ici
    return {"notes": [...]}

if __name__ == "__main__":
    import asyncio
    asyncio.run(server.run())

---

Sous-agents : Agents Spécialisés

Pour des tâches complexes, vous pouvez utiliser des sous-agents – des agents spécialisés qui gèrent des sous-tâches :

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

ORCHESTRATOR_PROMPT = """Vous êtes un coordinateur qui délègue des tâches à 
des sous-agents spécialisés :

- Agent Recherche : Pour la collecte d'informations
- Agent Rédaction : Pour la création de contenu
- Agent Analyse : Pour l'analyse de données

Déléguez les tâches selon leur type."""

async def orchestrator_agent():
    options = ClaudeAgentOptions(
        model="sonnet",
        system_prompt=ORCHESTRATOR_PROMPT,
        permission_mode="acceptEdits",
        allowed_tools=["SubAgent", "Read", "Write"],
        subagents_enabled=True  # Active les sous-agents
    )
    
    async with ClaudeSDKClient(options=options) as client:
        await client.query(
            "Rechercher les dernières tendances IA et créer un rapport."
        )
        # L'agent délègue automatiquement aux sous-agents

Quand Utiliser des Sous-agents ?

---

Hooks : Workflows Basés sur les Événements

Les Hooks permettent des actions automatisées sur des événements spécifiques :

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, HookMatcher

# Définir la fonction hook
async def log_tool_usage(event):
    """Journalise chaque utilisation d'outil."""
    print(f"📝 Log : L'outil '{event.tool_name}' a été appelé")
    return True  # Autorise l'exécution

async def block_dangerous_commands(event):
    """Bloque les commandes Bash dangereuses."""
    dangerous = ['rm -rf', 'sudo', 'chmod 777']
    if any(cmd in str(event.arguments) for cmd in dangerous):
        print("⚠️ Commande dangereuse bloquée !")
        return False  # Bloque l'exécution
    return True

async def hook_agent():
    options = ClaudeAgentOptions(
        model="sonnet",
        system_prompt="Vous êtes un assistant avec des hooks de sécurité.",
        permission_mode="acceptAll",
        allowed_tools=["Bash", "Write", "Read"],
        hooks={
            "PreToolUse": [
                HookMatcher(hooks=[log_tool_usage]),
                HookMatcher(
                    tool_name="Bash",
                    hooks=[block_dangerous_commands]
                )
            ]
        }
    )
    
    async with ClaudeSDKClient(options=options) as client:
        # ...

Types de Hooks

---

Meilleures Pratiques pour Agents Prêts pour la Production

1. Prompts Système Clairs

# ❌ Mauvais : Instructions vagues
SYSTEM_PROMPT = "Soyez utile."

# ✅ Bon : Rôle, limites et comportement clairs
SYSTEM_PROMPT = """Vous êtes un agent de service client pour TechCorp.

VOTRE RÔLE :
- Répondre aux questions sur nos produits
- Transférer les demandes complexes aux humains
- Documenter toutes les interactions

LIMITES :
- Pas de négociation de prix
- Pas de changements techniques sans approbation
- En cas de doute : Demander

COMPORTEMENT :
- Amical et professionnel
- Répondre dans la langue du client
- Résumer les sujets complexes"""

2. Définir les Permissions de Manière Granulaire

# ❌ Mauvais : Tout autoriser
permission_mode = "acceptAll"

# ✅ Bon : N'autoriser que les outils nécessaires
permission_mode = "acceptEdits"
allowed_tools = ["Read", "WebFetch"]  # Seulement ce qui est vraiment nécessaire

3. Implémenter la Gestion des Erreurs

async def resilient_agent():
    max_retries = 3
    
    for attempt in range(max_retries):
        try:
            async with ClaudeSDKClient(options=options) as client:
                await client.query(prompt)
                async for message in client.receive_response():
                    # Traitement
                    pass
                break  # Succès, sortir de la boucle
                
        except RateLimitError:
            wait_time = 2 ** attempt  # Backoff exponentiel
            print(f"Limite de taux atteinte. Attente de {wait_time}s...")
            await asyncio.sleep(wait_time)
            
        except Exception as e:
            print(f"Erreur : {e}")
            if attempt == max_retries - 1:
                raise

4. Gestion du Contexte

# Pour les longues conversations : Compresser le contexte
options = ClaudeAgentOptions(
    model="sonnet",
    system_prompt=SYSTEM_PROMPT,
    # Le SDK compresse automatiquement si nécessaire
    max_context_tokens=100000,  # Taille maximale du contexte
)

---

Coûts et Sélection de Modèle

Modèles Disponibles

Recommandation de Modèle par Cas d'Usage

---

Résumé : Votre Chemin vers Votre Premier Agent

Checklist pour Démarrer

• Python 3.10+ installé
• Clé API Anthropic créée
• claude-agent-sdk installé
• Agent Q&R simple testé
• Agent avec mémoire essayé
• Outils ajoutés
• Agent autonome construit

Prochaines Étapes

1. Expérimentez : Commencez avec l'agent Q&R simple
2. Étendez : Ajoutez des outils selon les besoins
3. Spécialisez : Créez des agents spécifiques au domaine
4. Scalez : Utilisez des sous-agents pour des workflows complexes
5. Sécurisez : Implémentez des hooks pour les environnements de production

---

Questions Fréquemment Posées (FAQ)

Quelle est la différence entre Claude Code et le Claude Agent SDK ?

Claude Code est l'assistant de codage complet d'Anthropic – un produit fini que vous pouvez utiliser dans votre terminal.

Le Claude Agent SDK est le framework sous-jacent qui vous permet de construire vos propres agents pour n'importe quel cas d'usage. Le SDK vous donne les blocs de construction qui alimentent également Claude Code.

Ai-je besoin de connaissances en programmation pour le SDK ?

Des connaissances de base en Python sont utiles mais pas strictement requises. Vous pouvez suivre les exemples simples de ce guide même sans expérience approfondie en programmation.

Cependant, pour des agents prêts pour la production, nous recommandons des bases solides en Python.

Combien coûte l'utilisation du Claude Agent SDK ?

L'utilisation du SDK lui-même est gratuite. Vous ne payez que pour les appels API à Claude.

Sonnet coûte environ 3$ par million de tokens d'entrée et 15$ par million de tokens de sortie (janvier 2026). Pour le développement et les tests, nous recommandons de commencer avec de petits contextes.

Puis-je utiliser le SDK avec d'autres modèles IA ?

Le Claude Agent SDK est spécifiquement optimisé pour les modèles Claude.

Pour d'autres modèles comme GPT-4 ou Gemini, il existe des SDKs alternatifs comme OpenAI Agents SDK ou Google ADK. Cependant, les concepts (Boucle d'Agent, Outils, Mémoire) sont transférables.

Comment sécuriser mon agent pour un usage en production ?

Trois étapes importantes :

1. Définissez permission_mode sur "manual" ou "acceptEdits" au lieu de "acceptAll"
2. Définissez explicitement allowed_tools avec uniquement les outils nécessaires
3. Implémentez des hooks pour les contrôles de sécurité et la journalisation

Pour les applications critiques, ajoutez des approbations humaines dans la boucle.

---

Ressources Supplémentaires

• Documentation Officielle : docs.claude.com/en/api/agent-sdk
• Blog Ingénierie Anthropic : anthropic.com/engineering
• Spécification MCP : modelcontextprotocol.io
• Claude Code : anthropic.com/claude-code

---

Ce guide a été créé pour les développeurs et les passionnés d'IA qui font leurs premiers pas avec les agents IA. Le Claude Code Agent SDK évolue constamment – visitez la documentation officielle pour les dernières mises à jour.