Référence du SDK Python

Fonctions

`query()`

La fonction async principale pour interagir avec Claude Code. Retourne un itérateur async qui produit des messages au fur et à mesure qu’ils arrivent.

async def query(
    *,
    prompt: str | AsyncIterable[dict[str, Any]],
    options: ClaudeCodeOptions | None = None
) -> AsyncIterator[Message]

Paramètres

Paramètre	Type	Description
`prompt`	`str \| AsyncIterable[dict]`	Le prompt d’entrée sous forme de chaîne ou d’itérable async pour le mode streaming
`options`	`ClaudeCodeOptions \| None`	Objet de configuration optionnel (par défaut `ClaudeCodeOptions()` si None)

Retours

Retourne un AsyncIterator[Message] qui produit des messages de la conversation.

Exemple - Requête simple

import asyncio
from claude_code_sdk import query

async def main():
    async for message in query(prompt="Qu'est-ce que 2+2 ?"):
        print(message)

asyncio.run(main())

Exemple - Avec options


import asyncio
from claude_code_sdk import query, ClaudeCodeOptions

async def main():
    options = ClaudeCodeOptions(
        system_prompt="Vous êtes un développeur Python expert",
        permission_mode='acceptEdits',
        cwd="/home/user/project"
    )

    async for message in query(
        prompt="Créez un serveur web Python",
        options=options
    ):
        print(message)


asyncio.run(main())

`tool()`

Décorateur pour définir des outils MCP avec sécurité de type.

def tool(
    name: str,
    description: str,
    input_schema: type | dict[str, Any]
) -> Callable[[Callable[[Any], Awaitable[dict[str, Any]]]], SdkMcpTool[Any]]

Paramètres

Paramètre	Type	Description
`name`	`str`	Identifiant unique pour l’outil
`description`	`str`	Description lisible par l’humain de ce que fait l’outil
`input_schema`	`type \| dict[str, Any]`	Schéma définissant les paramètres d’entrée de l’outil (voir ci-dessous)

Options de schéma d’entrée

Mappage de type simple (recommandé) :

{"text": str, "count": int, "enabled": bool}

Format de schéma JSON (pour validation complexe) :

{
    "type": "object",
    "properties": {
        "text": {"type": "string"},
        "count": {"type": "integer", "minimum": 0}
    },
    "required": ["text"]
}

Retours

Une fonction décorateur qui encapsule l’implémentation de l’outil et retourne une instance SdkMcpTool.

Exemple

from claude_code_sdk import tool
from typing import Any

@tool("greet", "Saluer un utilisateur", {"name": str})
async def greet(args: dict[str, Any]) -> dict[str, Any]:
    return {
        "content": [{
            "type": "text",
            "text": f"Bonjour, {args['name']} !"
        }]
    }

`create_sdk_mcp_server()`

Créer un serveur MCP en processus qui s’exécute dans votre application Python.

def create_sdk_mcp_server(
    name: str,
    version: str = "1.0.0",
    tools: list[SdkMcpTool[Any]] | None = None
) -> McpSdkServerConfig

Paramètres

Paramètre	Type	Défaut	Description
`name`	`str`	-	Identifiant unique pour le serveur
`version`	`str`	`"1.0.0"`	Chaîne de version du serveur
`tools`	`list[SdkMcpTool[Any]] \| None`	`None`	Liste des fonctions d’outils créées avec le décorateur `@tool`

Retours

Retourne un objet McpSdkServerConfig qui peut être passé à ClaudeCodeOptions.mcp_servers.

Exemple

from claude_code_sdk import tool, create_sdk_mcp_server

@tool("add", "Additionner deux nombres", {"a": float, "b": float})
async def add(args):
    return {
        "content": [{
            "type": "text",
            "text": f"Somme : {args['a'] + args['b']}"
        }]
    }

@tool("multiply", "Multiplier deux nombres", {"a": float, "b": float})
async def multiply(args):
    return {
        "content": [{
            "type": "text",
            "text": f"Produit : {args['a'] * args['b']}"
        }]
    }

calculator = create_sdk_mcp_server(
    name="calculator",
    version="2.0.0",
    tools=[add, multiply]  # Passer les fonctions décorées
)

