Guide d'utilisation du SDK Claude Agent

Le SDK Claude Agent vous permet de créer des agents IA qui peuvent lire des fichiers de manière autonome, exécuter des commandes, effectuer des recherches sur le web, modifier du code, et plus encore.

Le SDK Claude Agent expose les outils, la boucle d'agent et les capacités de gestion du contexte qui alimentent Claude Code en tant que bibliothèques Python et TypeScript programmables.

En termes simples, il s'agit d'un SDK qui utilise Claude Code comme bibliothèque. Vous pouvez l'intégrer dans vos propres applications, pipelines CI ou scripts d'automatisation pour créer des agents IA capables d'accomplir des tâches complexes de manière autonome.

Capacités principales

Le SDK inclut des outils intégrés pour lire des fichiers, exécuter des commandes et modifier du code. Votre agent n'a pas besoin d'implémenter lui-même la logique d'exécution des outils et peut commencer à travailler immédiatement. Les principales capacités incluent :

Capacité Description
Outils intégrés Lecture/écriture de fichiers, commandes terminal, édition de code, recherche web, etc.
Hooks Exécuter une logique personnalisée avant et après les appels d'outils
Sous-agents Décomposer les grandes tâches en tâches plus petites et les déléguer à des sous-agents indépendants pour une exécution parallèle
Serveur MCP Se connecter aux bases de données, navigateurs, API externes, etc.
Contrôle des permissions Contrôlez précisément ce que l'agent peut faire et quand l'approbation de l'utilisateur est requise
Gestion des sessions Créez des agents conversationnels multi-tours qui maintiennent le contexte

Prérequis

  • Node.js 18+(TypeScript) ouPython 3.10+
  • Uncompte Anthropic, et obtenez une clé API (Inscrivez-vous ici）

Étape 1 : Installer le SDK

TypeScript

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

Le SDK TypeScript inclut le binaire Claude Code pour votre plateforme actuelle en tant que dépendance optionnelle, il n'est donc pas nécessaire d'installer Claude Code séparément.

Python

# 使用 pip
pip install claude-agent-sdk

# 或使用 uv（推荐）
uv add claude-agent-sdk

Remarque : la CLI Claude Code est automatiquement installée avec le package—aucune installation séparée n'est nécessaire ! Le SDK utilise la CLI incluse par défaut.

Si vous préférez utiliser une installation au niveau du système ou une version spécifique, vous pouvez utiliserClaudeAgentOptions(cli_path="/path/to/claude")Spécifiez un chemin.

Étape 2 : Configurer la clé API

depuisClaude ConsoleObtenez une clé API, puis créez un fichier dans le répertoire du projet :.envfichier :

ANTHROPIC_API_KEY=your-api-key-here

Ou définissez-la directement comme variable d'environnement :

export ANTHROPIC_API_KEY=your-api-key-here

Prise en charge des plateformes cloud tierces

Le SDK prend également en charge l'authentification via des fournisseurs d'API tiers : Amazon Bedrock (définissez laCLAUDE_CODE_USE_BEDROCK=1variable d'environnement et configurez les identifiants AWS), Google Vertex AI (définissezCLAUDE_CODE_USE_VERTEX=1) et Microsoft Azure (définissezCLAUDE_CODE_USE_FOUNDRY=1）。

⚠️ Important: Sauf approbation préalable obtenue d'Anthropic, les développeurs tiers ne sont pas autorisés à fournir la connexion claude.ai ni la limitation de débit dans les produits construits sur le Claude Agent SDK. Veuillez utiliser la méthode d'authentification par clé API décrite dans la documentation.

Étape 3 : Exécutez votre premier agent

L'exemple suivant crée un agent qui liste les fichiers dans le répertoire courant :

Python

Exemple

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Quels fichiers se trouvent dans ce répertoire ?",
        options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

TypeScript

Exemple

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

async function main() {
  for await (const message of query({
    prompt: "Quels fichiers se trouvent dans ce répertoire ?",
    options: { allowedTools: ["Bash", "Glob"] },
  })) {
    if ("result" in message) {
      console.log(message.result);
    }
  }
}

main();

Atelier pratique : construire un agent qui corrige automatiquement les bugs

Voici un exemple complet démontrant l'utilisation essentielle du SDK Agent.

Préparer un fichier avec un bug

Créezutils.py, contenant deux bugs intentionnels :

Exemple

def calculate_average(numbers):
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)   # Bug : division par 0 quand la liste est vide

def get_user_name(user):
    return user["name"].upper()   # Bug : lève TypeError quand user est None

Écrire l'agent

Créezagent.py：

Exemple

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async def main():
    async for message in query(
        prompt="Examinez utils.py pour rechercher des bogues qui provoqueraient des plantages. Corrigez tous les problèmes que vous trouvez.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],  # Outils autorisés
            permission_mode="acceptEdits",            # Approuver automatiquement les modifications de fichiers
        ),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)          # Processus de raisonnement de Claude
                elif hasattr(block, "name"):
                    print(f"Outil : {block.name}") # Outil en cours d'appel
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")  # Résultat final

