Construire un agent IA autonome avec le Claude Agent SDK

Les agents IA représentent l'évolution naturelle des chatbots. Au lieu de simplement répondre à des questions, ils exécutent des tâches complexes de manière autonome : analyser du code, modifier des fichiers, interagir avec des APIs, et itérer jusqu'à atteindre un objectif. Le Claude Agent SDK, développé par Anthropic, fournit les briques nécessaires pour construire ce type d'agents. Ce guide vous accompagne de l'installation à la mise en production.

Qu'est-ce que le Claude Agent SDK ?

Le Claude Agent SDK est né de Claude Code, l'outil de développement d'Anthropic qui permet à Claude d'interagir directement avec un terminal et une base de code. Anthropic a extrait et généralisé cette infrastructure pour permettre aux développeurs de construire leurs propres agents.

Le principe fondamental du SDK est de donner à vos agents un ordinateur. Plutôt que de limiter Claude à de la génération de texte, le SDK lui permet d'écrire des fichiers, d'exécuter des commandes, de naviguer sur le web, et de vérifier son propre travail. Cette capacité d'action transforme un LLM en véritable assistant autonome.

Architecture d'un agent Claude

Chaque agent construit avec le SDK suit un pattern de feedback loop :

1. Gather context : L'agent collecte les informations nécessaires
2. Take action : Il exécute une opération via un outil
3. Verify work : Il vérifie le résultat de son action
4. Repeat : Il itère jusqu'à accomplir sa tâche

Cette boucle s'exécute de manière autonome. L'agent décide lui-même quand il a besoin de plus d'informations, quelle action entreprendre, et si le résultat est satisfaisant.

Installation et configuration

Prérequis

Le SDK nécessite :
- Python 3.10+ ou Node.js 18+
- Une clé API Anthropic
- Claude Code CLI (bundlé automatiquement avec le SDK)

Installation Python

pip install claude-agent-sdk

Installation TypeScript

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

Configuration de la clé API

Exportez votre clé API Anthropic :

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

Créer votre premier agent

Commençons par un agent simple qui peut saluer des utilisateurs. Cet exemple illustre les concepts de base : définition d'outils, création de serveur MCP, et configuration de l'agent.

Définir un outil custom

En Python, un outil custom est une fonction décorée avec @tool :

from claude_agent_sdk import tool, create_sdk_mcp_server

Le décorateur @tool prend trois arguments :
- Le nom de l'outil (utilisé par Claude pour l'invoquer)
- Une description (guide Claude sur quand utiliser cet outil)
- Le schéma des paramètres attendus

Créer le serveur MCP

Les outils sont exposés via un serveur MCP (Model Context Protocol) :

from claude_agent_sdk import create_sdk_mcp_server

Ce serveur s'exécute directement dans votre processus Python, sans nécessiter de service externe.

Configurer et lancer l'agent

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

options = ClaudeAgentOptions(
    mcp_servers={"tools": server},
    allowed_tools=["mcp__tools__greet"]
)

client = ClaudeSDKClient(options=options)

L'option allowed_tools restreint les outils disponibles pour l'agent. Le préfixe mcp__tools__ fait référence au serveur MCP nommé "tools".

Outils built-in

Le SDK inclut plusieurs outils prêts à l'emploi.

Opérations fichiers

L'agent peut lire, écrire et modifier des fichiers :

options = ClaudeAgentOptions(
    allowed_tools=["read_file", "write_file", "edit_file"]
)

Ces outils permettent à l'agent de manipuler du code, des configurations, ou tout fichier texte.

Exécution Bash

Pour les opérations système :

options = ClaudeAgentOptions(
    allowed_tools=["bash"]
)

L'outil bash permet d'exécuter des commandes shell : installer des dépendances, lancer des tests, compiler du code.

Recherche web

Pour accéder à des informations en ligne :

options = ClaudeAgentOptions(
    allowed_tools=["web_search", "web_fetch"]
)

L'agent peut rechercher sur le web et récupérer le contenu de pages.

Intégration MCP avancée

Le Model Context Protocol permet de connecter votre agent à des services externes de manière standardisée.

Configuration via .mcp.json

Créez un fichier .mcp.json à la racine de votre projet :

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem"],
      "env": {
        "ALLOWED_PATHS": "/home/user/projects"
      }
    },
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Cette configuration expose deux serveurs MCP : un pour les opérations fichiers avec des chemins restreints, et un pour interagir avec GitHub.

Serveurs MCP disponibles

L'écosystème MCP propose des intégrations pré-construites pour de nombreux services :

- GitHub : Créer des issues, pull requests, naviguer dans les repos
- Slack : Envoyer des messages, lire des channels
- PostgreSQL : Exécuter des requêtes SQL
- Puppeteer : Automatiser un navigateur web

Ces intégrations gèrent l'authentification automatiquement, simplifiant considérablement le développement.

Hooks pour la sécurité

Les hooks permettent d'intercepter et contrôler les actions de l'agent avant leur exécution.

Bloquer les commandes dangereuses

from claude_agent_sdk import hook

@hook("pre_tool_execution")
async def block_dangerous_bash(tool_name, args):
    if tool_name == "bash":
        command = args.get("command", "")
        dangerous_patterns = ["rm -rf", "sudo", "chmod 777"]

