Référence du SDK Agent - Python

Référence API complète du SDK Agent Python, incluant toutes les fonctions, types et classes.

Installation

Installez le package dans un environnement virtuel. Sur les installations récentes de Debian, Ubuntu et Homebrew Python, l'exécution de pip install contre le Python système échoue avec error: externally-managed-environment.

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

Pour uv, Windows PowerShell et la configuration de la clé API, consultez Démarrer dans la vue d'ensemble du Agent SDK.

Choisir entre `query()` et `ClaudeSDKClient`

Le SDK Python offre deux façons d'interagir avec Claude Code :

Utilisez ClaudeSDKClient pour les applications interactives telles que les interfaces de chat, ou quand l'action suivante dépend de la réponse de Claude.

Fonctions

`query()`

Crée une nouvelle session pour chaque interaction avec Claude Code par défaut. Retourne un itérateur asynchrone qui produit les messages au fur et à mesure qu'ils arrivent. Chaque appel à query() recommence à zéro sans mémoire des interactions précédentes, sauf si vous passez continue_conversation=True ou resume dans ClaudeAgentOptions. Voir Sessions.

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

Paramètres

Retours

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

Exemple - Avec options

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    options = ClaudeAgentOptions(
        system_prompt="You are an expert Python developer",
        permission_mode="acceptEdits",
    )

    async for message in query(prompt="Create a Python web server", options=options):
        print(message)


asyncio.run(main())

`tool()`

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

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

Paramètres

Options de schéma d'entrée

1. Mappage de type simple (recommandé) :

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

2. Format JSON Schema (pour la validation complexe) :

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

Retours

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

Exemple

from claude_agent_sdk import tool
from typing import Any


@tool("greet", "Greet a user", {"name": str})
async def greet(args: dict[str, Any]) -> dict[str, Any]:
    return {"content": [{"type": "text", "text": f"Hello, {args['name']}!"}]}

`ToolAnnotations`

Indices comportementaux pour un outil, passés comme argument annotations de tool(). ToolAnnotations étend mcp.types.ToolAnnotations du SDK MCP avec un champ maxResultSizeChars, et vous pouvez écrire chaque indice en camelCase ou snake_case : ToolAnnotations(readOnlyHint=True) et ToolAnnotations(read_only_hint=True) sont équivalents. Vous pouvez également passer un mcp.types.ToolAnnotations simple partout où le SDK accepte des annotations.

Les noms snake_case et le champ typé maxResultSizeChars nécessitent Python Agent SDK 0.2.140 ou ultérieur. Les versions 0.1.31 à 0.2.139 réexportent mcp.types.ToolAnnotations inchangé. Sur les versions 0.1.55 à 0.2.139, vous pouvez toujours passer maxResultSizeChars comme argument de mot-clé : la classe MCP accepte les champs supplémentaires, et le SDK transmet la valeur à Claude Code.

Tous les champs sont optionnels. Les clients ne doivent pas s'y fier pour les décisions de sécurité.

from claude_agent_sdk import tool, ToolAnnotations
from typing import Any


@tool(
    "search",
    "Search the web",
    {"query": str},
    annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
)
async def search(args: dict[str, Any]) -> dict[str, Any]:
    return {"content": [{"type": "text", "text": f"Results for: {args['query']}"}]}

`create_sdk_mcp_server()`

Crée 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

Retours

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

Exemple

from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions


@tool("add", "Add two numbers", {"a": float, "b": float})
async def add(args):
    return {"content": [{"type": "text", "text": f"Sum: {args['a'] + args['b']}"}]}


@tool("multiply", "Multiply two numbers", {"a": float, "b": float})
async def multiply(args):
    return {"content": [{"type": "text", "text": f"Product: {args['a'] * args['b']}"}]}


calculator = create_sdk_mcp_server(
    name="calculator",
    version="2.0.0",
    tools=[add, multiply],  # Pass decorated functions
)

# Use with Claude
options = ClaudeAgentOptions(
    mcp_servers={"calc": calculator},
    allowed_tools=["mcp__calc__add", "mcp__calc__multiply"],
)

`list_sessions()`

Liste les sessions passées avec métadonnées. Filtrez par répertoire de projet ou listez les sessions dans tous les projets. Synchrone ; retourne immédiatement.

def list_sessions(
    directory: str | None = None,
    limit: int | None = None,
    offset: int = 0,
    include_worktrees: bool = True
) -> list[SDKSessionInfo]

Paramètres

Type de retour : `SDKSessionInfo`

Exemple

Affiche les 10 sessions les plus récentes pour un projet. Les résultats sont triés par last_modified décroissant, donc le premier élément est le plus récent. Omettez directory pour rechercher dans tous les projets.

from claude_agent_sdk import list_sessions

for session in list_sessions(directory="/path/to/project", limit=10):
    print(f"{session.summary} ({session.session_id})")

`get_session_messages()`

Récupère les messages d'une session passée. Synchrone ; retourne immédiatement.

def get_session_messages(
    session_id: str,
    directory: str | None = None,
    limit: int | None = None,
    offset: int = 0
) -> list[SessionMessage]

Paramètres

Type de retour : `SessionMessage`

Exemple

from claude_agent_sdk import list_sessions, get_session_messages

sessions = list_sessions(limit=1)
if sessions:
    messages = get_session_messages(sessions[0].session_id)
    for msg in messages:
        print(f"[{msg.type}] {msg.uuid}")

`get_session_info()`

Lit les métadonnées d'une seule session par ID sans scanner le répertoire de projet complet. Synchrone ; retourne immédiatement.

def get_session_info(
    session_id: str,
    directory: str | None = None,
) -> SDKSessionInfo | None

Paramètres

Retourne SDKSessionInfo, ou None si la session n'est pas trouvée.

Exemple

Recherchez les métadonnées d'une seule session sans scanner le répertoire de projet. Utile quand vous avez déjà un ID de session d'une exécution précédente.

from claude_agent_sdk import get_session_info

info = get_session_info("550e8400-e29b-41d4-a716-446655440000")
if info:
    print(f"{info.summary} (branch: {info.git_branch}, tag: {info.tag})")

`rename_session()`

Renomme une session en ajoutant une entrée de titre personnalisé. Les appels répétés sont sûrs ; le titre le plus récent gagne. Synchrone.

def rename_session(
    session_id: str,
    title: str,
    directory: str | None = None,
) -> None

Paramètres

Lève ValueError si session_id n'est pas un UUID valide ou si title est vide ; FileNotFoundError si la session ne peut pas être trouvée.

Exemple

Renommez la session la plus récente pour qu'elle soit plus facile à trouver plus tard. Le nouveau titre apparaît dans SDKSessionInfo.custom_title lors des lectures ultérieures.

from claude_agent_sdk import list_sessions, rename_session

sessions = list_sessions(directory="/path/to/project", limit=1)
if sessions:
    rename_session(sessions[0].session_id, "Refactor auth module")

`tag_session()`

Étiquette une session. Passez None pour effacer l'étiquette. Les appels répétés sont sûrs ; l'étiquette la plus récente gagne. Synchrone.

def tag_session(
    session_id: str,
    tag: str | None,
    directory: str | None = None,
) -> None

Paramètres

Lève ValueError si session_id n'est pas un UUID valide ou si tag est vide après nettoyage ; FileNotFoundError si la session ne peut pas être trouvée.

Exemple

Étiquetez une session, puis filtrez par cette étiquette lors d'une lecture ultérieure. Passez None pour effacer une étiquette existante.

from claude_agent_sdk import list_sessions, tag_session

# Tag the most recent session
sessions = list_sessions(directory="/path/to/project", limit=1)
if sessions:
    tag_session(sessions[0].session_id, "needs-review")

# Later: find all sessions with that tag
for session in list_sessions(directory="/path/to/project"):
    if session.tag == "needs-review":
        print(session.summary)

Classes

`ClaudeSDKClient`

Maintient une session de conversation sur plusieurs échanges. C'est l'équivalent Python de la façon dont la fonction query() du SDK TypeScript fonctionne en interne - elle crée un objet client qui peut continuer les conversations. Voir la comparaison avec query().