# Utiliser avec Claude
options = ClaudeCodeOptions(
    mcp_servers={"calc": calculator},
    allowed_tools=["mcp__calc__add", "mcp__calc__multiply"]
)

Classes

`ClaudeSDKClient`

Client pour des conversations bidirectionnelles et interactives avec Claude Code. Fournit un contrôle complet sur le flux de conversation avec support pour le streaming, les interruptions et l’envoi dynamique de messages.

class ClaudeSDKClient:
    def __init__(self, options: ClaudeCodeOptions | None = None)
    async def connect(self, prompt: str | AsyncIterable[dict] | None = None) -> None
    async def query(self, prompt: str | AsyncIterable[dict], session_id: str = "default") -> None
    async def receive_messages(self) -> AsyncIterator[Message]
    async def receive_response(self) -> AsyncIterator[Message]
    async def interrupt(self) -> None
    async def disconnect(self) -> None

Méthodes

Méthode	Description
`__init__(options)`	Initialiser le client avec une configuration optionnelle
`connect(prompt)`	Se connecter à Claude avec un prompt initial optionnel ou un flux de messages
`query(prompt, session_id)`	Envoyer une nouvelle requête en mode streaming
`receive_messages()`	Recevoir tous les messages de Claude comme un itérateur async
`receive_response()`	Recevoir des messages jusqu’à et y compris un ResultMessage
`interrupt()`	Envoyer un signal d’interruption (fonctionne seulement en mode streaming)
`disconnect()`	Se déconnecter de Claude

Support du gestionnaire de contexte

Le client peut être utilisé comme un gestionnaire de contexte async pour la gestion automatique des connexions :

async with ClaudeSDKClient() as client:
    await client.query("Bonjour Claude")
    async for message in client.receive_response():
        print(message)

Important : Lors de l’itération sur les messages, évitez d’utiliser break pour sortir prématurément car cela peut causer des problèmes de nettoyage asyncio. Au lieu de cela, laissez l’itération se terminer naturellement ou utilisez des drapeaux pour suivre quand vous avez trouvé ce dont vous avez besoin.

Exemple - Conversation interactive

import asyncio
from claude_code_sdk import ClaudeSDKClient, AssistantMessage, TextBlock, ResultMessage

async def main():
    async with ClaudeSDKClient() as client:
        # Envoyer le message initial
        await client.query("Résolvons un problème de mathématiques étape par étape")
        
        # Recevoir et traiter la réponse
        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Assistant : {block.text[:100]}...")
            elif isinstance(message, ResultMessage):
                print("Réponse terminée")
        
        # Envoyer un suivi basé sur la réponse
        await client.query("Combien font 15% de 80 ?")

asyncio.run(main())

Types

`SdkMcpTool`

Définition pour un outil MCP SDK créé avec le décorateur @tool.

@dataclass
class SdkMcpTool(Generic[T]):
    name: str
    description: str
    input_schema: type[T] | dict[str, Any]
    handler: Callable[[T], Awaitable[dict[str, Any]]]

Propriété	Type	Description
`name`	`str`	Identifiant unique pour l’outil
`description`	`str`	Description lisible par l’humain
`input_schema`	`type[T] \| dict[str, Any]`	Schéma pour la validation d’entrée
`handler`	`Callable[[T], Awaitable[dict[str, Any]]]`	Fonction async qui gère l’exécution de l’outil

`ClaudeCodeOptions`

Dataclass de configuration pour les requêtes Claude Code.

@dataclass
class ClaudeCodeOptions:
    allowed_tools: list[str] = field(default_factory=list)
    max_thinking_tokens: int = 8000
    system_prompt: str | None = None
    append_system_prompt: str | None = None
    mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)
    permission_mode: PermissionMode | None = None
    continue_conversation: bool = False
    resume: str | None = None
    max_turns: int | None = None
    disallowed_tools: list[str] = field(default_factory=list)
    model: str | None = None
    permission_prompt_tool_name: str | None = None
    cwd: str | Path | None = None
    settings: str | None = None
    add_dirs: list[str | Path] = field(default_factory=list)
    env: dict[str, str] = field(default_factory=dict)
    extra_args: dict[str, str | None] = field(default_factory=dict)