asyncio.run(main())

Exécutez

python agent.py

Après l'exécution, vérifiezutils.py, vous verrez que l'Agent a accompli de manière autonome les actions suivantes :

  1. Ludéjàutils.pyfichier
  2. Analyséla logique du code, identifié les cas limites pouvant causer des plantages
  3. Modifiéle fichier, ajouté une gestion complète des erreurs

Concepts fondamentaux expliqués

Fonctions – Point d'entrée de la boucle de l'Agent

queryest le point d'entrée principal pour créer une boucle d'Agent, renvoyant un itérateur asynchrone, donc vous utilisezasync forpour diffuser les messages générés par Claude en temps réel. La boucle se termine lorsque Claude termine la tâche ou rencontre une erreur. Le SDK gère l'orchestration (exécution des outils, gestion du contexte, nouvelles tentatives), et vous n'avez qu'à consommer ce flux de messages.

Chaque itération produit un message, qui peut être :

  • Processus de raisonnement de Claude
  • Un appel d'outil
  • Résultat de l'appel d'outil
  • Résultat final

Outils – Contrôlez ce que l'agent peut faire

Combinaisons d'outils Capacités de l'agent
Read, Glob, Grep Analyse en lecture
Read, Edit, Glob Analyser et modifier le code
Read, Edit, Bash, Glob, Grep Automatisation complète
PlusWebSearch Ajouter la capacité de recherche web

Modes d'autorisation – Contrôler le niveau de supervision humaine

Mode Comportement Cas d'utilisation
acceptEdits Approuver automatiquement les modifications de fichiers, les autres opérations nécessitent toujours une confirmation Flux de travail de développement approuvé
dontAsk RefuserallowedToolstoutes les opérations en dehors de Agent verrouillé sans surveillance
auto(TypeScript uniquement) Le classificateur de modèle approuve/refuse automatiquement chaque appel d'outil Agent autonome avec garde-fous de sécurité
bypassPermissions Exécuter tous les outils directement sans invite Environnement CI en bac à sable
default Doit fournircanUseToolFonction de rappel pour gérer l'approbation Processus d'approbation personnalisé

Personnaliser le comportement de l'Agent

Ajouter la recherche Web

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "WebSearch"],
    permission_mode="acceptEdits"
)

Ajouter des prompts système personnalisés

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob"],
    permission_mode="acceptEdits",
    system_prompt="You are a senior Python developer. Always follow PEP 8 style guidelines.",
)

Autoriser l'exécution des commandes du terminal

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "Bash"],
    permission_mode="acceptEdits"
)
# 可以尝试：
# prompt="Write unit tests for utils.py, run them, and fix any failures"

Charger la configuration du projet (CLAUDE.md, etc.)

Le SDK est construit sur la même base que Claude Code, et les Agents SDK peuvent accéder aux mêmes fonctionnalités basées sur le système de fichiers : instructions de projet (CLAUDE.md et règles), compétences, Hooks, etc. Par défaut, le SDK ne charge aucun paramètre du système de fichiers.

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit"],
    # "user" 从 ~/.claude/ 加载，"project" 从 ./.claude/ 加载
    setting_sources=["user", "project"],
)

Gestion des erreurs

from claude_agent_sdk import (
    ClaudeSDKError,      # 基础错误
    CLINotFoundError,    # Claude Code 未安装
    CLIConnectionError,  # 连接问题
    ProcessError,        # 进程失败
    CLIJSONDecodeError,  # JSON 解析失败
)

try:
    async for message in query(prompt="Hello"):
        pass
except CLINotFoundError:
    print("请先安装 Claude Code")
except ProcessError as e:
    print(f"进程失败，退出码：{e.exit_code}")
except CLIJSONDecodeError as e:
    print(f"响应解析失败：{e}")

Agent SDK vs. autres outils Claude

Agent SDK SDK client（Messages API） Claude Code CLI
Utilisation Bibliothèque Python/TypeScript Appels d'API HTTP Outil en ligne de commande dans le terminal
Exécution d'outils Intégré, exécution automatique Nécessite une implémentation manuelle Intégré, interactif
Cas d'utilisation Création d'agents autonomes, intégration d'applications Appels LLM généraux Assistance directe au codage
Gestion d'état Avec état, prend en charge les sessions Sans état Avec état, interactif

Tableau comparatif des fonctionnalités du SDK

Le SDK prend également en charge la configuration de Claude Code basée sur le système de fichiers. Pour utiliser ces fonctionnalités, définissez-les dans les optionssetting_sources=["project"](Python) ousettingSources: ['project']（TypeScript）。

Fonctionnalité Description Emplacement
Compétences Capacités spécialisées définies dans Markdown .claude/skills/*/SKILL.md
Commandes slash Commandes personnalisées pour les tâches courantes .claude/commands/*.md
Mémoire Contexte et instructions du projet CLAUDE.md
Plugins Viapluginsextensions d'options Configuré via le code
Autres extensions