class ClaudeSDKClient:
    def __init__(self, options: ClaudeAgentOptions | None = None, transport: Transport | 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 set_permission_mode(self, mode: PermissionMode) -> None
    async def set_model(self, model: str | None = None) -> None
    async def rewind_files(self, user_message_id: str) -> None
    async def get_mcp_status(self) -> McpStatusResponse
    async def reconnect_mcp_server(self, server_name: str) -> None
    async def toggle_mcp_server(self, server_name: str, enabled: bool) -> None
    async def stop_task(self, task_id: str) -> None
    async def get_server_info(self) -> dict[str, Any] | None
    async def disconnect(self) -> None

Méthodes

Support du gestionnaire de contexte

Le client peut être utilisé comme un gestionnaire de contexte asynchrone pour la gestion automatique de la connexion :

import asyncio
from claude_agent_sdk import ClaudeSDKClient


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


asyncio.run(main())

Important : Lors de l'itération sur les messages, évitez d'utiliser break pour quitter tôt car cela peut causer des problèmes de nettoyage asyncio. À la place, laissez l'itération se terminer naturellement ou utilisez des drapeaux pour suivre quand vous avez trouvé ce que vous cherchiez.

Exemple - Continuer une conversation

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


async def main():
    async with ClaudeSDKClient() as client:
        # First question
        await client.query("What's the capital of France?")

        # Process response
        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Claude: {block.text}")

        # Follow-up question - the session retains the previous context
        await client.query("What's the population of that city?")

        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Claude: {block.text}")

        # Another follow-up - still in the same conversation
        await client.query("What are some famous landmarks there?")

        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Claude: {block.text}")


asyncio.run(main())

Exemple - Entrée en streaming avec ClaudeSDKClient

import asyncio
from claude_agent_sdk import ClaudeSDKClient


async def message_stream():
    """Generate messages dynamically."""
    yield {
        "type": "user",
        "message": {"role": "user", "content": "Analyze the following data:"},
    }
    await asyncio.sleep(0.5)
    yield {
        "type": "user",
        "message": {"role": "user", "content": "Temperature: 25°C, Humidity: 60%"},
    }
    await asyncio.sleep(0.5)
    yield {
        "type": "user",
        "message": {"role": "user", "content": "What patterns do you see?"},
    }


async def main():
    async with ClaudeSDKClient() as client:
        # Stream input to Claude
        await client.query(message_stream())

        # Process response
        async for message in client.receive_response():
            print(message)

        # Follow-up in same session
        await client.query("Should we be concerned about these readings?")

        async for message in client.receive_response():
            print(message)


asyncio.run(main())

Exemple - Utiliser les interruptions

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, ResultMessage


async def interruptible_task():
    options = ClaudeAgentOptions(allowed_tools=["Bash"], permission_mode="acceptEdits")

    async with ClaudeSDKClient(options=options) as client:
        # Start a long-running task
        await client.query("Count from 1 to 100 slowly, using the bash sleep command")

        # Let it run for a bit
        await asyncio.sleep(2)

        # Interrupt the task
        await client.interrupt()
        print("Task interrupted!")

        # Drain the interrupted task's messages (including its ResultMessage)
        async for message in client.receive_response():
            if isinstance(message, ResultMessage):
                print(f"Interrupted task: terminal_reason={message.terminal_reason!r}")
                # terminal_reason is "aborted_streaming" or "aborted_tools"
                # for interrupted turns

        # Send a new command
        await client.query("Just say hello instead")

        # Now receive the new response
        async for message in client.receive_response():
            if isinstance(message, ResultMessage) and message.subtype == "success":
                print(f"New result: {message.result}")


asyncio.run(interruptible_task())

Exemple - Contrôle avancé des permissions

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
from claude_agent_sdk.types import (
    PermissionResultAllow,
    PermissionResultDeny,
    ToolPermissionContext,
)


async def custom_permission_handler(
    tool_name: str, input_data: dict, context: ToolPermissionContext
) -> PermissionResultAllow | PermissionResultDeny:
    """Custom logic for tool permissions."""

    # Block writes to system directories
    if tool_name == "Write" and input_data.get("file_path", "").startswith("/system/"):
        return PermissionResultDeny(
            message="System directory write not allowed", interrupt=True
        )

    # Redirect sensitive file operations
    if tool_name in ["Write", "Edit"] and "config" in input_data.get("file_path", ""):
        safe_path = f"./sandbox/{input_data['file_path']}"
        return PermissionResultAllow(
            updated_input={**input_data, "file_path": safe_path}
        )

    # Allow everything else
    return PermissionResultAllow(updated_input=input_data)


async def main():
    # Don't also list the gated tools in allowed_tools: allow rules approve calls before can_use_tool runs
    options = ClaudeAgentOptions(can_use_tool=custom_permission_handler)

    async with ClaudeSDKClient(options=options) as client:
        await client.query("Update the system config file")

        async for message in client.receive_response():
            # Will use sandbox path instead
            print(message)


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]]]
    annotations: ToolAnnotations | None = None

`Transport`

Classe de base abstraite pour les implémentations de transport personnalisées. Utilisez ceci pour communiquer avec le processus Claude sur un canal personnalisé (par exemple, une connexion distante au lieu d'un sous-processus local).

from abc import ABC, abstractmethod
from collections.abc import AsyncIterator
from typing import Any


class Transport(ABC):
    @abstractmethod
    async def connect(self) -> None: ...

    @abstractmethod
    async def write(self, data: str) -> None: ...

    @abstractmethod
    def read_messages(self) -> AsyncIterator[dict[str, Any]]: ...

    @abstractmethod
    async def close(self) -> None: ...

    @abstractmethod
    def is_ready(self) -> bool: ...

    @abstractmethod
    async def end_input(self) -> None: ...

Importation : from claude_agent_sdk import Transport

`ClaudeAgentOptions`

Dataclass de configuration pour les requêtes Claude Code.

@dataclass
class ClaudeAgentOptions:
    tools: list[str] | ToolsPreset | None = None
    allowed_tools: list[str] = field(default_factory=list)
    system_prompt: str | SystemPromptPreset | SystemPromptCustom | SystemPromptFile | None = None
    mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)
    strict_mcp_config: bool = False
    permission_mode: PermissionMode | None = None
    continue_conversation: bool = False
    resume: str | None = None
    session_id: str | None = None
    max_turns: int | None = None
    max_budget_usd: float | None = None
    disallowed_tools: list[str] = field(default_factory=list)
    model: str | None = None
    fallback_model: str | None = None
    betas: list[SdkBeta] = field(default_factory=list)
    output_format: dict[str, Any] | None = None
    permission_prompt_tool_name: str | None = None
    cwd: str | Path | None = None
    cli_path: 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)
    max_buffer_size: int | None = None
    debug_stderr: Any = sys.stderr  # Deprecated
    stderr: Callable[[str], None] | None = None
    can_use_tool: CanUseTool | None = None
    hooks: dict[HookEvent, list[HookMatcher]] | None = None
    user: str | None = None
    include_partial_messages: bool = False
    include_hook_events: bool = False
    forward_subagent_text: bool = False
    fork_session: bool = False
    resume_session_at: str | None = None
    resume_drops_turn: str | None = None
    agents: dict[str, AgentDefinition] | None = None
    setting_sources: list[SettingSource] | None = None
    skills: list[str] | Literal["all"] | None = None
    sandbox: SandboxSettings | None = None
    plugins: list[SdkPluginConfig] = field(default_factory=list)
    max_thinking_tokens: int | None = None  # Deprecated: use thinking instead
    thinking: ThinkingConfig | None = None
    effort: EffortLevel | None = None
    enable_file_checkpointing: bool = False
    session_store: SessionStore | None = None
    session_store_flush: SessionStoreFlushMode = "batched"
    load_timeout_ms: int = 60_000
    task_budget: TaskBudget | None = None

Gérer les réponses API lentes ou bloquées

Le sous-processus CLI lit plusieurs variables d'environnement qui contrôlent les délais d'expiration de l'API et la détection de blocage. Passez-les via ClaudeAgentOptions.env :

from claude_agent_sdk import ClaudeAgentOptions

options = ClaudeAgentOptions(
    env={
        "API_TIMEOUT_MS": "120000",
        "CLAUDE_CODE_MAX_RETRIES": "2",
        "CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS": "120000",
    },
)

• API_TIMEOUT_MS : délai d'expiration par requête sur le client Anthropic, en millisecondes. Par défaut 600000. S'applique à la boucle principale et à tous les sous-agents.

• CLAUDE_CODE_MAX_RETRIES : nombre maximum de tentatives API. Par défaut 10, limité à 15. Chaque tentative obtient sa propre fenêtre API_TIMEOUT_MS, donc le pire temps mural est approximativement API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1) plus le backoff. Pour les exécutions sans surveillance qui doivent attendre des pannes plus longues, définissez CLAUDE_CODE_RETRY_WATCHDOG=1 : il réessaye les erreurs de capacité transitoires indéfiniment et, à partir de Claude Code v2.1.199, augmente la valeur par défaut pour les autres erreurs transitoires à 300 et supprime le plafond sur cette variable.

• CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS : chien de garde de blocage pour les sous-agents. Pendant que le chien de garde de flux est activé, la valeur par défaut est CLAUDE_STREAM_IDLE_TIMEOUT_MS plus 5 minutes, ce qui donne 600000 sauf si vous augmentez cette variable. Avec le chien de garde de flux désactivé, la valeur par défaut est 600000. Avant v2.1.257, la valeur par défaut était toujours 600000.

  Le minuteur se réinitialise à chaque événement de flux. En cas de blocage, Claude Code abandonne le sous-agent et signale le blocage au parent. Pour un sous-agent en arrière-plan, il marque également la tâche comme échouée et attache tout résultat partiel.

• CLAUDE_ENABLE_STREAM_WATCHDOG avec CLAUDE_STREAM_IDLE_TIMEOUT_MS : chien de garde de flux qui abandonne la requête quand les en-têtes sont arrivés mais le corps de la réponse cesse de faire du streaming. Le chien de garde est activé par défaut pour tous les fournisseurs ; définissez CLAUDE_ENABLE_STREAM_WATCHDOG=0 pour le désactiver. CLAUDE_STREAM_IDLE_TIMEOUT_MS par défaut à 300000 et est limité à ce minimum. Après l'abandon, Les tentatives automatiques couvre ce que Claude Code fait, en fonction de la progression de la réponse.

  Pendant que le chien de garde attend une réponse qu'une passerelle derrière ANTHROPIC_BASE_URL maintient ouverte avec des pings de maintien de connexion, un hôte qui définit include_partial_messages continue de recevoir des messages StreamEvent de ping. Lisez ces frames comme une vivacité plutôt que de chronométrer la session sur le silence. Avant v2.1.257, les frames s'arrêtaient 5 minutes après le dernier événement de flux réel.

`OutputFormat`

Configuration pour la validation de sortie structurée. Passez ceci comme un dict au champ output_format sur ClaudeAgentOptions :

# Expected dict shape for output_format
{
    "type": "json_schema",
    "schema": {...},  # Your JSON Schema definition
}

`SystemPromptPreset`

Configuration pour utiliser le preset de prompt système de Claude Code avec des ajouts optionnels.

class SystemPromptPreset(TypedDict):
    type: Literal["preset"]
    preset: Literal["claude_code"]
    append: NotRequired[str]
    exclude_dynamic_sections: NotRequired[bool]
    snapshot: NotRequired[bool]

`SystemPromptCustom`

Un prompt système personnalisé sous forme d'objet, équivalent à passer une chaîne comme system_prompt, qui peut également définir snapshot. Nécessite claude-agent-sdk v0.2.153 ou ultérieur.

class SystemPromptCustom(TypedDict):
    type: Literal["custom"]
    prompt: str
    snapshot: NotRequired[bool]

`SystemPromptFile`

Configuration pour charger un prompt système personnalisé à partir d'un fichier au lieu de le passer en tant que chaîne. Le SDK mappe ceci à l'indicateur CLI --system-prompt-file. Utilisez la forme fichier quand le prompt est volumineux : le SDK passe un system_prompt chaîne sur l'argv du sous-processus CLI, qui est soumis aux limites de longueur de ligne de commande du système d'exploitation avant que le SDK n'envoie une requête API. Sur Linux, un seul argument plus long que environ 128 KB échoue au spawn du processus avec Argument list too long. Sur Windows, la ligne de commande entière est limitée à environ 32 KB, donc la forme chaîne échoue à un seuil inférieur.