Propriété	Type	Défaut	Description
`allowed_tools`	`list[str]`	`[]`	Liste des noms d’outils autorisés
`max_thinking_tokens`	`int`	`8000`	Tokens maximum pour le processus de réflexion
`system_prompt`	`str \| None`	`None`	Remplacer entièrement le prompt système par défaut
`append_system_prompt`	`str \| None`	`None`	Texte à ajouter au prompt système par défaut
`mcp_servers`	`dict[str, McpServerConfig] \| str \| Path`	`{}`	Configurations de serveur MCP ou chemin vers le fichier de configuration
`permission_mode`	`PermissionMode \| None`	`None`	Mode de permission pour l’utilisation des outils
`continue_conversation`	`bool`	`False`	Continuer la conversation la plus récente
`resume`	`str \| None`	`None`	ID de session à reprendre
`max_turns`	`int \| None`	`None`	Tours de conversation maximum
`disallowed_tools`	`list[str]`	`[]`	Liste des noms d’outils interdits
`model`	`str \| None`	`None`	Modèle Claude à utiliser
`permission_prompt_tool_name`	`str \| None`	`None`	Nom d’outil MCP pour les prompts de permission
`cwd`	`str \| Path \| None`	`None`	Répertoire de travail actuel
`settings`	`str \| None`	`None`	Chemin vers le fichier de paramètres
`add_dirs`	`list[str \| Path]`	`[]`	Répertoires supplémentaires auxquels Claude peut accéder
`extra_args`	`dict[str, str \| None]`	`{}`	Arguments CLI supplémentaires à passer directement au CLI
`can_use_tool`	`CanUseTool \| None`	`None`	Fonction de rappel de permission d’outil
`hooks`	`dict[HookEvent, list[HookMatcher]] \| None`	`None`	Configurations de hook pour intercepter les événements

`PermissionMode`

Modes de permission pour contrôler l’exécution des outils.

PermissionMode = Literal[
    "default",           # Comportement de permission standard
    "acceptEdits",       # Auto-accepter les modifications de fichiers
    "plan",              # Mode planification - pas d'exécution
    "bypassPermissions"  # Contourner toutes les vérifications de permission (utiliser avec précaution)
]

`McpSdkServerConfig`

Configuration pour les serveurs MCP SDK créés avec create_sdk_mcp_server().

class McpSdkServerConfig(TypedDict):
    type: Literal["sdk"]
    name: str
    instance: Any  # Instance de serveur MCP

`McpServerConfig`

Type union pour les configurations de serveur MCP.

McpServerConfig = McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig

`McpStdioServerConfig`

class McpStdioServerConfig(TypedDict):
    type: NotRequired[Literal["stdio"]]  # Optionnel pour la compatibilité ascendante
    command: str
    args: NotRequired[list[str]]
    env: NotRequired[dict[str, str]]

`McpSSEServerConfig`

class McpSSEServerConfig(TypedDict):
    type: Literal["sse"]
    url: str
    headers: NotRequired[dict[str, str]]

`McpHttpServerConfig`

class McpHttpServerConfig(TypedDict):
    type: Literal["http"]
    url: str
    headers: NotRequired[dict[str, str]]

Types de messages

`Message`

Type union de tous les messages possibles.

Message = UserMessage | AssistantMessage | SystemMessage | ResultMessage

`UserMessage`

Message d’entrée utilisateur.

@dataclass
class UserMessage:
    content: str | list[ContentBlock]

`AssistantMessage`

Message de réponse de l’assistant avec blocs de contenu.

@dataclass
class AssistantMessage:
    content: list[ContentBlock]
    model: str

`SystemMessage`

Message système avec métadonnées.

@dataclass
class SystemMessage:
    subtype: str
    data: dict[str, Any]

`ResultMessage`

Message de résultat final avec informations de coût et d’utilisation.

@dataclass
class ResultMessage:
    subtype: str
    duration_ms: int
    duration_api_ms: int
    is_error: bool
    num_turns: int
    session_id: str
    total_cost_usd: float | None = None
    usage: dict[str, Any] | None = None
    result: str | None = None

Types de blocs de contenu

`ContentBlock`

Type union de tous les blocs de contenu.

ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock

`TextBlock`

Bloc de contenu texte.

@dataclass
class TextBlock:
    text: str

`ThinkingBlock`

Bloc de contenu de réflexion (pour les modèles avec capacité de réflexion).