for pattern in dangerous_patterns:
            if pattern in command:
                return {
                    "action": "deny",
                    "message": f"Command blocked: contains '{pattern}'"
                }

Ce hook intercepte chaque appel à l'outil bash et refuse l'exécution si la commande contient des patterns dangereux.

Logger les actions

@hook("post_tool_execution")
async def log_actions(tool_name, args, result):
    print(f"[AUDIT] Tool: {tool_name}")
    print(f"[AUDIT] Args: {args}")
    print(f"[AUDIT] Result: {result[:100]}...")

Les hooks post-exécution permettent d'auditer toutes les actions de l'agent pour le debugging ou la conformité.

Gestion du contexte

Les agents peuvent fonctionner pendant de longues sessions. La gestion du contexte devient alors critique.

Compaction automatique

Le SDK compacte automatiquement le contexte quand il approche de la limite de la fenêtre. Les informations sont résumées pour préserver l'essentiel tout en libérant de l'espace.

Subagents

Pour les tâches complexes, l'agent principal peut déléguer à des subagents :

options = ClaudeAgentOptions(
    enable_subagents=True,
    max_subagent_depth=2
)

Chaque subagent possède sa propre fenêtre de contexte, permettant des recherches parallèles ou des analyses ciblées sans polluer le contexte principal.

Bonnes pratiques contextuelles

- Utilisez CLAUDE.md : Placez un fichier CLAUDE.md à la racine de votre projet avec les conventions, l'architecture, et les commandes importantes. L'agent s'y référera automatiquement.

- Préférez le retrieval aux dumps : Plutôt que d'injecter des logs complets, utilisez des outils de recherche pour récupérer les informations pertinentes à la demande.

- Compressez l'état global : Stockez uniquement le plan, les décisions clés, et les artefacts récents.

Exemple complet : Agent d'analyse de code

Voici un agent capable d'analyser une base de code et de générer un rapport :

from claude_agent_sdk import (
    ClaudeSDKClient,
    ClaudeAgentOptions,
    tool,
    create_sdk_mcp_server
)
import json

@tool("analyze_complexity", "Analyze code complexity metrics", {"file_path": str})
async def analyze_complexity(args):
    # Simulation d'analyse
    return {
        "content": [{
            "type": "text",
            "text": json.dumps({
                "file": args["file_path"],
                "lines": 150,
                "complexity": "medium",
                "suggestions": ["Consider extracting helper functions"]
            })
        }]
    }

@tool("generate_report", "Generate analysis report", {"findings": list})
async def generate_report(args):
    report = "# Code Analysis Report\n\n"
    for finding in args["findings"]:
        report += f"## {finding['file']}\n"
        report += f"- Lines: {finding['lines']}\n"
        report += f"- Complexity: {finding['complexity']}\n\n"
    return {"content": [{"type": "text", "text": report}]}

server = create_sdk_mcp_server(
    name="code-analyzer",
    version="1.0.0",
    tools=[analyze_complexity, generate_report]
)

options = ClaudeAgentOptions(
    mcp_servers={"analyzer": server},
    allowed_tools=[
        "read_file",
        "mcp__analyzer__analyze_complexity",
        "mcp__analyzer__generate_report"
    ]
)

client = ClaudeSDKClient(options=options)

Cet agent :
1. Utilise l'outil built-in read_file pour lire les fichiers
2. Appelle analyze_complexity pour chaque fichier Python trouvé
3. Agrège les résultats avec generate_report

Cas d'usage en production

Agent de support client

Un agent capable de :
- Rechercher dans la base de connaissances
- Créer des tickets dans le système de support
- Escalader aux humains si nécessaire

Assistant financier

Un agent qui :
- Récupère les données de marchés via API
- Analyse les portefeuilles
- Génère des recommandations basées sur des règles prédéfinies

Automatisation DevOps

Un agent pour :
- Monitorer les déploiements
- Analyser les logs d'erreur
- Proposer et appliquer des correctifs

Bonnes pratiques

Limiter les permissions

Ne donnez à l'agent que les outils strictement nécessaires. Un agent de recherche n'a pas besoin d'accès en écriture aux fichiers.

Implémenter des guardrails

Utilisez les hooks pour valider chaque action. Loggez tout pour l'audit. Définissez des limites de temps et de coût.

Tester exhaustivement

Les agents ont des comportements émergents. Testez avec des prompts adversariaux et des edge cases. Validez que les hooks bloquent effectivement les actions dangereuses.

Monitorer en production

Suivez les métriques : nombre d'itérations par tâche, taux de succès, tokens consommés. Identifiez les patterns problématiques.

Conclusion

Le Claude Agent SDK démocratise la création d'agents IA autonomes. En combinant la puissance de Claude avec des outils d'exécution et le protocole MCP, vous pouvez construire des assistants capables de tâches complexes qui auraient nécessité des heures de développement manuel.

Le SDK est open-source, activement maintenu, et bénéficie d'un écosystème MCP en pleine expansion. C'est le moment idéal pour expérimenter et intégrer des agents dans vos workflows.

Commencez petit : un agent qui automatise une tâche répétitive de votre quotidien. Puis itérez, ajoutez des outils, affinez les permissions. L'autonomie des agents ouvre des possibilités que nous commençons à peine à explorer.