class SystemPromptFile(TypedDict):
    type: Literal["file"]
    path: str

`SettingSource`

Contrôle quelles sources de configuration basées sur le système de fichiers le SDK charge les paramètres à partir de.

SettingSource = Literal["user", "project", "local"]

Comportement par défaut

Quand setting_sources est omis ou None et skills n'est pas défini, query() charge les mêmes paramètres du système de fichiers que le CLI Claude Code : utilisateur, projet et local. Avec skills défini, la ligne setting_sources décrit la valeur par défaut actuelle. Seules les sources utilisateur et projet se chargent. Définissez setting_sources explicitement pour conserver les paramètres locaux. La politique gérée par le point de terminaison se charge indépendamment ; les paramètres gérés par le serveur sont récupérés quand la session s'authentifie avec une credential d'organisation sur une configuration éligible. Pour plus d'informations, voir Ce que settingSources ne contrôle pas.

Pourquoi utiliser setting\_sources

Désactiver les paramètres du système de fichiers :

# Do not load user, project, or local settings from disk
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Analyze this code",
        options=ClaudeAgentOptions(
            setting_sources=[]
        ),
    ):
        print(message)


asyncio.run(main())

Charger uniquement des sources de paramètres spécifiques :

# Load only project settings, ignore user and local
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Run CI checks",
        options=ClaudeAgentOptions(
            setting_sources=["project"]  # Only .claude/settings.json
        ),
    ):
        print(message)


asyncio.run(main())

Applications SDK uniquement :

# Define everything programmatically.
# Pass [] to opt out of filesystem setting sources.
import asyncio
from claude_agent_sdk import AgentDefinition, ClaudeAgentOptions, query


async def main():
    async for message in query(
        prompt="Review this PR",
        options=ClaudeAgentOptions(
            setting_sources=[],
            agents={
                "code-reviewer": AgentDefinition(
                    description="Reviews code changes",
                    prompt="You are a code reviewer. Report issues in the diff.",
                ),
            },
            allowed_tools=["Read", "Grep", "Glob"],
        ),
    ):
        print(message)


asyncio.run(main())

Pour charger les instructions de projet CLAUDE.md, incluez "project" dans setting_sources. Voir Modifier les prompts système pour comment le chargement de CLAUDE.md interagit avec les options de prompt système.

Précédence des paramètres

Quand plusieurs sources sont chargées, les paramètres sont fusionnés avec cette précédence (la plus haute à la plus basse) :

1. Paramètres locaux (.claude/settings.local.json)
2. Paramètres de projet (.claude/settings.json)
3. Paramètres utilisateur (~/.claude/settings.json)

Les options programmatiques telles que agents, allowed_tools, et settings remplacent les paramètres du système de fichiers utilisateur, projet et local. Les paramètres de politique gérée prennent la priorité sur les options programmatiques.

`AgentDefinition`

Configuration pour un sous-agent défini programmatiquement.

@dataclass
class AgentDefinition:
    description: str
    prompt: str
    tools: list[str] | None = None
    disallowedTools: list[str] | None = None
    model: str | None = None
    skills: list[str] | None = None
    memory: Literal["user", "project", "local"] | None = None
    mcpServers: list[str | dict[str, Any]] | None = None
    initialPrompt: str | None = None
    maxTurns: int | None = None
    background: bool | None = None
    effort: EffortLevel | int | None = None
    permissionMode: PermissionMode | None = None

`PermissionMode`

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

PermissionMode = Literal[
    "default",  # Standard permission behavior
    "acceptEdits",  # Auto-accept file edits
    "plan",  # Planning mode - explore without editing
    "dontAsk",  # Deny anything not pre-approved instead of prompting
    "bypassPermissions",  # Bypass permission checks; explicit ask rules still prompt (use with caution)
    "auto",  # Model classifier approves or denies permission prompts
]

`EffortLevel`

Niveaux d'effort pour guider la profondeur de réflexion.

EffortLevel = Literal[
    "low",  # Minimal thinking, fastest responses
    "medium",  # Moderate thinking
    "high",  # Deep reasoning
    "xhigh",  # Extended reasoning; falls back to "high" on models that don't support it
    "max",  # Maximum effort
]

`CanUseTool`

Alias de type pour les fonctions de callback de permission d'outil.

CanUseTool = Callable[
    [str, dict[str, Any], ToolPermissionContext], Awaitable[PermissionResult]
]

Le callback reçoit :

• tool_name : Nom de l'outil en cours d'appel
• input_data : Les paramètres d'entrée de l'outil
• context : Un ToolPermissionContext avec des informations supplémentaires

Retourne un PermissionResult (soit PermissionResultAllow soit PermissionResultDeny).

Le callback est le remplacement SDK pour le prompt de permission interactif : il est invoqué uniquement quand le flux d'évaluation de permission aboutit à un prompt. Les appels d'outil déjà approuvés par une entrée allowed_tools, une règle d'autorisation des paramètres, ou le mode de permission, tel que acceptEdits ou bypassPermissions, ne l'invoquent jamais. Pour contrôler chaque appel d'outil, utilisez un hook PreToolUse à la place.

Une règle d'autorisation ne pré-approuve pas les actions qu'aucun mode n'approuve automatiquement ; voir Comment les permissions sont évaluées pour lesquelles les atteignent et ce qui se passe en mode dontAsk et auto.

`ToolPermissionContext`

Informations de contexte passées aux callbacks de permission d'outil.

@dataclass
class ToolPermissionContext:
    signal: Any | None = None  # Future: abort signal support
    suggestions: list[PermissionUpdate] = field(default_factory=list)
    tool_use_id: str | None = None
    agent_id: str | None = None
    blocked_path: str | None = None
    decision_reason: str | None = None
    title: str | None = None
    display_name: str | None = None
    description: str | None = None

`PermissionResult`

Type union pour les résultats de callback de permission.

PermissionResult = PermissionResultAllow | PermissionResultDeny

`PermissionResultAllow`

Résultat indiquant que l'appel d'outil doit être autorisé.

@dataclass
class PermissionResultAllow:
    behavior: Literal["allow"] = "allow"
    updated_input: dict[str, Any] | None = None
    updated_permissions: list[PermissionUpdate] | None = None

`PermissionResultDeny`

Résultat indiquant que l'appel d'outil doit être refusé.

@dataclass
class PermissionResultDeny:
    behavior: Literal["deny"] = "deny"
    message: str = ""
    interrupt: bool = False

`PermissionUpdate`

Configuration pour mettre à jour les permissions programmatiquement.

@dataclass
class PermissionUpdate:
    type: Literal[
        "addRules",
        "replaceRules",
        "removeRules",
        "setMode",
        "addDirectories",
        "removeDirectories",
    ]
    rules: list[PermissionRuleValue] | None = None
    behavior: Literal["allow", "deny", "ask"] | None = None
    mode: PermissionMode | None = None
    directories: list[str] | None = None
    destination: (
        Literal["userSettings", "projectSettings", "localSettings", "session"] | None
    ) = None

`PermissionRuleValue`

Une règle à ajouter, remplacer ou supprimer dans une mise à jour de permission.

@dataclass
class PermissionRuleValue:
    tool_name: str
    rule_content: str | None = None

`ToolsPreset`

Configuration des outils preset pour utiliser l'ensemble d'outils par défaut de Claude Code.

class ToolsPreset(TypedDict):
    type: Literal["preset"]
    preset: Literal["claude_code"]

`ThinkingConfig`

Contrôle le comportement de la réflexion étendue. Une union de trois configurations :

ThinkingDisplay = Literal["summarized", "omitted"]


class ThinkingConfigAdaptive(TypedDict):
    type: Literal["adaptive"]
    display: NotRequired[ThinkingDisplay]


class ThinkingConfigEnabled(TypedDict):
    type: Literal["enabled"]
    budget_tokens: int
    display: NotRequired[ThinkingDisplay]


class ThinkingConfigDisabled(TypedDict):
    type: Literal["disabled"]


ThinkingConfig = ThinkingConfigAdaptive | ThinkingConfigEnabled | ThinkingConfigDisabled

Le champ optionnel display contrôle si le texte de réflexion est retourné "summarized" ou "omitted". Sur Claude Opus 4.7 et ultérieur, la valeur par défaut de l'API est "omitted", donc définissez "summarized" pour recevoir le contenu de réflexion dans les sorties ThinkingBlock. Claude Code n'envoie pas display à Amazon Bedrock ou à la plateforme Agent de Google Cloud, donc sur ces fournisseurs Opus 4.7 et ultérieur retournent des sorties ThinkingBlock vides même quand vous définissez display à "summarized".

Parce que ce sont des classes TypedDict, ce sont des dicts simples à l'exécution. Construisez-les soit comme des littéraux dict soit appelez la classe comme un constructeur ; les deux produisent un dict. Accédez aux champs avec config["budget_tokens"], pas config.budget_tokens :

from claude_agent_sdk import ClaudeAgentOptions, ThinkingConfigEnabled

# Option 1: dict literal (recommended, no import needed)
options = ClaudeAgentOptions(thinking={"type": "enabled", "budget_tokens": 20000})

# Option 2: constructor-style (returns a plain dict)
config = ThinkingConfigEnabled(type="enabled", budget_tokens=20000)
print(config["budget_tokens"])  # 20000
# config.budget_tokens would raise AttributeError

`TaskBudget`

Budget de tâche côté API en tokens, utilisé avec le champ task_budget dans ClaudeAgentOptions.

class TaskBudget(TypedDict):
    total: int

Parce que c'est une TypedDict, passez-la comme un dict simple, tel que ClaudeAgentOptions(task_budget={"total": 50000}).

`SdkBeta`

Type littéral pour les fonctionnalités bêta du SDK.

SdkBeta = Literal["context-1m-2025-08-07"]

Utilisez avec le champ betas dans ClaudeAgentOptions pour activer les fonctionnalités bêta.

`McpSdkServerConfig`

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

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

`McpServerConfig`

Type union pour les configurations de serveur MCP.

McpServerConfig = (
    McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig
)

`McpStdioServerConfig`

class McpStdioServerConfig(TypedDict):
    type: NotRequired[Literal["stdio"]]  # Optional for backwards compatibility
    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]]