@dataclass
class ThinkingBlock:
    thinking: str
    signature: str

`ToolUseBlock`

Bloc de demande d’utilisation d’outil.

@dataclass
class ToolUseBlock:
    id: str
    name: str
    input: dict[str, Any]

`ToolResultBlock`

Bloc de résultat d’exécution d’outil.

@dataclass
class ToolResultBlock:
    tool_use_id: str
    content: str | list[dict[str, Any]] | None = None
    is_error: bool | None = None

Types d’erreur

`ClaudeSDKError`

Classe d’exception de base pour toutes les erreurs SDK.

class ClaudeSDKError(Exception):
    """Erreur de base pour Claude SDK."""

`CLINotFoundError`

Levée quand le CLI Claude Code n’est pas installé ou introuvable.

class CLINotFoundError(CLIConnectionError):
    def __init__(self, message: str = "Claude Code introuvable", cli_path: str | None = None):
        """
        Args:
            message: Message d'erreur (défaut : "Claude Code introuvable")
            cli_path: Chemin optionnel vers le CLI qui n'a pas été trouvé
        """

`CLIConnectionError`

Levée quand la connexion à Claude Code échoue.

class CLIConnectionError(ClaudeSDKError):
    """Échec de connexion à Claude Code."""

`ProcessError`

Levée quand le processus Claude Code échoue.

class ProcessError(ClaudeSDKError):
    def __init__(self, message: str, exit_code: int | None = None, stderr: str | None = None):
        self.exit_code = exit_code
        self.stderr = stderr

`CLIJSONDecodeError`

Levée quand l’analyse JSON échoue.

class CLIJSONDecodeError(ClaudeSDKError):
    def __init__(self, line: str, original_error: Exception):
        """
        Args:
            line: La ligne qui a échoué à être analysée
            original_error: L'exception de décodage JSON originale
        """
        self.line = line
        self.original_error = original_error

Types de hook

`HookEvent`

Types d’événements de hook supportés. Notez qu’en raison de limitations de configuration, le SDK Python ne supporte pas les hooks SessionStart, SessionEnd et Notification.

HookEvent = Literal[
    "PreToolUse",      # Appelé avant l'exécution d'outil
    "PostToolUse",     # Appelé après l'exécution d'outil
    "UserPromptSubmit", # Appelé quand l'utilisateur soumet un prompt
    "Stop",            # Appelé lors de l'arrêt de l'exécution
    "SubagentStop",    # Appelé quand un sous-agent s'arrête
    "PreCompact"       # Appelé avant la compaction de messages
]

`HookCallback`

Définition de type pour les fonctions de rappel de hook.

HookCallback = Callable[
    [dict[str, Any], str | None, HookContext],
    Awaitable[dict[str, Any]]
]

Paramètres :

input_data : Données d’entrée spécifiques au hook (voir documentation des hooks)
tool_use_id : Identifiant d’utilisation d’outil optionnel (pour les hooks liés aux outils)
context : Contexte de hook avec informations supplémentaires

Retourne un dictionnaire qui peut contenir :

decision : "block" pour bloquer l’action
systemMessage : Message système à ajouter à la transcription
hookSpecificOutput : Données de sortie spécifiques au hook

`HookContext`

Informations de contexte passées aux rappels de hook.

@dataclass
class HookContext:
    signal: Any | None = None  # Futur : support du signal d'abandon

`HookMatcher`

Configuration pour faire correspondre les hooks à des événements ou outils spécifiques.

@dataclass
class HookMatcher:
    matcher: str | None = None        # Nom d'outil ou motif à faire correspondre (ex. "Bash", "Write|Edit")
    hooks: list[HookCallback] = field(default_factory=list)  # Liste des rappels à exécuter

Exemple d’utilisation de hook

from claude_code_sdk import query, ClaudeCodeOptions, HookMatcher, HookContext
from typing import Any

async def validate_bash_command(
    input_data: dict[str, Any],
    tool_use_id: str | None,
    context: HookContext
) -> dict[str, Any]:
    """Valider et potentiellement bloquer les commandes bash dangereuses."""
    if input_data['tool_name'] == 'Bash':
        command = input_data['tool_input'].get('command', '')
        if 'rm -rf /' in command:
            return {
                'hookSpecificOutput': {
                    'hookEventName': 'PreToolUse',
                    'permissionDecision': 'deny',
                    'permissionDecisionReason': 'Commande dangereuse bloquée'
                }
            }
    return {}

async def log_tool_use(
    input_data: dict[str, Any],
    tool_use_id: str | None,
    context: HookContext
) -> dict[str, Any]:
    """Enregistrer toute utilisation d'outil pour audit."""
    print(f"Outil utilisé : {input_data.get('tool_name')}")
    return {}

options = ClaudeCodeOptions(
    hooks={
        'PreToolUse': [
            HookMatcher(matcher='Bash', hooks=[validate_bash_command]),
            HookMatcher(hooks=[log_tool_use])  # S'applique à tous les outils
        ],
        'PostToolUse': [
            HookMatcher(hooks=[log_tool_use])
        ]
    }
)

async for message in query(
    prompt="Analysez cette base de code",
    options=options
):
    print(message)

Types d’entrée/sortie d’outil

Documentation des schémas d’entrée/sortie pour tous les outils intégrés Claude Code. Bien que le SDK Python n’exporte pas ceux-ci comme types, ils représentent la structure des entrées et sorties d’outils dans les messages.

Task

Nom d’outil : Task Entrée :

{
    "description": str,      # Une description courte (3-5 mots) de la tâche
    "prompt": str,           # La tâche que l'agent doit effectuer
    "subagent_type": str     # Le type d'agent spécialisé à utiliser
}

Sortie :

{
    "result": str,                    # Résultat final du sous-agent
    "usage": dict | None,             # Statistiques d'utilisation des tokens
    "total_cost_usd": float | None,  # Coût total en USD
    "duration_ms": int | None         # Durée d'exécution en millisecondes
}

Bash

Nom d’outil : Bash Entrée :

{
    "command": str,                  # La commande à exécuter
    "timeout": int | None,           # Timeout optionnel en millisecondes (max 600000)
    "description": str | None,       # Description claire et concise (5-10 mots)
    "run_in_background": bool | None # Définir à true pour exécuter en arrière-plan
}

Sortie :

{
    "output": str,              # Sortie combinée stdout et stderr
    "exitCode": int,            # Code de sortie de la commande
    "killed": bool | None,      # Si la commande a été tuée à cause du timeout
    "shellId": str | None       # ID de shell pour les processus en arrière-plan
}

Edit

Nom d’outil : Edit Entrée :

{
    "file_path": str,           # Le chemin absolu vers le fichier à modifier
    "old_string": str,          # Le texte à remplacer
    "new_string": str,          # Le texte par lequel le remplacer
    "replace_all": bool | None  # Remplacer toutes les occurrences (défaut False)
}

Sortie :

{
    "message": str,      # Message de confirmation
    "replacements": int, # Nombre de remplacements effectués
    "file_path": str     # Chemin du fichier qui a été édité
}

MultiEdit

Nom d’outil : MultiEdit Entrée :

{
    "file_path": str,     # Le chemin absolu vers le fichier à modifier
    "edits": [            # Tableau d'opérations d'édition
        {
            "old_string": str,          # Le texte à remplacer
            "new_string": str,          # Le texte par lequel le remplacer
            "replace_all": bool | None  # Remplacer toutes les occurrences
        }
    ]
}

Sortie :

{
    "message": str,       # Message de succès
    "edits_applied": int, # Nombre total d'éditions appliquées
    "file_path": str      # Chemin du fichier qui a été édité
}

Read

Nom d’outil : Read Entrée :

{
    "file_path": str,       # Le chemin absolu vers le fichier à lire
    "offset": int | None,   # Le numéro de ligne à partir duquel commencer la lecture
    "limit": int | None     # Le nombre de lignes à lire
}

Sortie (Fichiers texte) :

{
    "content": str,         # Contenu du fichier avec numéros de ligne
    "total_lines": int,     # Nombre total de lignes dans le fichier
    "lines_returned": int   # Lignes réellement retournées
}

Sortie (Images) :

{
    "image": str,       # Données d'image encodées en Base64
    "mime_type": str,   # Type MIME de l'image
    "file_size": int    # Taille du fichier en octets
}

Write

Nom d’outil : Write Entrée :

{
    "file_path": str,  # Le chemin absolu vers le fichier à écrire
    "content": str     # Le contenu à écrire dans le fichier
}