`McpServerStatusConfig`

La configuration d'un serveur MCP telle que rapportée par get_mcp_status(). C'est l'union de toutes les variantes de transport McpServerConfig plus une variante de sortie uniquement claudeai-proxy pour les serveurs proxifiés via claude.ai.

McpServerStatusConfig = (
    McpStdioServerConfig
    | McpSSEServerConfig
    | McpHttpServerConfig
    | McpSdkServerConfigStatus
    | McpClaudeAIProxyServerConfig
)

McpSdkServerConfigStatus est la forme sérialisable de McpSdkServerConfig avec seulement les champs type ("sdk") et name (str) ; l'instance en processus est omise. McpClaudeAIProxyServerConfig a les champs type ("claudeai-proxy"), url (str), et id (str).

`McpStatusResponse`

Réponse de ClaudeSDKClient.get_mcp_status(). Enveloppe la liste des statuts de serveur sous la clé mcpServers.

class McpStatusResponse(TypedDict):
    mcpServers: list[McpServerStatus]

`McpServerStatus`

Statut d'un serveur MCP connecté, contenu dans McpStatusResponse.

class McpServerStatus(TypedDict):
    name: str
    status: McpServerConnectionStatus  # "connected" | "failed" | "needs-auth" | "pending" | "disabled"
    serverInfo: NotRequired[McpServerInfo]
    error: NotRequired[str]
    config: NotRequired[McpServerStatusConfig]
    scope: NotRequired[str]
    tools: NotRequired[list[McpToolInfo]]

`SdkPluginConfig`

Configuration pour charger les plugins dans le SDK.

class SdkPluginConfig(TypedDict):
    type: Literal["local"]
    path: str

Exemple :

plugins = [
    {"type": "local", "path": "./my-plugin"},
    {"type": "local", "path": "/absolute/path/to/plugin"},
]

Pour des informations complètes sur la création et l'utilisation de plugins, voir Plugins.

Types de messages

`Message`

Type union de tous les messages possibles.

Message = (
    UserMessage
    | AssistantMessage
    | SystemMessage
    | ResultMessage
    | StreamEvent
    | RateLimitEvent
    | ConversationResetMessage
)

`UserMessage`

Message d'entrée utilisateur.

@dataclass
class UserMessage:
    content: str | list[ContentBlock]
    uuid: str | None = None
    parent_tool_use_id: str | None = None
    tool_use_result: dict[str, Any] | None = None
    origin: MessageOrigin | None = None

Le SDK transmet tool_use_result inchangé depuis le CLI. Pour un outil sur un serveur MCP externe dont le résultat contient des blocs resource_link, le dict a une clé resourceLinks contenant une liste de dicts avec les clés du type TypeScript SDKMcpResourceLink. Claude reçoit chaque lien sous forme de ligne de texte dans le résultat de l'outil. Pour afficher les fichiers que le serveur a retournés, lisez resourceLinks au lieu d'analyser ce texte. La clé resourceLinks nécessite Python Agent SDK 0.2.150 ou ultérieur et Claude Code v2.1.257 ou ultérieur ; le CLI fourni avec cette version du SDK satisfait l'exigence de Claude Code.

Le CLI omet la clé quand le résultat n'a pas de liens et sur les résultats des sous-agents. Le CLI conserve au maximum 50 liens par résultat et arrête d'ajouter des liens une fois que la liste atteint 64 KiB de JSON sérialisé. Un outil que vous définissez en processus avec tool() ne produit jamais la clé, car le SDK aplatit ses blocs resource_link en texte avant que le CLI ne voie le résultat.

`AssistantMessage`

Message de réponse d'assistant avec blocs de contenu.

@dataclass
class AssistantMessage:
    content: list[ContentBlock]
    model: str
    parent_tool_use_id: str | None = None
    error: AssistantMessageError | None = None
    usage: dict[str, Any] | None = None
    message_id: str | None = None
    stop_reason: str | None = None
    session_id: str | None = None
    uuid: str | None = None

`AssistantMessageError`

Types d'erreur possibles pour les messages d'assistant.

AssistantMessageError = Literal[
    "authentication_failed",
    "billing_error",
    "rate_limit",
    "invalid_request",
    "server_error",
    "unknown",
]

Le processus CLI sous-jacent peut émettre des types d'erreur que ce Literal ne liste pas, tels que max_output_tokens. Le SDK transmet la valeur inchangée, donc traitez les chaînes en dehors de cette liste de la même manière que vous traitez unknown. Le type TypeScript SDKAssistantMessageError liste l'ensemble complet des valeurs que le CLI peut émettre.

`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
    stop_reason: str | None = None
    total_cost_usd: float | None = None
    usage: dict[str, Any] | None = None
    result: str | None = None
    structured_output: Any = None
    model_usage: dict[str, ModelUsage] | None = None
    permission_denials: list[Any] | None = None
    deferred_tool_use: DeferredToolUse | None = None
    errors: list[str] | None = None
    api_error_status: int | None = None
    uuid: str | None = None
    terminal_reason: str | None = None
    origin: MessageOrigin | None = None

Le champ subtype détermine quels autres champs sont remplis. C'est l'un de "success", "error_during_execution", "error_max_turns", "error_max_budget_usd", ou "error_max_structured_output_retries". La dataclass Python aplatit toutes les variantes en une seule forme, donc les champs qui ne s'appliquent pas au sous-type retourné sont None.

Plusieurs champs portent des détails de diagnostic sur la façon dont la conversation s'est terminée :

• is_error : True quand la conversation s'est terminée dans un état d'erreur. Toujours True sur les sous-types error_*. Sur subtype="success" c'est True quand la dernière demande de modèle a échoué, ce qui signifie que la boucle d'agent s'est terminée mais le dernier appel API a retourné une erreur.
• api_error_status : le code de statut HTTP de l'erreur API terminale. None quand le tour s'est terminé sans une. Rempli uniquement sur subtype="success".
• result : texte du message d'assistant final sur subtype="success", ou None sur les sous-types error_*. Quand subtype="success" et is_error=True, ceci contient la chaîne d'erreur API si une est disponible mais peut être vide, donc vérifiez api_error_status et le contenu AssistantMessage précédent pour plus de détails.
• errors : chaînes d'erreur au niveau de la boucle telles que le message max-turns. Rempli uniquement sur les sous-types error_*.
• terminal_reason : pourquoi la boucle de requête s'est terminée, telle que "completed", "max_turns", "api_error", "aborted_streaming", ou "aborted_tools". Une valeur de "aborted_streaming" ou "aborted_tools" signifie que le tour a été interrompu avant de se terminer. Les causes courantes sont interrupt() et un rappel de permission retournant PermissionResultDeny avec interrupt=True. None sur les versions CLI qui précèdent le champ, sur les résultats des commandes locales telles que /voice ou /usage, qui contournent la boucle de requête, ou sur les résultats d'erreur synthétisés émis quand la session échoue fatalement. Reflète le SDKResultMessage.terminal_reason du SDK TypeScript, qui liste l'ensemble complet des valeurs.
• origin : origine du message utilisateur qui a déclenché ce tour. En mode d'entrée en streaming, vérifiez ceci pour distinguer le résultat de votre propre invite, où origin est None ou {"kind": "human"}, du résultat d'un tour injecté tel qu'une notification de tâche de fond. Nécessite Python Agent SDK 0.2.137 ou ultérieur.

Le dict usage couvre uniquement la boucle d'agent principal et exclut les sous-agents et autres appels de modèle imbriqués ou auxiliaires. En mode d'entrée en streaming, les valeurs sont par tour. Préférez model_usage pour la comptabilité des tokens et des coûts. Le dict usage contient les clés suivantes quand présentes :

Le dict model_usage mappe les noms de modèles à l'utilisation par modèle. Il couvre chaque appel de modèle effectué via le pipeline de requête : la boucle principale, les sous-agents, et les appels internes tels que la compaction et les agents Workflow. Les appels d'assistance en dehors de ce pipeline, tels que le classificateur de permission et les demandes de comptage de tokens, sont exclus de model_usage. Traitez model_usage comme une estimation, pas une déclaration de facturation.

En mode d'entrée en streaming, model_usage et total_cost_usd sont cumulatifs entre les tours, donc lisez le dernier résultat plutôt que de faire la somme entre les résultats. Voir Suivre les coûts en mode d'entrée en streaming pour les réinitialisations et Récupérer les totaux après un crash de session pour les résultats remis à zéro.

Chaque valeur dans model_usage est un TypedDict ModelUsage, importé via from claude_agent_sdk.types import ModelUsage. Ses clés utilisent camelCase car le SDK transmet la valeur inchangée du processus CLI sous-jacent, correspondant au type TypeScript ModelUsage :

`StreamEvent`

Événement de flux pour les mises à jour de messages partiels pendant le streaming. Reçu uniquement quand include_partial_messages=True dans ClaudeAgentOptions. Importez via from claude_agent_sdk.types import StreamEvent.

@dataclass
class StreamEvent:
    uuid: str
    session_id: str
    event: dict[str, Any]  # The raw Claude API stream event
    parent_tool_use_id: str | None = None

`RateLimitEvent`

Émis quand le statut de limite de débit change (par exemple, de "allowed" à "allowed_warning"). Utilisez ceci pour avertir les utilisateurs avant qu'ils ne frappent une limite dure, ou pour reculer quand le statut est "rejected".

@dataclass
class RateLimitEvent:
    rate_limit_info: RateLimitInfo
    uuid: str
    session_id: str

`RateLimitInfo`

État de limite de débit porté par RateLimitEvent.

RateLimitStatus = Literal["allowed", "allowed_warning", "rejected"]
RateLimitType = Literal[
    "five_hour", "seven_day", "seven_day_opus", "seven_day_sonnet", "overage"
]


@dataclass
class RateLimitInfo:
    status: RateLimitStatus
    resets_at: int | None = None
    rate_limit_type: RateLimitType | None = None
    utilization: float | None = None
    overage_status: RateLimitStatus | None = None
    overage_resets_at: int | None = None
    overage_disabled_reason: str | None = None
    raw: dict[str, Any] = field(default_factory=dict)

`ConversationResetMessage`

Émis quand la conversation est remplacée sans terminer la connexion, par exemple après /clear. Voir Suivre les coûts en mode d'entrée en streaming pour la façon dont une réinitialisation affecte les totaux en cours d'exécution sur les objets ResultMessage ultérieurs. Nécessite Python Agent SDK 0.2.137 ou ultérieur.

@dataclass
class ConversationResetMessage:
    new_conversation_id: str
    uuid: str
    session_id: str

`TaskStartedMessage`

Émis quand une tâche de fond démarre. Une tâche de fond est tout ce qui est suivi en dehors du tour principal : une commande Bash en arrière-plan, une montre Monitor, un sous-agent généré via l'outil Agent, ou un agent distant. Le champ task_type vous dit lequel. Ce nommage n'est pas lié au renommage de l'outil Task-à-Agent.

@dataclass
class TaskStartedMessage(SystemMessage):
    task_id: str
    description: str
    uuid: str
    session_id: str
    tool_use_id: str | None = None
    task_type: str | None = None

`TaskUsage`

Données de tokens et de timing pour une tâche de fond.

class TaskUsage(TypedDict):
    total_tokens: int
    tool_uses: int
    duration_ms: int

`TaskProgressMessage`

Émis périodiquement avec les mises à jour de progression pour une tâche de fond en cours d'exécution.

@dataclass
class TaskProgressMessage(SystemMessage):
    task_id: str
    description: str
    usage: TaskUsage
    uuid: str
    session_id: str
    tool_use_id: str | None = None
    last_tool_name: str | None = None

`TaskNotificationMessage`

Émis quand une tâche de fond se termine, échoue, ou est arrêtée. Les tâches de fond incluent les commandes Bash run_in_background, les montres Monitor, et les sous-agents en arrière-plan.

@dataclass
class TaskNotificationMessage(SystemMessage):
    task_id: str
    status: TaskNotificationStatus  # "completed" | "failed" | "stopped"
    output_file: str
    summary: str
    uuid: str
    session_id: str
    tool_use_id: str | None = None
    usage: TaskUsage | None = None

Quand le CLI déplace un long appel d'outil MCP en arrière-plan, le résultat de l'outil pour cet appel ne contient qu'un espace réservé et le résultat réel de l'appel arrive dans ce message. Sur une notification "completed" pour un tel appel, le CLI ajoute une clé resource_links listant les fichiers que l'outil a retournés par référence, avec les mêmes entrées et limites que la clé resourceLinks sur UserMessage.tool_use_result. La clé resource_links nécessite Python Agent SDK 0.2.150 ou ultérieur et Claude Code v2.1.257 ou ultérieur ; le CLI fourni avec cette version du SDK satisfait l'exigence de Claude Code.

La dataclass n'a pas de champ pour resource_links. Lisez-le à partir du dict data que le message hérite de SystemMessage : message.data.get("resource_links"). Faites correspondre la notification à l'appel avec tool_use_id. Le CLI omet la clé quand le résultat n'avait pas de liens et sur les notifications pour les tâches qui ne sont pas des appels d'outil MCP.

Types de blocs de contenu

`ContentBlock`

Type union de tous les blocs de contenu.

ContentBlock = (
    TextBlock
    | ThinkingBlock
    | ToolUseBlock
    | ToolResultBlock
    | ServerToolUseBlock
    | ServerToolResultBlock
)

`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 requête 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