Sortie :

{
    "message": str,        # Message de succès
    "bytes_written": int,  # Nombre d'octets écrits
    "file_path": str       # Chemin du fichier qui a été écrit
}

Glob

Nom d’outil : Glob Entrée :

{
    "pattern": str,       # Le motif glob pour faire correspondre les fichiers
    "path": str | None    # Le répertoire dans lequel chercher (par défaut cwd)
}

Sortie :

{
    "matches": list[str],  # Tableau des chemins de fichiers correspondants
    "count": int,          # Nombre de correspondances trouvées
    "search_path": str     # Répertoire de recherche utilisé
}

Grep

Nom d’outil : Grep Entrée :

{
    "pattern": str,                    # Le motif d'expression régulière
    "path": str | None,                # Fichier ou répertoire dans lequel chercher
    "glob": str | None,                # Motif glob pour filtrer les fichiers
    "type": str | None,                # Type de fichier à chercher
    "output_mode": str | None,         # "content", "files_with_matches", ou "count"
    "-i": bool | None,                 # Recherche insensible à la casse
    "-n": bool | None,                 # Afficher les numéros de ligne
    "-B": int | None,                  # Lignes à afficher avant chaque correspondance
    "-A": int | None,                  # Lignes à afficher après chaque correspondance
    "-C": int | None,                  # Lignes à afficher avant et après
    "head_limit": int | None,          # Limiter la sortie aux N premières lignes/entrées
    "multiline": bool | None           # Activer le mode multiligne
}

Sortie (mode content) :

{
    "matches": [
        {
            "file": str,
            "line_number": int | None,
            "line": str,
            "before_context": list[str] | None,
            "after_context": list[str] | None
        }
    ],
    "total_matches": int
}

Sortie (mode files_with_matches) :

{
    "files": list[str],  # Fichiers contenant des correspondances
    "count": int         # Nombre de fichiers avec correspondances
}

NotebookEdit

Nom d’outil : NotebookEdit Entrée :

{
    "notebook_path": str,                     # Chemin absolu vers le notebook Jupyter
    "cell_id": str | None,                    # L'ID de la cellule à éditer
    "new_source": str,                        # La nouvelle source pour la cellule
    "cell_type": "code" | "markdown" | None,  # Le type de la cellule
    "edit_mode": "replace" | "insert" | "delete" | None  # Type d'opération d'édition
}

Sortie :

{
    "message": str, # Message de succès
    "edit_type": "replaced" | "inserted" | "deleted",  # Type d'édition effectuée
    "cell_id": str | None,                       # ID de cellule qui a été affectée
    "total_cells": int                           # Total des cellules dans le notebook après édition
}

WebFetch

Nom d’outil : WebFetch Entrée :

{
    "url": str,     # L'URL à partir de laquelle récupérer le contenu
    "prompt": str   # Le prompt à exécuter sur le contenu récupéré
}

Sortie :

{
    "response": str,           # Réponse du modèle IA au prompt
    "url": str,                # URL qui a été récupérée
    "final_url": str | None,   # URL finale après redirections
    "status_code": int | None  # Code de statut HTTP
}

WebSearch

Nom d’outil : WebSearch Entrée :

{
    "query": str,                        # La requête de recherche à utiliser
    "allowed_domains": list[str] | None, # Inclure seulement les résultats de ces domaines
    "blocked_domains": list[str] | None  # Ne jamais inclure les résultats de ces domaines
}

Sortie :

{
    "results": [
        {
            "title": str,
            "url": str,
            "snippet": str,
            "metadata": dict | None
        }
    ],
    "total_results": int,
    "query": str
}

TodoWrite

Nom d’outil : TodoWrite Entrée :

{
    "todos": [
        {
            "content": str, # La description de la tâche
            "status": "pending" | "in_progress" | "completed",  # Statut de la tâche
            "activeForm": str                            # Forme active de la description
        }
    ]
}

Sortie :

{
    "message": str,  # Message de succès
    "stats": {
        "total": int,
        "pending": int,
        "in_progress": int,
        "completed": int
    }
}

BashOutput

Nom d’outil : BashOutput Entrée :

{
    "bash_id": str,       # L'ID du shell en arrière-plan
    "filter": str | None  # Regex optionnel pour filtrer les lignes de sortie
}

Sortie :

{
    "output": str, # Nouvelle sortie depuis la dernière vérification
    "status": "running" | "completed" | "failed",       # Statut actuel du shell
    "exitCode": int | None # Code de sortie quand terminé
}

KillBash

Nom d’outil : KillBash Entrée :

{
    "shell_id": str  # L'ID du shell en arrière-plan à tuer
}

Sortie :

{
    "message": str,  # Message de succès
    "shell_id": str  # ID du shell tué
}

ExitPlanMode

Nom d’outil : ExitPlanMode Entrée :

{
    "plan": str  # Le plan à exécuter par l'utilisateur pour approbation
}

Sortie :

{
    "message": str,          # Message de confirmation
    "approved": bool | None  # Si l'utilisateur a approuvé le plan
}

ListMcpResources

Nom d’outil : ListMcpResources Entrée :

{
    "server": str | None  # Nom de serveur optionnel pour filtrer les ressources par
}

Sortie :

{
    "resources": [
        {
            "uri": str,
            "name": str,
            "description": str | None,
            "mimeType": str | None,
            "server": str
        }
    ],
    "total": int
}

ReadMcpResource

Nom d’outil : ReadMcpResource Entrée :

{
    "server": str,  # Le nom du serveur MCP
    "uri": str      # L'URI de ressource à lire
}

Sortie :

{
    "contents": [
        {
            "uri": str,
            "mimeType": str | None,
            "text": str | None,
            "blob": str | None
        }
    ],
    "server": str
}

Exemple d’utilisation

Opérations de fichier de base

from claude_code_sdk import query, ClaudeCodeOptions, AssistantMessage, ToolUseBlock
import asyncio

async def create_project():
    options = ClaudeCodeOptions(
        allowed_tools=["Read", "Write", "Bash"],
        permission_mode='acceptEdits',
        cwd="/home/user/project"
    )
    
    async for message in query(
        prompt="Créez une structure de projet Python avec setup.py",
        options=options
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, ToolUseBlock):
                    print(f"Utilisation de l'outil : {block.name}")

asyncio.run(create_project())

Gestion d’erreur

from claude_code_sdk import (
    query,
    CLINotFoundError,
    ProcessError,
    CLIJSONDecodeError
)

try:
    async for message in query(prompt="Bonjour"):
        print(message)
except CLINotFoundError:
    print("Veuillez installer Claude Code : npm install -g @anthropic-ai/claude-code")
except ProcessError as e:
    print(f"Le processus a échoué avec le code de sortie : {e.exit_code}")
except CLIJSONDecodeError as e:
    print(f"Échec d'analyse de la réponse : {e}")

Mode streaming avec client

from claude_code_sdk import ClaudeSDKClient
import asyncio

async def interactive_session():
    async with ClaudeSDKClient() as client:
        # Envoyer le message initial
        await client.query("Quel temps fait-il ?")
        
        # Traiter les réponses
        async for msg in client.receive_response():
            print(msg)
        
        # Envoyer un suivi
        await client.query("Dites-moi en plus à ce sujet")
        
        # Traiter la réponse de suivi
        async for msg in client.receive_response():
            print(msg)

asyncio.run(interactive_session())

Utilisation d’outils personnalisés

from claude_code_sdk import (
    query,
    ClaudeCodeOptions,
    tool,
    create_sdk_mcp_server,
    AssistantMessage,
    TextBlock
)
import asyncio
from typing import Any

# Définir des outils personnalisés avec le décorateur @tool
@tool("calculate", "Effectuer des calculs mathématiques", {"expression": str})
async def calculate(args: dict[str, Any]) -> dict[str, Any]:
    try:
        result = eval(args["expression"], {"__builtins__": {}})
        return {
            "content": [{
                "type": "text",
                "text": f"Résultat : {result}"
            }]
        }
    except Exception as e:
        return {
            "content": [{
                "type": "text",
                "text": f"Erreur : {str(e)}"
            }],
            "is_error": True
        }

@tool("get_time", "Obtenir l'heure actuelle", {})
async def get_time(args: dict[str, Any]) -> dict[str, Any]:
    from datetime import datetime
    current_time = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
    return {
        "content": [{
            "type": "text",
            "text": f"Heure actuelle : {current_time}"
        }]
    }