Les types ci-dessous définissent ce que votre code capture. Pour les entrées associées aux messages d'erreur que ces types lèvent, avec la cause et la correction pour chacun, consultez Dépannage.

`ClaudeSDKError`

Classe d'exception de base pour toutes les erreurs du SDK.

class ClaudeSDKError(Exception):
    """Base error for Claude SDK."""

Quand une requête query() unique se termine par un résultat d'erreur, par exemple une erreur de limite de tours, le SDK lève une ResultError après avoir cédé le message de résultat final. Les versions du Python Agent SDK antérieures à 0.2.140 levaient une Exception simple qui n'était pas une sous-classe de ClaudeSDKError.

`CLINotFoundError`

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

class CLINotFoundError(CLIConnectionError):
    def __init__(
        self, message: str = "Claude Code not found", cli_path: str | None = None
    ):
        """
        Args:
            message: Error message (default: "Claude Code not found")
            cli_path: Optional path to the CLI that was not found
        """

`CLIConnectionError`

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

class CLIConnectionError(ClaudeSDKError):
    """Failed to connect to 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

`ResultError`

Levée après le ResultMessage final quand le processus Claude Code se termine parce que l'exécution s'est terminée par un résultat d'erreur, comme une erreur de limite de tours ou une erreur API. ResultError est une sous-classe de ProcessError, donc un gestionnaire except ProcessError existant la capture également. Ses attributs portent les champs de ce message de résultat, vous pouvez donc vous brancher sur la raison de l'échec de l'exécution sans analyser le texte du message. Nécessite Python Agent SDK 0.2.140 ou version ultérieure.

class ResultError(ProcessError):
    subtype: str | None  # "error_max_turns", "error_during_execution", ...; "success" when the run ended on a failed request
    errors: list[str]  # an empty list when the result message reported none
    result: str | None
    api_error_status: int | None
    terminal_reason: str | None  # "max_turns", "api_error", ...; check this before subtype
    session_id: str | None
    data: dict[str, Any]  # the raw result message payload

Pour distinguer les échecs, vérifiez terminal_reason avant subtype. Quand la requête finale échoue, par exemple sur une erreur API, Claude Code rapporte subtype "success" avec la cause dans terminal_reason, par exemple "api_error" ; quand une limite que vous avez définie termine l'exécution, comme max_turns ou max_budget_usd, il rapporte un sous-type error_*.

`CLIJSONDecodeError`

Levée quand l'analyse JSON échoue.

class CLIJSONDecodeError(ClaudeSDKError):
    def __init__(self, line: str, original_error: Exception):
        """
        Args:
            line: The line that failed to parse
            original_error: The original JSON decode exception
        """
        self.line = line
        self.original_error = original_error

Types de hooks

Pour un guide complet sur l'utilisation des hooks avec des exemples et des modèles courants, voir le guide Hooks.

`HookEvent`

Types d'événements de hook supportés.

HookEvent = Literal[
    "PreToolUse",  # Called before tool execution
    "PostToolUse",  # Called after tool execution
    "PostToolUseFailure",  # Called when a tool execution fails
    "UserPromptSubmit",  # Called when user submits a prompt
    "Stop",  # Called when stopping execution
    "SubagentStop",  # Called when a subagent stops
    "PreCompact",  # Called before message compaction
    "Notification",  # Called for notification events
    "SubagentStart",  # Called when a subagent starts
    "PermissionRequest",  # Called when a permission decision is needed
]

`HookCallback`

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

HookCallback = Callable[[HookInput, str | None, HookContext], Awaitable[HookJSONOutput]]

Paramètres :

• input : Entrée de hook fortement typée avec unions discriminées basées sur hook_event_name (voir HookInput)
• tool_use_id : Identifiant d'utilisation d'outil optionnel (pour les hooks liés aux outils)
• context : Contexte de hook avec des informations supplémentaires

Retourne un HookJSONOutput.

`HookContext`

Informations de contexte passées aux callbacks de hook.

class HookContext(TypedDict):
    signal: Any | None  # Future: abort signal support

`HookMatcher`

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

@dataclass
class HookMatcher:
    matcher: str | None = (
        None  # Tool name or pattern to match (e.g., "Bash", "Write|Edit")
    )
    hooks: list[HookCallback] = field(
        default_factory=list
    )  # List of callbacks to execute
    timeout: float | None = (
        None  # Timeout in seconds. When omitted, the per-event default applies:
        # 600 for most events, 30 for UserPromptSubmit
    )

`HookInput`

Type union de tous les types d'entrée de hook. Le type réel dépend du champ hook_event_name.

HookInput = (
    PreToolUseHookInput
    | PostToolUseHookInput
    | PostToolUseFailureHookInput
    | UserPromptSubmitHookInput
    | StopHookInput
    | SubagentStopHookInput
    | PreCompactHookInput
    | NotificationHookInput
    | SubagentStartHookInput
    | PermissionRequestHookInput
)

`BaseHookInput`

Champs de base présents dans tous les types d'entrée de hook.

class BaseHookInput(TypedDict):
    session_id: str
    transcript_path: str
    cwd: str
    permission_mode: NotRequired[str]

`PreToolUseHookInput`

Données d'entrée pour les événements de hook PreToolUse.

class PreToolUseHookInput(BaseHookInput):
    hook_event_name: Literal["PreToolUse"]
    tool_name: str
    tool_input: dict[str, Any]
    tool_use_id: str
    agent_id: NotRequired[str]
    agent_type: NotRequired[str]

`PostToolUseHookInput`

Données d'entrée pour les événements de hook PostToolUse.

class PostToolUseHookInput(BaseHookInput):
    hook_event_name: Literal["PostToolUse"]
    tool_name: str
    tool_input: dict[str, Any]
    tool_response: Any
    tool_use_id: str
    agent_id: NotRequired[str]
    agent_type: NotRequired[str]

`PostToolUseFailureHookInput`

Données d'entrée pour les événements de hook PostToolUseFailure. Appelé quand l'exécution d'un outil échoue.

class PostToolUseFailureHookInput(BaseHookInput):
    hook_event_name: Literal["PostToolUseFailure"]
    tool_name: str
    tool_input: dict[str, Any]
    tool_use_id: str
    error: str
    is_interrupt: NotRequired[bool]
    agent_id: NotRequired[str]
    agent_type: NotRequired[str]

`UserPromptSubmitHookInput`

Données d'entrée pour les événements de hook UserPromptSubmit.

class UserPromptSubmitHookInput(BaseHookInput):
    hook_event_name: Literal["UserPromptSubmit"]
    prompt: str

`StopHookInput`

Données d'entrée pour les événements de hook Stop.

class StopHookInput(BaseHookInput):
    hook_event_name: Literal["Stop"]
    stop_hook_active: bool

`SubagentStopHookInput`

Données d'entrée pour les événements de hook SubagentStop.

class SubagentStopHookInput(BaseHookInput):
    hook_event_name: Literal["SubagentStop"]
    stop_hook_active: bool
    agent_id: str
    agent_transcript_path: str
    agent_type: str

`PreCompactHookInput`

Données d'entrée pour les événements de hook PreCompact.

class PreCompactHookInput(BaseHookInput):
    hook_event_name: Literal["PreCompact"]
    trigger: Literal["manual", "auto"]
    custom_instructions: str | None

`NotificationHookInput`

Données d'entrée pour les événements de hook Notification.

class NotificationHookInput(BaseHookInput):
    hook_event_name: Literal["Notification"]
    message: str
    title: NotRequired[str]
    notification_type: str

`SubagentStartHookInput`

Données d'entrée pour les événements de hook SubagentStart.

class SubagentStartHookInput(BaseHookInput):
    hook_event_name: Literal["SubagentStart"]
    agent_id: str
    agent_type: str

`PermissionRequestHookInput`

Données d'entrée pour les événements de hook PermissionRequest. Permet aux hooks de gérer les décisions de permission programmatiquement.

class PermissionRequestHookInput(BaseHookInput):
    hook_event_name: Literal["PermissionRequest"]
    tool_name: str
    tool_input: dict[str, Any]
    permission_suggestions: NotRequired[list[Any]]
    agent_id: NotRequired[str]
    agent_type: NotRequired[str]

`HookJSONOutput`

Type union pour les valeurs de retour de callback de hook.

HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput

`SyncHookJSONOutput`

Sortie de hook synchrone avec champs de contrôle et de décision.

class SyncHookJSONOutput(TypedDict):
    # Control fields
    continue_: NotRequired[bool]  # Whether to proceed (default: True)
    suppressOutput: NotRequired[bool]  # Hide stdout from transcript
    stopReason: NotRequired[str]  # Message when continue is False

    # Decision fields
    decision: NotRequired[Literal["block"]]
    systemMessage: NotRequired[str]  # Warning message for user
    reason: NotRequired[str]  # Feedback for Claude

    # Hook-specific output
    hookSpecificOutput: NotRequired[HookSpecificOutput]

`HookSpecificOutput`

Une union discriminée de types de sortie spécifiques à l'événement TypedDict. Le champ hookEventName détermine quels champs sont valides. Pour les détails complets sur les champs disponibles par événement de hook, voir Contrôler l'exécution avec les hooks.

class PreToolUseHookSpecificOutput(TypedDict):
    hookEventName: Literal["PreToolUse"]
    permissionDecision: NotRequired[Literal["allow", "deny", "ask", "defer"]]
    permissionDecisionReason: NotRequired[str]
    updatedInput: NotRequired[dict[str, Any]]
    additionalContext: NotRequired[str]


class PostToolUseHookSpecificOutput(TypedDict):
    hookEventName: Literal["PostToolUse"]
    additionalContext: NotRequired[str]
    updatedToolOutput: NotRequired[Any]
    updatedMCPToolOutput: NotRequired[Any]  # Deprecated: use updatedToolOutput, which works for all tools


class PostToolUseFailureHookSpecificOutput(TypedDict):
    hookEventName: Literal["PostToolUseFailure"]
    additionalContext: NotRequired[str]


class UserPromptSubmitHookSpecificOutput(TypedDict):
    hookEventName: Literal["UserPromptSubmit"]
    additionalContext: NotRequired[str]


class NotificationHookSpecificOutput(TypedDict):
    hookEventName: Literal["Notification"]
    additionalContext: NotRequired[str]


class SubagentStartHookSpecificOutput(TypedDict):
    hookEventName: Literal["SubagentStart"]
    additionalContext: NotRequired[str]


class PermissionRequestHookSpecificOutput(TypedDict):
    hookEventName: Literal["PermissionRequest"]
    decision: dict[str, Any]


HookSpecificOutput = (
    PreToolUseHookSpecificOutput
    | PostToolUseHookSpecificOutput
    | PostToolUseFailureHookSpecificOutput
    | UserPromptSubmitHookSpecificOutput
    | NotificationHookSpecificOutput
    | SubagentStartHookSpecificOutput
    | PermissionRequestHookSpecificOutput
)

`AsyncHookJSONOutput`

Sortie de hook asynchrone qui diffère l'exécution du hook.

class AsyncHookJSONOutput(TypedDict):
    async_: Literal[True]  # Set to True to defer execution
    asyncTimeout: NotRequired[int]  # Timeout in milliseconds

Exemple d'utilisation de hook

Cet exemple enregistre deux hooks : l'un qui bloque les commandes bash dangereuses comme rm -rf /, et un autre qui enregistre toute l'utilisation d'outils pour l'audit. Le hook de sécurité s'exécute uniquement sur les commandes Bash (via le matcher), tandis que le hook de journalisation s'exécute sur tous les outils.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, 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]:
    """Validate and potentially block dangerous bash commands."""
    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": "Dangerous command blocked",
                }
            }
    return {}


async def log_tool_use(
    input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
) -> dict[str, Any]:
    """Log all tool usage for auditing."""
    print(f"Tool used: {input_data.get('tool_name')}")
    return {}


options = ClaudeAgentOptions(
    hooks={
        "PreToolUse": [
            HookMatcher(
                matcher="Bash", hooks=[validate_bash_command], timeout=120
            ),  # 2 min for validation
            HookMatcher(
                hooks=[log_tool_use]
            ),  # Applies to all tools (per-event default timeout)
        ],
        "PostToolUse": [HookMatcher(hooks=[log_tool_use])],
    }
)

async def main():
    async for message in query(prompt="Analyze this codebase", options=options):
        print(message)


asyncio.run(main())

Types d'entrée/sortie d'outil

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

Agent

Nom de l'outil : Agent. Le nom précédent Task est toujours accepté comme alias, et la liste tools dans le SystemMessage d'initialisation rapporte cet outil comme Task pour la compatibilité rétroactive.

Entrée :

{
    "description": str,  # A short (3-5 word) description of the task
    "prompt": str,  # The task for the agent to perform
    "subagent_type": str | None,  # The type of specialized agent to use
    "model": "sonnet" | "opus" | "haiku" | "fable" | None,  # Model override for this agent
    "run_in_background": bool | None,  # Agents run in the background by default; set to False to run synchronously
    "name": str | None,  # Name for the spawned agent
    "team_name": str | None,  # Deprecated; ignored
    "mode": "acceptEdits" | "auto" | "bypassPermissions" | "default" | "dontAsk" | "plan" | None,  # Deprecated; ignored. The subagent inheritance rules decide a subagent's permission mode
    "isolation": "worktree" | "remote" | None,  # Isolation mode for the agent's changes
}

Lance un nouvel agent pour gérer des tâches complexes et multi-étapes de manière autonome.

Sortie (statut : "completed") :

{
    "status": "completed",
    "agentId": str,  # ID of the agent that ran
    "agentType": str | None,  # The subagent type that handled the task
    "content": [  # Result content blocks
        {
            "type": "text",
            "text": str,
            "citations": list | None,
        }
    ],
    "resolvedModel": str | None,  # Model the subagent started on
    "modelsUsed": list[str] | None,  # Models used in order, with consecutive repeats collapsed
    "totalToolUseCount": int,  # Number of tool calls the agent made
    "totalDurationMs": int,  # Execution duration in milliseconds
    "totalTokens": int,  # Token count from the final API request, not the whole run
    "usage": {  # Token usage statistics
        "input_tokens": int,
        "output_tokens": int,
        "cache_creation_input_tokens": int | None,
        "cache_read_input_tokens": int | None,
        "server_tool_use": {"web_search_requests": int, "web_fetch_requests": int} | None,
        "service_tier": str | None,
        "cache_creation": {"ephemeral_1h_input_tokens": int, "ephemeral_5m_input_tokens": int} | None,
        "inference_geo": str | None,
        "speed": str | None,
        "iterations": Any | None,
        "output_tokens_details": {"thinking_tokens": int | None} | None,
    },
    "toolStats": {  # Aggregate tool activity for the run
        "readCount": int,
        "searchCount": int,
        "bashCount": int,
        "editFileCount": int,
        "linesAdded": int,
        "linesRemoved": int,
        "otherToolCount": int,
        "frameCount": int | None,
    } | None,
    "prompt": str,  # The prompt the agent ran
    "worktreePath": str | None,  # Present when Claude Code kept the subagent's worktree
    "worktreeBranch": str | None,  # Present when Claude Code created that worktree with git
}

Sortie (statut : "async_launched") :

{
    "status": "async_launched",
    "isAsync": bool | None,  # True on background launches
    "agentId": str,  # ID of the launched agent
    "description": str,  # The task description
    "resolvedModel": str | None,  # Model in use at the backgrounding transition
    "modelsUsed": list[str] | None,  # Models used before backgrounding, in order, with consecutive repeats collapsed
    "prompt": str,  # The prompt the agent runs
    "outputFile": str,  # File path where the agent's output is written
    "canReadOutputFile": bool | None,  # Whether the output file can be read directly
}

Sortie (statut : "remote_launched") :

{
    "status": "remote_launched",
    "taskId": str,  # ID of the dispatched task
    "sessionUrl": str,  # Link to the cloud session
    "description": str,  # The task description
    "prompt": str,  # The prompt the agent runs
    "outputFile": str,  # File path where the agent's output is written
}

Retourne le résultat du sous-agent. La sortie est discriminée sur le champ status : "completed" pour les tâches terminées, "async_launched" pour les tâches en arrière-plan, et "remote_launched" pour les tâches que Claude Code a envoyées à une session cloud, où sessionUrl renvoie à cette session et taskId l'identifie. Si Claude Code a conservé la worktree isolée du sous-agent, worktreePath sur la variante completed est l'endroit où la trouver, et worktreeBranch est sa branche lorsque Claude Code a créé la worktree avec git.

Sur la variante completed, resolvedModel nomme le modèle sur lequel le sous-agent a démarré, qui peut différer du model d'entrée demandé lorsque availableModels ou une autre substitution s'applique. Ce champ nécessite Claude Code v2.1.174 ou ultérieur. Sur la variante async_launched, resolvedModel nomme le modèle en cours d'utilisation lorsque l'agent s'est déplacé en arrière-plan, donc un échange qui s'est produit avant la mise en arrière-plan est reflété là. Le champ modelsUsed sur les deux variantes répertorie les modèles utilisés dans l'ordre, avec les répétitions consécutives réduites ; il est défini uniquement lorsque le modèle a été échangé en cours d'exécution. modelsUsed et le comportement resolvedModel au moment de la mise en arrière-plan nécessitent Claude Code v2.1.212 ou ultérieur.

Claude Code remplit usage et totalTokens à partir de la dernière demande API du sous-agent, pas de l'ensemble de l'exécution. Lorsqu'il est présent, thinking_tokens sous output_tokens_details dans usage est le nombre de jetons de sortie de cette demande qui étaient des jetons de réflexion. La clé output_tokens_details nécessite le SDK Python v0.2.136 ou ultérieur, qui regroupe Claude Code v2.1.228.

AskUserQuestion

Nom de l'outil : AskUserQuestion

Pose des questions de clarification à l'utilisateur pendant l'exécution. Voir Gérer les approbations et les entrées utilisateur pour les détails d'utilisation.

Entrée :

{
    "questions": [  # Questions to ask the user (1-4 questions)
        {
            "question": str,  # The complete question to ask the user
            "header": str,  # Very short label displayed as a chip/tag (max 12 chars)
            "options": [  # The available choices (2-4 options)
                {
                    "label": str,  # Display text for this option (1-5 words)
                    "description": str,  # Explanation of what this option means
                    "preview": str | None,  # Preview content rendered when the option is focused
                }
            ],
            "multiSelect": bool,  # Set to true to allow multiple selections
        }
    ],
    "answers": dict[str, str] | None,
    # User answers populated by the permission system. Multi-select
    # answers are a comma-joined string of the selected labels; a
    # list of labels is accepted on input and coerced to that form
    "annotations": dict[str, dict] | None,
    # Per-question annotations from the user, keyed by question text.
    # Each value can carry "preview" (the selected option's preview
    # content) and "notes" (free-text notes on the selection)
    "metadata": dict | None,  # Analytics metadata, such as {"source": "remember"}; not displayed to the user
}

Sortie :

{
    "questions": [  # The questions that were asked
        {
            "question": str,
            "header": str,
            "options": [{"label": str, "description": str, "preview": str | None}],
            "multiSelect": bool,
        }
    ],
    "answers": dict[str, str],  # Maps question text to answer string
    # Multi-select answers are comma-separated
    "response": str | None,
    # Freeform reply typed instead of answering the questions; when set,
    # Claude receives "The user responded: ..." in place of the answer list
    "annotations": dict[str, dict] | None,  # Per-question "preview" and "notes" from the user's selections
    "afkTimeoutMs": int | None,  # Set when the dialog auto-resolved after this many milliseconds of user inactivity; absent when the user answered
}

Bash

Nom de l'outil : Bash

Entrée :

{
    "command": str,  # The command to execute
    "timeout": int | None,  # Optional timeout in milliseconds (max 600000; higher values are clamped to the max)
    "description": str | None,  # Clear, concise description (5-10 words)
    "run_in_background": bool | None,  # Set to true to run in background
}

Sortie :

{
    "stdout": str,  # The command's output; stdout and stderr arrive merged into this one interleaved stream
    "stderr": str,  # Notices the tool itself adds, not the command's stderr
    "interrupted": bool,  # Whether the command was interrupted
    "isImage": bool | None,  # Whether stdout contains image data
    "backgroundTaskId": str | None,  # ID of the background task if command is running in background
}

Monitor

Nom de l'outil : Monitor

Exécute une source de fond et livre chaque événement à Claude pour qu'il puisse réagir sans interrogation : command exécute un script et émet un événement par ligne stdout, et ws ouvre une WebSocket et émet un événement par trame texte. Fournissez exactement l'un de command ou ws.

Lorsque Monitor exécute une commande, il suit les mêmes règles de permission que Bash ; une surveillance WebSocket demande une approbation séparément. La source ws nécessite Claude Code v2.1.195 ou ultérieur. Voir la référence de l'outil Monitor pour le comportement et la disponibilité du fournisseur.

Entrée :

{
    "command": str | None,  # Shell script; each stdout line is an event, exit ends the watch
    "ws": dict | None,  # WebSocket source: {"url": str, "protocols": list[str] | None}; each text frame is an event
    "description": str,  # Short description shown in notifications
    "timeout_ms": int | None,  # Kill after this deadline (default 300000, max 3600000)
    "persistent": bool | None,  # Run for the lifetime of the session; stop with TaskStop
}

Sortie :

{
    "taskId": str,  # ID of the background monitor task
    "timeoutMs": int,  # Timeout deadline in milliseconds (0 when persistent)
    "persistent": bool | None,  # True when running until TaskStop or session end
}

Edit

Nom de l'outil : Edit

Entrée :

{
    "file_path": str,  # The absolute path to the file to modify
    "old_string": str,  # The text to replace
    "new_string": str,  # The text to replace it with
    "replace_all": bool | None,  # Replace all occurrences (default False)
}

Sortie :

{
    "message": str,  # Confirmation message
    "replacements": int,  # Number of replacements made
    "file_path": str,  # File path that was edited
}

Read

Nom de l'outil : Read

Entrée :

{
    "file_path": str,  # The absolute path to the file to read
    "offset": int | None,  # The line number to start reading from
    "limit": int | None,  # The number of lines to read
}

Sortie (fichiers texte) :

{
    "content": str,  # File contents with line numbers
    "total_lines": int,  # Total number of lines in file
    "lines_returned": int,  # Lines actually returned
}

Sortie (images) :

{
    "image": str,  # Base64 encoded image data
    "mime_type": str,  # Image MIME type
    "file_size": int,  # File size in bytes
}

Write

Nom de l'outil : Write

Entrée :

{
    "file_path": str,  # The absolute path to the file to write
    "content": str,  # The content to write to the file
}

Sortie :

{
    "message": str,  # Success message
    "bytes_written": int,  # Number of bytes written
    "file_path": str,  # File path that was written
}

Glob

Nom de l'outil : Glob

Entrée :

{
    "pattern": str,  # The glob pattern to match files against
    "path": str | None,  # The directory to search in (defaults to cwd)
}

Sortie :

{
    "matches": list[str],  # Array of matching file paths
    "count": int,  # Number of matches found
    "search_path": str,  # Search directory used
}

Grep

Nom de l'outil : Grep

Entrée :

{
    "pattern": str,  # The regular expression pattern
    "path": str | None,  # File or directory to search in
    "glob": str | None,  # Glob pattern to filter files
    "type": str | None,  # File type to search
    "output_mode": str | None,  # "content", "files_with_matches", or "count"
    "-i": bool | None,  # Case insensitive search
    "-n": bool | None,  # Show line numbers
    "-B": int | None,  # Lines to show before each match
    "-A": int | None,  # Lines to show after each match
    "-C": int | None,  # Lines to show before and after
    "head_limit": int | None,  # Limit output to first N lines/entries
    "multiline": bool | None,  # Enable multiline mode
}

Sortie (mode contenu) :

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

Sortie (mode fichiers_avec_correspondances) :

{
    "files": list[str],  # Files containing matches
    "count": int,  # Number of files with matches
}

NotebookEdit

Nom de l'outil : NotebookEdit

Entrée :

{
    "notebook_path": str,  # Absolute path to the Jupyter notebook
    "cell_id": str | None,  # The ID of the cell to edit
    "new_source": str,  # The new source for the cell
    "cell_type": "code" | "markdown" | None,  # The type of the cell
    "edit_mode": "replace" | "insert" | "delete" | None,  # Edit operation type
}

Sortie :

{
    "message": str,  # Success message
    "edit_type": "replaced" | "inserted" | "deleted",  # Type of edit performed
    "cell_id": str | None,  # Cell ID that was affected
    "total_cells": int,  # Total cells in notebook after edit
}

WebFetch

Nom de l'outil : WebFetch

Entrée :

{
    "url": str,  # The URL to fetch content from
    "prompt": str,  # The prompt to run on the fetched content
}

Sortie :

{
    "bytes": int,  # Size of the fetched content in bytes
    "code": int,  # HTTP response code
    "codeText": str,  # HTTP response code text
    "result": str,  # Processed result from applying the prompt to the content
    "durationMs": int,  # Time to fetch and process the content, in milliseconds
    "url": str,  # URL that was fetched
}

WebSearch

Nom de l'outil : WebSearch

Entrée :

{
    "query": str,  # The search query to use
    "allowed_domains": list[str] | None,  # Only include results from these domains
    "blocked_domains": list[str] | None,  # Never include results from these domains
}

Sortie :

{
    "query": str,  # The search query
    "results": list[str | {"tool_use_id": str, "content": list[{"title": str, "url": str}]}],
    "durationSeconds": float,  # Search duration in seconds
}

TodoWrite

Nom de l'outil : TodoWrite

Entrée :

{
    "todos": [
        {
            "content": str,  # The task description
            "status": "pending" | "in_progress" | "completed",  # Task status
            "activeForm": str,  # Active form of the description
        }
    ]
}

Sortie :

{
    "message": str,  # Success message
    "stats": {"total": int, "pending": int, "in_progress": int, "completed": int},
}

TaskCreate

Nom de l'outil : TaskCreate

Entrée :

{
    "subject": str,  # Short task title
    "description": str,  # Detailed task body
    "activeForm": str | None,  # Present-tense label shown while in progress
    "metadata": dict | None,  # Arbitrary caller metadata
}

Sortie :

{
    "task": {"id": str, "subject": str},  # Created task with assigned ID
}

TaskUpdate

Nom de l'outil : TaskUpdate

Entrée :

{
    "taskId": str,  # ID of the task to patch
    "status": Literal["pending", "in_progress", "completed", "deleted"] | None,
    "subject": str | None,
    "description": str | None,
    "activeForm": str | None,
    "addBlocks": list[str] | None,  # Task IDs this task now blocks
    "addBlockedBy": list[str] | None,  # Task IDs that now block this task
    "owner": str | None,
    "metadata": dict | None,
}

Sortie :

{
    "success": bool,
    "taskId": str,
    "updatedFields": list[str],  # Names of fields that changed
    "error": str | None,
    "statusChange": {"from": str, "to": str} | None,
}

TaskGet

Nom de l'outil : TaskGet

Entrée :

{
    "taskId": str,  # ID of the task to read
}

Sortie :

{
    "task": {
        "id": str,
        "subject": str,
        "description": str,
        "status": Literal["pending", "in_progress", "completed"],
        "blocks": list[str],
        "blockedBy": list[str],
    } | None,  # None when the ID is not found
}

TaskList

Nom de l'outil : TaskList

Entrée :

{}

Sortie :

{
    "tasks": [
        {
            "id": str,
            "subject": str,
            "status": Literal["pending", "in_progress", "completed"],
            "owner": str | None,
            "blockedBy": list[str],
        }
    ],
}

TaskOutput

Nom de l'outil : TaskOutput. Le nom précédent BashOutput est toujours accepté comme alias.

Entrée :

{
    "task_id": str,  # The task ID to get output from
    "block": bool,  # Whether to wait for completion (default True)
    "timeout": int,  # Max wait time in ms (default 30000)
}

Sortie :

{
    "retrieval_status": "success" | "timeout" | "not_ready",  # Whether the output was retrieved
    "task": dict | None,  # Task details: task_id, task_type, status, description, output, plus type-specific fields such as exitCode
}

TaskStop

Nom de l'outil : TaskStop. Les noms précédents KillShell et KillBash sont toujours acceptés comme alias.

Entrée :

{
    "task_id": str | None,  # The ID of the background task to stop
    "shell_id": str | None,  # Deprecated: use task_id instead
}

Sortie :

{
    "message": str,  # Status message about the operation
    "task_id": str,  # The ID of the task that was stopped
    "task_type": str,  # The type of the task that was stopped
    "command": str | None,  # The command or description of the stopped task
}

ExitPlanMode

Nom de l'outil : ExitPlanMode

Entrée :

{
    "plan": str  # The plan to run by the user for approval
}

Sortie :

{
    "message": str,  # Confirmation message
    "approved": bool | None,  # Whether user approved the plan
}

ListMcpResources

Nom de l'outil : ListMcpResourcesTool

Entrée :

{
    "server": str | None  # Optional server name to filter resources by
}

Sortie :

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

ReadMcpResource

Nom de l'outil : ReadMcpResourceTool

Entrée :

{
    "server": str,  # The MCP server name
    "uri": str,  # The resource URI to read
}

Sortie :

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

Construire une interface de conversation continue

L'exemple suivant maintient un seul ClaudeSDKClient connecté à travers les tours, afin que Claude se souvienne des messages antérieurs. Tapez new pour vous déconnecter et vous reconnecter pour une nouvelle session, ou exit pour terminer la conversation.

from claude_agent_sdk import (
    ClaudeSDKClient,
    ClaudeAgentOptions,
    AssistantMessage,
    TextBlock,
)
import asyncio


class ConversationSession:
    """Maintains a single conversation session with Claude."""

    def __init__(self, options: ClaudeAgentOptions | None = None):
        self.client = ClaudeSDKClient(options)
        self.turn_count = 0

    async def start(self):
        await self.client.connect()
        print("Starting conversation session. Claude will remember context.")
        print(
            "Commands: 'exit' to quit, 'interrupt' to stop current task, 'new' for new session"
        )

        while True:
            user_input = input(f"\n[Turn {self.turn_count + 1}] You: ")

            if user_input.lower() == "exit":
                break
            elif user_input.lower() == "interrupt":
                await self.client.interrupt()
                print("Task interrupted!")
                continue
            elif user_input.lower() == "new":
                # Disconnect and reconnect for a fresh session
                await self.client.disconnect()
                await self.client.connect()
                self.turn_count = 0
                print("Started new conversation session (previous context cleared)")
                continue

            # Send message - the session retains all previous messages
            await self.client.query(user_input)
            self.turn_count += 1

            # Process response
            print(f"[Turn {self.turn_count}] Claude: ", end="")
            async for message in self.client.receive_response():
                if isinstance(message, AssistantMessage):
                    for block in message.content:
                        if isinstance(block, TextBlock):
                            print(block.text, end="")
            print()  # New line after response

        await self.client.disconnect()
        print(f"Conversation ended after {self.turn_count} turns.")


async def main():
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Write", "Bash"], permission_mode="acceptEdits"
    )
    session = ConversationSession(options)
    await session.start()


# Example conversation:
# Turn 1 - You: "Create a file called hello.py"
# Turn 1 - Claude: "I'll create a hello.py file for you..."
# Turn 2 - You: "What's in that file?"
# Turn 2 - Claude: "The hello.py file I just created contains..." (remembers!)
# Turn 3 - You: "Add a main function to it"
# Turn 3 - Claude: "I'll add a main function to hello.py..." (knows which file!)

asyncio.run(main())

Gestion des erreurs

L'exemple suivant encapsule un appel query() dans des gestionnaires pour quatre des types d'erreurs que le SDK lève.

Cet exemple capture ResultError, qui nécessite Python Agent SDK 0.2.140 ou version ultérieure.

import asyncio

from claude_agent_sdk import (
    query,
    CLINotFoundError,
    ProcessError,
    ResultError,
    CLIJSONDecodeError,
)


async def main():
    try:
        async for message in query(prompt="Hello"):
            print(message)
    except CLINotFoundError:
        print(
            "Claude Code CLI not found. Try reinstalling: pip install --force-reinstall claude-agent-sdk"
        )
    # Catch ResultError before ProcessError, which it subclasses. Its message
    # carries the error text. A failed final request, such as an API error,
    # arrives with subtype "success", so branch on terminal_reason first.
    except ResultError as e:
        if e.terminal_reason == "api_error":
            print(f"API request failed: {e}")
        else:
            print(f"Query ended with an error result ({e.terminal_reason or e.subtype}): {e}")
    except ProcessError as e:
        print(f"Process failed with exit code: {e.exit_code}")
    except CLIJSONDecodeError as e:
        print(f"Failed to parse response: {e}")


asyncio.run(main())

Configuration du sandbox

`SandboxSettings`

Configuration pour le comportement du sandbox. Utilisez ceci pour activer le sandboxing des commandes et configurer les restrictions réseau programmatiquement.

class SandboxSettings(TypedDict, total=False):
    enabled: bool
    autoAllowBashIfSandboxed: bool
    excludedCommands: list[str]
    allowUnsandboxedCommands: bool
    network: SandboxNetworkConfig
    ignoreViolations: SandboxIgnoreViolations
    enableWeakerNestedSandbox: bool

Exemple d'utilisation

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions

sandbox_settings = {
    "enabled": True,
    "autoAllowBashIfSandboxed": True,
    "failIfUnavailable": True,
    "network": {"allowLocalBinding": True},
}


async def main():
    try:
        async for message in query(
            prompt="Build and test my project",
            options=ClaudeAgentOptions(sandbox=sandbox_settings),
        ):
            print(message)
    except Exception as error:
        # A single-shot query() raises after yielding an error result,
        # such as when failIfUnavailable is set and the sandbox can't start.
        print(f"Session ended with an error: {error}")


asyncio.run(main())

`SandboxNetworkConfig`

Configuration spécifique au réseau pour le mode sandbox. Ces paramètres s'appliquent aux commandes Bash en sandbox quand enabled est True dans le parent SandboxSettings. Ils ne restreignent pas l'outil WebFetch, qui utilise à la place des règles de permission.

class SandboxNetworkConfig(TypedDict, total=False):
    allowedDomains: list[str]
    deniedDomains: list[str]
    allowManagedDomainsOnly: bool
    allowUnixSockets: list[str]
    allowAllUnixSockets: bool
    allowLocalBinding: bool
    allowMachLookup: list[str]
    httpProxyPort: int
    socksProxyPort: int

`SandboxIgnoreViolations`

Configuration pour ignorer les violations de sandbox spécifiques.

class SandboxIgnoreViolations(TypedDict, total=False):
    file: list[str]
    network: list[str]

Fallback de permissions pour les commandes sans sandbox

Quand allowUnsandboxedCommands est activé, le modèle peut demander l'exécution de commandes en dehors du sandbox en définissant dangerouslyDisableSandbox: True dans l'entrée d'outil. Ces requêtes reviennent au système de permissions existant, ce qui signifie que votre gestionnaire can_use_tool sera invoqué, vous permettant d'implémenter une logique d'autorisation personnalisée. Les commandes listées dans excludedCommands contournent à la place le sandbox automatiquement, sans implication du modèle ; voir SandboxSettings.

L'exemple suivant enregistre chaque requête sans sandbox et la refuse sauf si votre propre logique d'autorisation l'autorise :

import asyncio
from claude_agent_sdk import (
    query,
    ClaudeAgentOptions,
    HookMatcher,
    PermissionResultAllow,
    PermissionResultDeny,
    ToolPermissionContext,
)


def is_command_authorized(command: str | None) -> bool:
    # Replace with your own authorization logic
    return False



async def can_use_tool(
    tool: str, input: dict, context: ToolPermissionContext
) -> PermissionResultAllow | PermissionResultDeny:
    # Check if the model is requesting to bypass the sandbox
    if tool == "Bash" and input.get("dangerouslyDisableSandbox"):
        # The model is requesting to run this command outside the sandbox
        print(f"Unsandboxed command requested: {input.get('command')}")

        if is_command_authorized(input.get("command")):
            return PermissionResultAllow()
        return PermissionResultDeny(
            message="Command not authorized for unsandboxed execution"
        )
    return PermissionResultAllow()


# Required: dummy hook keeps the stream open for can_use_tool
async def dummy_hook(input_data, tool_use_id, context):
    return {"continue_": True}


async def prompt_stream():
    yield {
        "type": "user",
        "message": {"role": "user", "content": "Deploy my application"},
    }


async def main():
    async for message in query(
        prompt=prompt_stream(),
        options=ClaudeAgentOptions(
            sandbox={
                "enabled": True,
                "allowUnsandboxedCommands": True,  # Model can request unsandboxed execution
            },
            permission_mode="default",
            can_use_tool=can_use_tool,
            hooks={"PreToolUse": [HookMatcher(matcher=None, hooks=[dummy_hook])]},
        ),
    ):
        print(message)


asyncio.run(main())

Voir aussi

• Vue d'ensemble du SDK - Concepts généraux du SDK
• Référence du SDK TypeScript - Documentation du SDK TypeScript
• Outils personnalisés - Définir des outils MCP en processus pour que Claude appelle
• Référence CLI - Interface de ligne de commande
• Flux de travail courants - Guides étape par étape