async def main():
    # Créer un serveur MCP SDK avec des outils personnalisés
    my_server = create_sdk_mcp_server(
        name="utilities",
        version="1.0.0",
        tools=[calculate, get_time]
    )
    
    # Configurer les options avec le serveur
    options = ClaudeCodeOptions(
        mcp_servers={"utils": my_server},
        allowed_tools=[
            "mcp__utils__calculate",
            "mcp__utils__get_time"
        ]
    )
    
    # Interroger Claude avec des outils personnalisés disponibles
    async for message in query(
        prompt="Combien font 123 * 456 et quelle heure est-il ?",
        options=options
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(block.text)

asyncio.run(main())

Voir aussi

Guide du SDK Python - Tutoriel et exemples
Aperçu du SDK - Concepts généraux du SDK
Référence du SDK TypeScript - Documentation du SDK TypeScript
Référence CLI - Interface en ligne de commande
Flux de travail courants - Guides étape par étape

Commencer

Créer avec Claude Code

SDK de code Claude

Déploiement

Administration

Configuration

Référence

Ressources

​Fonctions

​query()

​Paramètres

​Retours

​Exemple - Requête simple

​Exemple - Avec options

​tool()

​Paramètres

​Options de schéma d’entrée

​Retours

​Exemple

​create_sdk_mcp_server()

​Paramètres

​Retours

​Exemple

​Classes

​ClaudeSDKClient

​Méthodes

​Support du gestionnaire de contexte

​Exemple - Conversation interactive

​Types

​SdkMcpTool

​ClaudeCodeOptions

​PermissionMode

​McpSdkServerConfig

​McpServerConfig

​McpStdioServerConfig

​McpSSEServerConfig

​McpHttpServerConfig

​Types de messages

​Message

​UserMessage

​AssistantMessage

​SystemMessage

​ResultMessage

​Types de blocs de contenu

​ContentBlock

​TextBlock

​ThinkingBlock

​ToolUseBlock

​ToolResultBlock

​Types d’erreur

​ClaudeSDKError

​CLINotFoundError

​CLIConnectionError

​ProcessError

​CLIJSONDecodeError

​Types de hook

​HookEvent

​HookCallback

​HookContext

​HookMatcher

​Exemple d’utilisation de hook

​Types d’entrée/sortie d’outil

​Task

​Bash

​Edit

​MultiEdit

​Read

​Write

​Glob

​Grep

​NotebookEdit

​WebFetch

​WebSearch

​TodoWrite

​BashOutput

​KillBash

​ExitPlanMode

​ListMcpResources

​ReadMcpResource

​Exemple d’utilisation

Fonctions

`query()`

Paramètres

Retours

Exemple - Requête simple

Exemple - Avec options

`tool()`

Paramètres

Options de schéma d’entrée

Retours

Exemple

`create_sdk_mcp_server()`

Paramètres

Retours

Exemple

Classes

`ClaudeSDKClient`

Méthodes

Support du gestionnaire de contexte

Exemple - Conversation interactive

Types

`SdkMcpTool`

`ClaudeCodeOptions`

`PermissionMode`

`McpSdkServerConfig`

`McpServerConfig`

`McpStdioServerConfig`

`McpSSEServerConfig`

`McpHttpServerConfig`

Types de messages

`Message`

`UserMessage`

`AssistantMessage`

`SystemMessage`

`ResultMessage`

Types de blocs de contenu

`ContentBlock`

`TextBlock`

`ThinkingBlock`

`ToolUseBlock`

`ToolResultBlock`

Types d’erreur

`ClaudeSDKError`

`CLINotFoundError`

`CLIConnectionError`

`ProcessError`

`CLIJSONDecodeError`

Types de hook

`HookEvent`

`HookCallback`

`HookContext`

`HookMatcher`

Exemple d’utilisation de hook

Types d’entrée/sortie d’outil

Task

Bash

Edit

MultiEdit

Read

Write

Glob

Grep

NotebookEdit

WebFetch

WebSearch

TodoWrite

BashOutput

KillBash

ExitPlanMode

ListMcpResources

ReadMcpResource

Exemple d’utilisation

Opérations de fichier de base

Gestion d’erreur

Mode streaming avec client

Utilisation d’outils personnalisés

Voir aussi