Riferimento SDK Agent - Python

Riferimento API completo per Python Agent SDK, incluse tutte le funzioni, i tipi e le classi.

Installazione

Installare il pacchetto in un ambiente virtuale. Su recenti installazioni di Debian, Ubuntu e Homebrew Python, l'esecuzione di pip install su Python di sistema fallisce con error: externally-managed-environment.

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

Per uv, Windows PowerShell e configurazione della chiave API, vedere Iniziare nella guida rapida di Agent SDK.

Scelta tra `query()` e `ClaudeSDKClient`

Python SDK fornisce due modi per interagire con Claude Code:

Utilizzare ClaudeSDKClient per applicazioni interattive come interfacce chat, o quando l'azione successiva dipende dalla risposta di Claude.

Funzioni

`query()`

Crea una nuova sessione per ogni interazione con Claude Code per impostazione predefinita. Restituisce un iteratore asincrono che produce messaggi man mano che arrivano. Ogni chiamata a query() inizia da zero senza memoria di interazioni precedenti a meno che non passiate continue_conversation=True o resume in ClaudeAgentOptions. Vedi Sessions.

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

Parametri

Restituisce

Restituisce un AsyncIterator[Message] che produce messaggi dalla conversazione.

Esempio - Con opzioni

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()`

Decoratore per definire strumenti MCP con sicurezza dei tipi.

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]]

Parametri

Opzioni dello schema di input

1. Mappatura di tipo semplice (consigliato):

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

2. Formato JSON Schema (per validazione complessa):

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

Restituisce

Una funzione decoratore che avvolge l'implementazione dello strumento e restituisce un'istanza SdkMcpTool.

Esempio

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`

Suggerimenti comportamentali per uno strumento, passati come argomento annotations di tool(). ToolAnnotations estende mcp.types.ToolAnnotations dell'SDK MCP con un campo maxResultSizeChars, e potete scrivere ogni suggerimento in camelCase o snake_case: ToolAnnotations(readOnlyHint=True) e ToolAnnotations(read_only_hint=True) sono equivalenti. Potete anche passare un semplice mcp.types.ToolAnnotations ovunque l'SDK accetti annotazioni.

I nomi snake_case e il campo tipizzato maxResultSizeChars richiedono Python Agent SDK 0.2.140 o successivo. Le versioni da 0.1.31 a 0.2.139 riesportano mcp.types.ToolAnnotations senza modifiche. Nelle versioni da 0.1.55 a 0.2.139 potete comunque passare maxResultSizeChars come argomento di parola chiave: la classe MCP accetta campi extra e l'SDK invia il valore a Claude Code.

Tutti i campi sono opzionali. I client non dovrebbero fare affidamento sui suggerimenti per decisioni di sicurezza.

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()`

Crea un server MCP in-process che viene eseguito all'interno della tua applicazione Python.

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

Parametri

Restituisce

Restituisce un oggetto McpSdkServerConfig che può essere passato a ClaudeAgentOptions.mcp_servers.

Esempio

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()`

Elenca le sessioni passate con metadati. Filtra per directory di progetto o elenca le sessioni in tutti i progetti. Sincrono; restituisce immediatamente.

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

Parametri

Tipo di ritorno: `SDKSessionInfo`

Esempio

Stampa le 10 sessioni più recenti per un progetto. I risultati sono ordinati per last_modified decrescente, quindi il primo elemento è il più recente. Ometti directory per cercare in tutti i progetti.

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()`

Recupera i messaggi da una sessione passata. Sincrono; restituisce immediatamente.

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

Parametri

Tipo di ritorno: `SessionMessage`

Esempio

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()`

Legge i metadati per una singola sessione per ID senza scansionare la directory del progetto completo. Sincrono; restituisce immediatamente.

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

Parametri

Restituisce SDKSessionInfo, o None se la sessione non viene trovata.

Esempio

Cerca i metadati di una singola sessione senza scansionare la directory del progetto. Utile quando hai già un ID di sessione da un'esecuzione precedente.

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()`

Rinomina una sessione aggiungendo una voce di titolo personalizzato. Le chiamate ripetute sono sicure; il titolo più recente vince. Sincrono.

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

Parametri

Genera ValueError se session_id non è un UUID valido o title è vuoto; FileNotFoundError se la sessione non può essere trovata.

Esempio

Rinomina la sessione più recente in modo che sia più facile da trovare in seguito. Il nuovo titolo appare in SDKSessionInfo.custom_title nelle letture successive.

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()`

Etichetta una sessione. Passa None per cancellare l'etichetta. Le chiamate ripetute sono sicure; l'etichetta più recente vince. Sincrono.

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

Parametri

Genera ValueError se session_id non è un UUID valido o tag è vuoto dopo la sanitizzazione; FileNotFoundError se la sessione non può essere trovata.

Esempio

Etichetta una sessione, quindi filtra per quell'etichetta in una lettura successiva. Passa None per cancellare un'etichetta esistente.

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)

Classi

`ClaudeSDKClient`

Mantiene una sessione di conversazione in più scambi. Questo è l'equivalente Python di come la funzione query() di TypeScript SDK funziona internamente - crea un oggetto client che può continuare le conversazioni. Vedi il confronto con 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

Metodi

Supporto Context Manager

Il client può essere utilizzato come context manager asincrono per la gestione automatica della connessione:

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())

Importante: Quando iteri sui messaggi, evita di usare break per uscire anticipatamente poiché questo può causare problemi di pulizia asyncio. Invece, lascia che l'iterazione si completi naturalmente o usa flag per tracciare quando hai trovato quello che cerchi.

Esempio - Continuare una conversazione

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())

Esempio - Input streaming con 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())

Esempio - Utilizzo di interruzioni

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())

Esempio - Controllo avanzato delle autorizzazioni

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():
    # Non elencare anche gli strumenti gated in allowed_tools: le regole di autorizzazione approvano le chiamate prima che can_use_tool venga eseguito
    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())

Tipi

`SdkMcpTool`

Definizione per uno strumento SDK MCP creato con il decoratore @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 base astratta per implementazioni di trasporto personalizzate. Usala per comunicare con il processo Claude su un canale personalizzato (ad esempio, una connessione remota invece di un subprocess locale).

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: ...

Importazione: from claude_agent_sdk import Transport

`ClaudeAgentOptions`

Dataclass di configurazione per le query 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

Gestisci risposte API lente o bloccate

Il subprocess CLI legge diverse variabili di ambiente che controllano i timeout dell'API e il rilevamento dei blocchi. Passale attraverso 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: timeout per richiesta sul client Anthropic, in millisecondi. Predefinito 600000. Si applica al ciclo principale e a tutti i subagenti.

• CLAUDE_CODE_MAX_RETRIES: numero massimo di tentativi API. Predefinito 10, limitato a 15. Ogni tentativo ottiene la propria finestra API_TIMEOUT_MS, quindi il tempo di parete nel caso peggiore è approssimativamente API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1) più backoff. Per esecuzioni incustodite che devono attendere interruzioni più lunghe, imposta CLAUDE_CODE_RETRY_WATCHDOG=1: ritenta gli errori di capacità transitori indefinitamente e, a partire da Claude Code v2.1.199, aumenta il valore predefinito per altri errori transitori a 300 e rimuove il limite su questa variabile.

• CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS: watchdog di blocco per i subagenti. Mentre il watchdog del flusso è attivo, il predefinito è CLAUDE_STREAM_IDLE_TIMEOUT_MS più 5 minuti, che ammonta a 600000 a meno che non aumenti quella variabile. Con il watchdog del flusso disattivato, il predefinito è 600000. Prima di v2.1.257, il predefinito era sempre 600000.

  Il timer si ripristina su ogni evento di flusso. In caso di blocco, Claude Code interrompe il subagente e segnala il blocco al genitore. Per un subagente in background, contrassegna anche l'attività come non riuscita e allega qualsiasi risultato parziale.

• CLAUDE_ENABLE_STREAM_WATCHDOG con CLAUDE_STREAM_IDLE_TIMEOUT_MS: watchdog del flusso che interrompe la richiesta quando le intestazioni sono arrivate ma il corpo della risposta smette di trasmettere. Il watchdog è attivo per impostazione predefinita per tutti i provider; imposta CLAUDE_ENABLE_STREAM_WATCHDOG=0 per disabilitarlo. CLAUDE_STREAM_IDLE_TIMEOUT_MS predefinito a 300000 e viene bloccato a quel minimo. Dopo l'interruzione, Tentativi automatici copre cosa Claude Code fa, in base a quanto la risposta aveva progredito.

  Mentre il watchdog attende una risposta che un gateway dietro ANTHROPIC_BASE_URL tiene aperta con ping keep-alive, un host che imposta include_partial_messages continua a ricevere messaggi StreamEvent di ping. Leggi quei frame come vivacità piuttosto che cronometrare la sessione su silenzio. Prima di v2.1.257, i frame si fermavano 5 minuti dopo l'ultimo evento di flusso reale.

`OutputFormat`

Configurazione per la validazione dell'output strutturato. Passa questo come dict al campo output_format su ClaudeAgentOptions:

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

`SystemPromptPreset`

Configurazione per l'utilizzo del prompt di sistema preset di Claude Code con aggiunte opzionali.

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

`SystemPromptCustom`

Un prompt di sistema personalizzato in forma di oggetto, equivalente a passare una stringa come system_prompt, che può anche impostare snapshot. Richiede claude-agent-sdk v0.2.153 o successivo.

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

`SystemPromptFile`

Configurazione per il caricamento di un prompt di sistema personalizzato da un file invece di passarlo come stringa. L'SDK mappa questo al flag CLI --system-prompt-file. Usa il modulo file quando il prompt è grande: l'SDK passa una stringa system_prompt sull'argv del subprocess CLI, che è soggetto ai limiti di lunghezza della riga di comando del sistema operativo prima che l'SDK invii qualsiasi richiesta API. Su Linux un singolo argomento più lungo di circa 128 KB fallisce al spawn del processo con Argument list too long. Su Windows l'intera riga di comando è limitata a circa 32 KB, quindi il modulo stringa fallisce a una soglia inferiore.

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

`SettingSource`

Controlla quali fonti di configurazione basate su filesystem l'SDK carica le impostazioni da.

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

Comportamento predefinito

Quando setting_sources è omesso o None e skills non è impostato, query() carica le stesse impostazioni del filesystem della CLI di Claude Code: utente, progetto e locale. Con skills impostato, la riga setting_sources descrive il valore predefinito corrente. La politica gestita dall'endpoint viene caricata in tutti i casi; le impostazioni gestite dal server vengono recuperate quando la sessione si autentica con una credenziale organizzativa su una configurazione idonea. Per ulteriori informazioni, vedi Cosa settingSources non controlla.

Perché usare setting\_sources

Disabilita le impostazioni del filesystem:

# 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())

Carica solo fonti di impostazioni specifiche:

# 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())

Applicazioni solo SDK:

# 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())

Per caricare le istruzioni del progetto CLAUDE.md, includi "project" in setting_sources. Vedi Modifica i prompt di sistema per come il caricamento di CLAUDE.md interagisce con le opzioni del prompt di sistema.

Precedenza delle impostazioni

Quando più fonti vengono caricate, le impostazioni vengono unite con questa precedenza (da più alta a più bassa):

1. Impostazioni locali (.claude/settings.local.json)
2. Impostazioni di progetto (.claude/settings.json)
3. Impostazioni utente (~/.claude/settings.json)

Le opzioni programmatiche come agents, allowed_tools e settings sovrascrivono le impostazioni del filesystem utente, progetto e locale. Le impostazioni della politica gestita hanno la precedenza sulle opzioni programmatiche.

`AgentDefinition`

Configurazione per un subagente definito programmaticamente.

@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`

Modalità di autorizzazione per controllare l'esecuzione dello strumento.

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`

Livelli di sforzo per guidare la profondità del pensiero.

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 di tipo per le funzioni di callback di autorizzazione dello strumento.

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

Il callback riceve:

• tool_name: Nome dello strumento che viene chiamato
• input_data: I parametri di input dello strumento
• context: Un ToolPermissionContext con informazioni aggiuntive

Restituisce un PermissionResult (sia PermissionResultAllow che PermissionResultDeny).

Il callback è il sostituto SDK per il prompt di autorizzazione interattivo: viene invocato solo quando il flusso di valutazione delle autorizzazioni si risolve in un prompt. Le chiamate dello strumento già approvate da una voce allowed_tools, una regola di autorizzazione nelle impostazioni, o la modalità di autorizzazione, come acceptEdits o bypassPermissions, non lo invocano mai. Per controllare ogni chiamata dello strumento, usa un hook PreToolUse invece.

Una regola di autorizzazione non pre-approva le azioni che nessuna modalità auto-approva; vedi Come vengono valutate le autorizzazioni per quali di esse raggiungono il callback e cosa accade in modalità dontAsk e auto.

`ToolPermissionContext`

Informazioni di contesto passate ai callback di autorizzazione dello strumento.

@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`

Tipo di unione per i risultati del callback di autorizzazione.

PermissionResult = PermissionResultAllow | PermissionResultDeny

`PermissionResultAllow`

Risultato che indica che la chiamata dello strumento deve essere consentita.

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

`PermissionResultDeny`

Risultato che indica che la chiamata dello strumento deve essere negata.

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

`PermissionUpdate`

Configurazione per l'aggiornamento delle autorizzazioni a livello di programmazione.

@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`

Una regola da aggiungere, sostituire o rimuovere in un aggiornamento delle autorizzazioni.

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

`ToolsPreset`

Configurazione degli strumenti preset per l'utilizzo del set di strumenti predefinito di Claude Code.

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

`ThinkingConfig`

Controlla il comportamento del pensiero esteso. Un'unione di tre configurazioni:

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

Il campo opzionale display controlla se il testo di pensiero viene restituito "summarized" o "omitted". Su Claude Opus 4.7 e versioni successive, l'impostazione predefinita dell'API è "omitted", quindi imposta "summarized" per ricevere il contenuto di pensiero negli output ThinkingBlock. Claude Code non invia display ad Amazon Bedrock o alla piattaforma agente di Google Cloud, quindi su quei provider Opus 4.7 e versioni successive restituiscono output ThinkingBlock vuoti anche quando imposti display a "summarized".

Poiché queste sono classi TypedDict, sono dicts semplici in fase di esecuzione. Costruiscile come letterali dict o chiama la classe come costruttore; entrambi producono un dict. Accedi ai campi con config["budget_tokens"], non 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 di attività lato API in token, utilizzato con il campo task_budget in ClaudeAgentOptions.

class TaskBudget(TypedDict):
    total: int

Poiché questo è un TypedDict, passalo come dict semplice, come ClaudeAgentOptions(task_budget={"total": 50000}).

`SdkBeta`

Tipo letterale per le funzionalità beta dell'SDK.

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

Usa con il campo betas in ClaudeAgentOptions per abilitare le funzionalità beta.

`McpSdkServerConfig`

Configurazione per i server MCP dell'SDK creati con create_sdk_mcp_server().

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

`McpServerConfig`

Tipo di unione per le configurazioni del server 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 configurazione di un server MCP come riportato da get_mcp_status(). Questa è l'unione di tutte le varianti di trasporto McpServerConfig più una variante di output-only claudeai-proxy per i server proxy attraverso claude.ai.

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

McpSdkServerConfigStatus è la forma serializzabile di McpSdkServerConfig con solo i campi type ("sdk") e name (str); l'instance in-process viene omesso. McpClaudeAIProxyServerConfig ha i campi type ("claudeai-proxy"), url (str), e id (str).

`McpStatusResponse`

Risposta da ClaudeSDKClient.get_mcp_status(). Avvolge l'elenco degli stati del server sotto la chiave mcpServers.

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

`McpServerStatus`

Stato di un server MCP connesso, contenuto in 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`

Configurazione per il caricamento dei plugin nell'SDK.

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

Esempio:

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

Per informazioni complete sulla creazione e l'utilizzo dei plugin, vedi Plugin.

Tipi di messaggio

`Message`

Tipo di unione di tutti i possibili messaggi.

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

`UserMessage`

Messaggio di input dell'utente.

@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

L'SDK passa tool_use_result attraverso dalla CLI senza modifiche. Per uno strumento su un server MCP esterno il cui risultato contiene blocchi resource_link, il dict ha una chiave resourceLinks che contiene un elenco di dict con le chiavi del tipo TypeScript SDKMcpResourceLink. Claude riceve ogni link come una riga di testo nel risultato dello strumento. Per renderizzare i file restituiti dal server, leggi resourceLinks invece di analizzare quel testo. La chiave resourceLinks richiede Python Agent SDK 0.2.150 o successivo e Claude Code v2.1.257 o successivo; la CLI fornita con quella versione dell'SDK soddisfa il requisito di Claude Code.

La CLI omette la chiave quando il risultato non ha link e sui risultati dei subagenti. La CLI mantiene al massimo 50 link per risultato e smette di aggiungere link una volta che l'elenco raggiunge 64 KiB di JSON serializzato. Uno strumento che definisci in-process con tool() non produce mai la chiave, perché l'SDK appiattisce i suoi blocchi resource_link a testo prima che la CLI veda il risultato.

`AssistantMessage`

Messaggio di risposta dell'assistente con blocchi di contenuto.

@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`

Possibili tipi di errore per i messaggi dell'assistente.

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

Il processo CLI sottostante può emettere tipi di errore che questo Literal non elenca, come max_output_tokens. L'SDK passa il valore attraverso senza modifiche, quindi tratta le stringhe al di fuori di questo elenco come tratteresti unknown. Il tipo TypeScript SDKAssistantMessageError elenca l'insieme completo di valori che la CLI può emettere.

`SystemMessage`

Messaggio di sistema con metadati.

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

`ResultMessage`

Messaggio di risultato finale con informazioni su costo e utilizzo.

@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

Il campo subtype determina quali altri campi sono popolati. È uno di "success", "error_during_execution", "error_max_turns", "error_max_budget_usd", o "error_max_structured_output_retries". La dataclass Python appiattisce tutte le varianti in una forma, quindi i campi che non si applicano al subtype restituito sono None.

Diversi campi portano dettagli diagnostici su come la conversazione è terminata:

• is_error: True quando la conversazione è terminata in uno stato di errore. Sempre True sui subtype error_*. Su subtype="success" è True quando la richiesta del modello finale ha fallito, il che significa che il ciclo dell'agente è stato completato ma l'ultima chiamata API ha restituito un errore.
• api_error_status: il codice di stato HTTP dell'errore API terminale. None quando il turno è terminato senza uno. Popolato solo su subtype="success".
• result: testo del messaggio dell'assistente finale su subtype="success", o None sui subtype error_*. Quando subtype="success" e is_error=True, questo contiene la stringa di errore API se disponibile ma può essere vuoto, quindi controlla api_error_status e il contenuto di AssistantMessage precedente per i dettagli.
• errors: stringhe di errore a livello di ciclo come il messaggio max-turns. Popolato solo sui subtype error_*.
• terminal_reason: perché il ciclo di query è terminato, come "completed", "max_turns", "api_error", "aborted_streaming", o "aborted_tools". Un valore di "aborted_streaming" o "aborted_tools" significa che il turno è stato interrotto prima del completamento. Le cause comuni sono interrupt() e un callback di permesso che restituisce PermissionResultDeny con interrupt=True. None su versioni CLI che precedono il campo, su risultati da comandi locali come /voice o /usage, che bypassano il ciclo di query, o su risultati di errore sintetizzati emessi quando la sessione fallisce fatalmente. Rispecchia il SDKResultMessage.terminal_reason dell'SDK TypeScript, che elenca l'insieme completo di valori.
• origin: origine del messaggio utente che ha attivato questo turno. In modalità input streaming, controlla questo per distinguere il risultato del tuo prompt, dove origin è None o {"kind": "human"}, dal risultato di un turno iniettato come una notifica di attività in background. Richiede Python Agent SDK 0.2.137 o successivo.

Il dict usage copre solo il ciclo dell'agente principale ed esclude i subagenti e altre chiamate di modello nidificate o ausiliarie. In modalità input streaming, i valori sono per turno. Preferisci model_usage per la contabilità dei token e dei costi. Il dict usage contiene le seguenti chiavi quando presenti:

Il dict model_usage mappa i nomi dei modelli all'utilizzo per modello. Copre ogni chiamata di modello effettuata attraverso la pipeline di query: il ciclo principale, i subagenti e le chiamate interne come la compattazione e gli agenti Workflow. Le chiamate helper al di fuori di quella pipeline, come il classificatore di permessi e le richieste di conteggio dei token, sono escluse da model_usage. Tratta model_usage come una stima, non come un estratto conto di fatturazione.

In modalità input streaming, model_usage e total_cost_usd sono cumulativi tra i turni, quindi leggi il risultato più recente piuttosto che sommare tra i risultati. Una chiamata che riprende una sessione conta anche i totali ripristinati dalle chiamate precedenti della sessione. Vedi Traccia i costi in modalità input streaming per i ripristini e Recupera i totali dopo un crash della sessione per i risultati azzerati.

Ogni valore in model_usage è un TypedDict ModelUsage, importato tramite from claude_agent_sdk.types import ModelUsage. Le sue chiavi usano camelCase perché l'SDK passa il valore attraverso senza modifiche dal processo CLI sottostante, corrispondendo al tipo TypeScript ModelUsage:

`StreamEvent`

Evento di flusso per aggiornamenti di messaggi parziali durante lo streaming. Ricevuto solo quando include_partial_messages=True in ClaudeAgentOptions. Importa tramite 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`

Emesso quando lo stato del limite di velocità cambia (ad esempio, da "allowed" a "allowed_warning"). Usalo per avvertire gli utenti prima che raggiungano un limite rigido, o per fare backoff quando lo stato è "rejected".

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

`RateLimitInfo`

Stato del limite di velocità trasportato da 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`

Emesso quando la conversazione viene sostituita senza terminare la connessione, come dopo /clear. Vedi Traccia i costi in modalità input streaming per come un ripristino influisce sui totali in esecuzione su oggetti ResultMessage successivi. Richiede Python Agent SDK 0.2.137 o successivo.

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

`TaskStartedMessage`

Emesso quando un'attività in background inizia. Un'attività in background è qualsiasi cosa tracciata al di fuori del turno principale: un comando Bash in background, un watch Monitor, un subagente generato tramite lo strumento Agent, o un agente remoto. Il campo task_type ti dice quale. Questo nome non è correlato al rinomina dello strumento Task-to-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`

Dati di token e timing per un'attività in background.

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

`TaskProgressMessage`

Emesso periodicamente con aggiornamenti di progresso per un'attività in background in esecuzione.

@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`

Emesso quando un'attività in background si completa, fallisce o viene interrotta. Le attività in background includono comandi Bash run_in_background, watch Monitor e subagenti in background.

@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

Quando la CLI sposta una lunga chiamata di strumento MCP in background, il risultato dello strumento per quella chiamata contiene solo un placeholder e il risultato reale della chiamata arriva in questo messaggio. Su una notifica "completed" per tale chiamata, la CLI aggiunge una chiave resource_links che elenca i file restituiti dallo strumento per riferimento, con le stesse voci e limiti della chiave resourceLinks su UserMessage.tool_use_result. La chiave resource_links richiede Python Agent SDK 0.2.150 o successivo e Claude Code v2.1.257 o successivo; la CLI fornita con quella versione dell'SDK soddisfa il requisito di Claude Code.

La dataclass non ha un campo per resource_links. Leggilo dal dict data che il messaggio eredita da SystemMessage: message.data.get("resource_links"). Abbina la notifica alla chiamata con tool_use_id. La CLI omette la chiave quando il risultato non aveva link e su notifiche per attività che non sono chiamate di strumento MCP.

Tipi di blocco di contenuto

`ContentBlock`

Tipo di unione di tutti i blocchi di contenuto.

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

`TextBlock`

Blocco di contenuto di testo.

@dataclass
class TextBlock:
    text: str

`ThinkingBlock`

Blocco di contenuto di pensiero (per modelli con capacità di pensiero).

@dataclass
class ThinkingBlock:
    thinking: str
    signature: str

`ToolUseBlock`

Blocco di richiesta di utilizzo dello strumento.

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

`ToolResultBlock`

Blocco di risultato dell'esecuzione dello strumento.

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

Tipi di errore

I tipi di seguito definiscono cosa il vostro codice cattura. Per le voci associate ai messaggi di errore che questi tipi generano, con la causa e la correzione per ciascuno, consultate Troubleshooting.

`ClaudeSDKError`

Classe di eccezione base per tutti gli errori dell'SDK.

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

Quando una singola query() termina con un risultato di errore, ad esempio un errore di limite di turni, l'SDK genera un ResultError dopo aver restituito il messaggio di risultato finale. Le versioni di Python Agent SDK precedenti alla 0.2.140 generavano una semplice Exception che non era una sottoclasse di ClaudeSDKError.

`CLINotFoundError`

Generato quando Claude Code CLI non è installato o non viene trovato.

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`

Generato quando la connessione a Claude Code fallisce.

class CLIConnectionError(ClaudeSDKError):
    """Failed to connect to Claude Code."""

`ProcessError`

Generato quando il processo Claude Code fallisce.

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`

Generato dopo il ResultMessage finale quando il processo Claude Code esce perché l'esecuzione è terminata con un risultato di errore, come un errore di limite di turni o un errore API. ResultError è una sottoclasse di ProcessError, quindi un gestore except ProcessError esistente lo cattura anche. I suoi attributi contengono i campi di quel messaggio di risultato, quindi potete distinguere il motivo del fallimento dell'esecuzione senza analizzare il testo del messaggio. Richiede Python Agent SDK 0.2.140 o successivo.

class ResultError(ProcessError):
    subtype: str | None  # "error_max_turns", "error_during_execution", ...; "success" quando l'esecuzione è terminata su una richiesta non riuscita
    errors: list[str]  # un elenco vuoto quando il messaggio di risultato non ne ha segnalati
    result: str | None
    api_error_status: int | None
    terminal_reason: str | None  # "max_turns", "api_error", ...; controllate questo prima di subtype
    session_id: str | None
    data: dict[str, Any]  # il payload del messaggio di risultato grezzo

Per distinguere i fallimenti, controllate terminal_reason prima di subtype. Quando la richiesta finale fallisce, ad esempio su un errore API, Claude Code segnala subtype "success" con la causa in terminal_reason, ad esempio "api_error"; quando un limite che avete impostato termina l'esecuzione, come max_turns o max_budget_usd, segnala un subtype di tipo error_*.

`CLIJSONDecodeError`

Generato quando l'analisi JSON fallisce.

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

Tipi di Hook

Per una guida completa sull'utilizzo degli hooks con esempi e modelli comuni, vedi la guida Hooks.

`HookEvent`

Tipi di evento hook supportati.

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`

Definizione di tipo per le funzioni di callback hook.

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

Parametri:

• input: Input hook fortemente tipizzato con unioni discriminate basate su hook_event_name (vedi HookInput)
• tool_use_id: Identificatore di utilizzo dello strumento opzionale (per hook correlati allo strumento)
• context: Contesto hook con informazioni aggiuntive

Restituisce un HookJSONOutput.

`HookContext`

Informazioni di contesto passate ai callback hook.

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

`HookMatcher`

Configurazione per l'abbinamento degli hook a eventi o strumenti specifici.

@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`

Tipo di unione di tutti i tipi di input hook. Il tipo effettivo dipende dal campo hook_event_name.

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

`BaseHookInput`

Campi di base presenti in tutti i tipi di input hook.

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

`PreToolUseHookInput`

Dati di input per gli eventi 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`

Dati di input per gli eventi 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`

Dati di input per gli eventi hook PostToolUseFailure. Chiamato quando l'esecuzione di uno strumento fallisce.

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`

Dati di input per gli eventi hook UserPromptSubmit.

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

`StopHookInput`

Dati di input per gli eventi hook Stop.

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

`SubagentStopHookInput`

Dati di input per gli eventi 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`

Dati di input per gli eventi hook PreCompact.

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

`NotificationHookInput`

Dati di input per gli eventi hook Notification.

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

`SubagentStartHookInput`

Dati di input per gli eventi hook SubagentStart.

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

`PermissionRequestHookInput`

Dati di input per gli eventi hook PermissionRequest. Consente agli hook di gestire le decisioni di autorizzazione a livello di programmazione.

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`

Tipo di unione per i valori di ritorno del callback hook.

HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput

`SyncHookJSONOutput`

Output hook sincrono con campi di controllo e decisione.

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`

Un'unione discriminata di tipi di output specifici dell'evento TypedDict. Il campo hookEventName determina quali campi sono validi. Per i dettagli completi sui campi disponibili per evento hook, vedi Controlla l'esecuzione con gli 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`

Output hook asincrono che rinvia l'esecuzione dell'hook.

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

Esempio di utilizzo di Hook

Questo esempio registra due hook: uno che blocca i comandi bash pericolosi come rm -rf /, e un altro che registra tutto l'utilizzo dello strumento per il controllo. L'hook di sicurezza viene eseguito solo sui comandi Bash (tramite il matcher), mentre l'hook di registrazione viene eseguito su tutti gli strumenti.

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())

Tipi di input/output dello strumento

Documentazione degli schemi di input/output per tutti gli strumenti Claude Code integrati. Mentre Python SDK non esporta questi come tipi, rappresentano la struttura degli input e output dello strumento nei messaggi.

Agent

Nome dello strumento: Agent. Il nome precedente Task è ancora accettato come alias, e l'elenco tools nel SystemMessage di init riporta questo strumento come Task per compatibilità all'indietro.

Input:

{
    "description": str,  # Una breve descrizione del compito (3-5 parole)
    "prompt": str,  # Il compito che l'agente deve eseguire
    "subagent_type": str | None,  # Il tipo di agente specializzato da utilizzare
    "model": "sonnet" | "opus" | "haiku" | "fable" | None,  # Override del modello per questo agente
    "run_in_background": bool | None,  # Gli agenti vengono eseguiti in background per impostazione predefinita; impostare su False per eseguire in modo sincrono
    "name": str | None,  # Nome per l'agente generato
    "team_name": str | None,  # Deprecato; ignorato
    "mode": "acceptEdits" | "auto" | "bypassPermissions" | "default" | "dontAsk" | "plan" | None,  # Deprecato; ignorato. Le regole di ereditarietà dei subagenti decidono la modalità di autorizzazione di un subagente
    "isolation": "worktree" | "remote" | None,  # Modalità di isolamento per le modifiche dell'agente
}

Avvia un nuovo agente per gestire compiti complessi e multi-step in modo autonomo.

Output (status: "completed"):

{
    "status": "completed",
    "agentId": str,  # ID dell'agente che è stato eseguito
    "agentType": str | None,  # Il tipo di subagente che ha gestito il compito
    "content": [  # Blocchi di contenuto del risultato
        {
            "type": "text",
            "text": str,
            "citations": list | None,
        }
    ],
    "resolvedModel": str | None,  # Modello su cui il subagente ha iniziato
    "modelsUsed": list[str] | None,  # Modelli utilizzati in ordine, con ripetizioni consecutive compresse
    "totalToolUseCount": int,  # Numero di chiamate di strumento effettuate dall'agente
    "totalDurationMs": int,  # Durata dell'esecuzione in millisecondi
    "totalTokens": int,  # Conteggio dei token dalla richiesta API finale, non dall'intera esecuzione
    "usage": {  # Statistiche di utilizzo dei token
        "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": {  # Attività aggregata dello strumento per l'esecuzione
        "readCount": int,
        "searchCount": int,
        "bashCount": int,
        "editFileCount": int,
        "linesAdded": int,
        "linesRemoved": int,
        "otherToolCount": int,
        "frameCount": int | None,
    } | None,
    "prompt": str,  # Il prompt che l'agente ha eseguito
    "worktreePath": str | None,  # Presente quando Claude Code ha mantenuto il worktree del subagente
    "worktreeBranch": str | None,  # Presente quando Claude Code ha creato quel worktree con git
}

Output (status: "async_launched"):

{
    "status": "async_launched",
    "isAsync": bool | None,  # True al lancio in background
    "agentId": str,  # ID dell'agente lanciato
    "description": str,  # La descrizione del compito
    "resolvedModel": str | None,  # Modello in uso alla transizione di backgrounding
    "modelsUsed": list[str] | None,  # Modelli utilizzati prima del backgrounding, in ordine, con ripetizioni consecutive compresse
    "prompt": str,  # Il prompt che l'agente esegue
    "outputFile": str,  # Percorso del file dove viene scritto l'output dell'agente
    "canReadOutputFile": bool | None,  # Se il file di output può essere letto direttamente
}

Output (status: "remote_launched"):

{
    "status": "remote_launched",
    "taskId": str,  # ID dell'attività remota
    "sessionUrl": str,  # Collegamento alla sessione cloud remota
    "description": str,  # La descrizione del compito
    "prompt": str,  # Il prompt che l'agente esegue
    "outputFile": str,  # Percorso del file dove viene scritto l'output dell'agente
}

Restituisce il risultato dal subagente. L'output è discriminato sul campo status: "completed" per compiti terminati, "async_launched" per compiti in background, e "remote_launched" per compiti che Claude Code ha inviato a una sessione cloud remota, dove sessionUrl si collega a quella sessione e taskId l'identifica. Se Claude Code ha mantenuto il worktree isolato del subagente, worktreePath sulla variante completed è dove trovarlo, e worktreeBranch è il suo ramo quando Claude Code ha creato il worktree con git.

Sulla variante completed, resolvedModel nomina il modello su cui il subagente ha iniziato, che può differire dal model input richiesto quando availableModels o un altro override si applica. Questo campo richiede Claude Code v2.1.174 o successivo. Sulla variante async_launched, resolvedModel nomina il modello in uso quando l'agente si è spostato in background, quindi uno scambio che è accaduto prima del backgrounding si riflette lì. Il campo modelsUsed su entrambe le varianti elenca i modelli utilizzati in ordine, con ripetizioni consecutive compresse; è impostato solo quando il modello è stato scambiato durante l'esecuzione. modelsUsed e il comportamento di resolvedModel al momento del backgrounding richiedono Claude Code v2.1.212 o successivo.

Claude Code riempie usage e totalTokens dalla richiesta API finale del subagente, non dall'intera esecuzione. Quando presente, thinking_tokens sotto output_tokens_details in usage è il numero di token di output di quella richiesta che erano token di thinking. La chiave output_tokens_details richiede Python SDK v0.2.136 o successivo, che raggruppa Claude Code v2.1.228.

AskUserQuestion

Nome dello strumento: AskUserQuestion

Chiede all'utente domande di chiarimento durante l'esecuzione. Vedi Gestisci approvazioni e input dell'utente per i dettagli di utilizzo.

Input:

{
    "questions": [  # Domande da porre all'utente (1-4 domande)
        {
            "question": str,  # La domanda completa da porre all'utente
            "header": str,  # Etichetta molto breve visualizzata come chip/tag (max 12 caratteri)
            "options": [  # Le scelte disponibili (2-4 opzioni)
                {
                    "label": str,  # Testo visualizzato per questa opzione (1-5 parole)
                    "description": str,  # Spiegazione di cosa significa questa opzione
                    "preview": str | None,  # Contenuto di anteprima visualizzato quando l'opzione è focalizzata
                }
            ],
            "multiSelect": bool,  # Impostare su true per consentire selezioni multiple
        }
    ],
    "answers": dict[str, str] | None,
    # Risposte dell'utente popolate dal sistema di autorizzazione. Le risposte
    # multi-select sono una stringa unita da virgole delle etichette selezionate; un
    # elenco di etichette è accettato su input e coercizzato in quella forma
    "annotations": dict[str, dict] | None,
    # Annotazioni per domanda dall'utente, con chiave dal testo della domanda.
    # Ogni valore può contenere "preview" (il contenuto di anteprima dell'opzione selezionata)
    # e "notes" (note in testo libero sulla selezione)
    "metadata": dict | None,  # Metadati di analisi, come {"source": "remember"}; non visualizzati all'utente
}

Output:

{
    "questions": [  # Le domande che sono state poste
        {
            "question": str,
            "header": str,
            "options": [{"label": str, "description": str, "preview": str | None}],
            "multiSelect": bool,
        }
    ],
    "answers": dict[str, str],  # Mappa il testo della domanda alla stringa di risposta
    # Le risposte multi-select sono separate da virgole
    "response": str | None,
    # Risposta in testo libero digitata invece di rispondere alle domande; quando impostato,
    # Claude riceve "L'utente ha risposto: ..." al posto dell'elenco di risposte
    "annotations": dict[str, dict] | None,  # "preview" e "notes" per domanda dalle selezioni dell'utente
    "afkTimeoutMs": int | None,  # Impostato quando la finestra di dialogo si è auto-risolta dopo questo numero di millisecondi di inattività dell'utente; assente quando l'utente ha risposto
}

Bash

Nome dello strumento: Bash

Input:

{
    "command": str,  # Il comando da eseguire
    "timeout": int | None,  # Timeout opzionale in millisecondi (max 600000; i valori più alti vengono limitati al massimo)
    "description": str | None,  # Descrizione chiara e concisa (5-10 parole)
    "run_in_background": bool | None,  # Impostare su true per eseguire in background
}

Output:

{
    "stdout": str,  # L'output del comando; stdout e stderr arrivano uniti in questo unico flusso intercalato
    "stderr": str,  # Avvisi che lo strumento stesso aggiunge, non lo stderr del comando
    "interrupted": bool,  # Se il comando è stato interrotto
    "isImage": bool | None,  # Se stdout contiene dati di immagine
    "backgroundTaskId": str | None,  # ID dell'attività in background se il comando è in esecuzione in background
}

Monitor

Nome dello strumento: Monitor

Esegue una sorgente in background e fornisce ogni evento a Claude in modo che possa reagire senza polling: command esegue uno script e emette un evento per riga stdout, e ws apre un WebSocket ed emette un evento per frame di testo. Fornire esattamente uno tra command o ws.

Quando Monitor esegue un comando, segue le stesse regole di autorizzazione di Bash; un monitoraggio WebSocket richiede l'approvazione separatamente. L'origine ws richiede Claude Code v2.1.195 o successivo. Vedi il riferimento dello strumento Monitor per il comportamento e la disponibilità del provider.

Input:

{
    "command": str | None,  # Script shell; ogni riga stdout è un evento, exit termina il monitoraggio
    "ws": dict | None,  # Origine WebSocket: {"url": str, "protocols": list[str] | None}; ogni frame di testo è un evento
    "description": str,  # Breve descrizione mostrata nelle notifiche
    "timeout_ms": int | None,  # Scadenza in millisecondi (default 300000, max 3600000; la scadenza effettiva è al massimo 1800000)
}

Output:

{
    "taskId": str,  # ID dell'attività di monitoraggio in background
    "timeoutMs": int,  # La scadenza effettiva del monitoraggio in millisecondi
    "persistent": bool | None,  # False: ogni monitoraggio ha una scadenza
}

Edit

Nome dello strumento: Edit

Input:

{
    "file_path": str,  # Il percorso assoluto del file da modificare
    "old_string": str,  # Il testo da sostituire
    "new_string": str,  # Il testo con cui sostituirlo
    "replace_all": bool | None,  # Sostituisci tutte le occorrenze (default False)
}

Output:

{
    "message": str,  # Messaggio di conferma
    "replacements": int,  # Numero di sostituzioni effettuate
    "file_path": str,  # Percorso del file che è stato modificato
}

Read

Nome dello strumento: Read

Input:

{
    "file_path": str,  # Il percorso assoluto del file da leggere
    "offset": int | None,  # Il numero di riga da cui iniziare la lettura
    "limit": int | None,  # Il numero di righe da leggere
}

Output (File di testo):

{
    "content": str,  # Contenuto del file con numeri di riga
    "total_lines": int,  # Numero totale di righe nel file
    "lines_returned": int,  # Righe effettivamente restituite
}

Output (Immagini):

{
    "image": str,  # Dati dell'immagine codificati in Base64
    "mime_type": str,  # Tipo MIME dell'immagine
    "file_size": int,  # Dimensione del file in byte
}

Write

Nome dello strumento: Write

Input:

{
    "file_path": str,  # Il percorso assoluto del file da scrivere
    "content": str,  # Il contenuto da scrivere nel file
}

Output:

{
    "message": str,  # Messaggio di successo
    "bytes_written": int,  # Numero di byte scritti
    "file_path": str,  # Percorso del file che è stato scritto
}

Glob

Nome dello strumento: Glob

Input:

{
    "pattern": str,  # Il pattern glob per abbinare i file
    "path": str | None,  # La directory da cercare (default cwd)
}

Output:

{
    "matches": list[str],  # Array dei percorsi dei file corrispondenti
    "count": int,  # Numero di corrispondenze trovate
    "search_path": str,  # Directory di ricerca utilizzata
}

Grep

Nome dello strumento: Grep

Input:

{
    "pattern": str,  # Il pattern di espressione regolare
    "path": str | None,  # File o directory da cercare
    "glob": str | None,  # Pattern glob per filtrare i file
    "type": str | None,  # Tipo di file da cercare
    "output_mode": str | None,  # "content", "files_with_matches", o "count"
    "-i": bool | None,  # Ricerca senza distinzione maiuscole/minuscole
    "-n": bool | None,  # Mostra i numeri di riga
    "-B": int | None,  # Righe da mostrare prima di ogni corrispondenza
    "-A": int | None,  # Righe da mostrare dopo ogni corrispondenza
    "-C": int | None,  # Righe da mostrare prima e dopo
    "head_limit": int | None,  # Limita l'output alle prime N righe/voci
    "multiline": bool | None,  # Abilita la modalità multilinea
}

Output (modalità content):

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

Output (modalità files_with_matches):

{
    "files": list[str],  # File contenenti corrispondenze
    "count": int,  # Numero di file con corrispondenze
}

NotebookEdit

Nome dello strumento: NotebookEdit

Input:

{
    "notebook_path": str,  # Percorso assoluto del notebook Jupyter
    "cell_id": str | None,  # L'ID della cella da modificare
    "new_source": str,  # La nuova sorgente per la cella
    "cell_type": "code" | "markdown" | None,  # Il tipo della cella
    "edit_mode": "replace" | "insert" | "delete" | None,  # Tipo di operazione di modifica
}

Output:

{
    "message": str,  # Messaggio di successo
    "edit_type": "replaced" | "inserted" | "deleted",  # Tipo di modifica eseguita
    "cell_id": str | None,  # ID della cella interessata
    "total_cells": int,  # Numero totale di celle nel notebook dopo la modifica
}

WebFetch

Nome dello strumento: WebFetch

Input:

{
    "url": str,  # L'URL da cui recuperare il contenuto
    "prompt": str,  # Il prompt da eseguire sul contenuto recuperato
}

Output:

{
    "bytes": int,  # Dimensione del contenuto recuperato in byte
    "code": int,  # Codice di risposta HTTP
    "codeText": str,  # Testo del codice di risposta HTTP
    "result": str,  # Risultato elaborato dall'applicazione del prompt al contenuto
    "durationMs": int,  # Tempo per recuperare ed elaborare il contenuto, in millisecondi
    "url": str,  # URL che è stato recuperato
}

WebSearch

Nome dello strumento: WebSearch

Input:

{
    "query": str,  # La query di ricerca da utilizzare
    "allowed_domains": list[str] | None,  # Includi solo risultati da questi domini
    "blocked_domains": list[str] | None,  # Non includere mai risultati da questi domini
}

Output:

{
    "query": str,  # La query di ricerca
    "results": list[str | {"tool_use_id": str, "content": list[{"title": str, "url": str}]}],
    "durationSeconds": float,  # Durata della ricerca in secondi
}

TodoWrite

Nome dello strumento: TodoWrite

Input:

{
    "todos": [
        {
            "content": str,  # La descrizione del compito
            "status": "pending" | "in_progress" | "completed",  # Stato del compito
            "activeForm": str,  # Forma attiva della descrizione
        }
    ]
}

Output:

{
    "message": str,  # Messaggio di successo
    "stats": {"total": int, "pending": int, "in_progress": int, "completed": int},
}

TaskCreate

Nome dello strumento: TaskCreate

Input:

{
    "subject": str,  # Titolo breve del compito
    "description": str,  # Corpo dettagliato del compito
    "activeForm": str | None,  # Etichetta al tempo presente mostrata mentre in corso
    "metadata": dict | None,  # Metadati arbitrari del chiamante
}

Output:

{
    "task": {"id": str, "subject": str},  # Compito creato con ID assegnato
}

TaskUpdate

Nome dello strumento: TaskUpdate

Input:

{
    "taskId": str,  # ID del compito da modificare
    "status": Literal["pending", "in_progress", "completed", "deleted"] | None,
    "subject": str | None,
    "description": str | None,
    "activeForm": str | None,
    "addBlocks": list[str] | None,  # ID dei compiti che questo compito ora blocca
    "addBlockedBy": list[str] | None,  # ID dei compiti che ora bloccano questo compito
    "owner": str | None,
    "metadata": dict | None,
}

Output:

{
    "success": bool,
    "taskId": str,
    "updatedFields": list[str],  # Nomi dei campi che sono cambiati
    "error": str | None,
    "statusChange": {"from": str, "to": str} | None,
}

TaskGet

Nome dello strumento: TaskGet

Input:

{
    "taskId": str,  # ID del compito da leggere
}

Output:

{
    "task": {
        "id": str,
        "subject": str,
        "description": str,
        "status": Literal["pending", "in_progress", "completed"],
        "blocks": list[str],
        "blockedBy": list[str],
    } | None,  # None quando l'ID non viene trovato
}

TaskList

Nome dello strumento: TaskList

Input:

{}

Output:

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

TaskOutput

Rimosso in Claude Code v2.1.277. In precedenza recuperava l'output da un'attività in background o completata in esecuzione, con BashOutput accettato come alias; Claude legge il file di output di un'attività in background con Read invece.

Una voce disallowed_tools o una regola di negazione che ancora nomina uno dei due nomi viene ignorata senza un avviso.

TaskStop

Nome dello strumento: TaskStop. I nomi precedenti KillShell e KillBash sono ancora accettati come alias.

Input:

{
    "task_id": str | None,  # L'ID dell'attività in background da fermare
    "shell_id": str | None,  # Deprecato: usa task_id invece
}

Output:

{
    "message": str,  # Messaggio di stato sull'operazione
    "task_id": str,  # L'ID dell'attività che è stata fermata
    "task_type": str,  # Il tipo dell'attività che è stata fermata
    "command": str | None,  # Il comando o la descrizione dell'attività fermata
}

ExitPlanMode

Nome dello strumento: ExitPlanMode

Input:

{
    "plan": str  # Il piano da eseguire dall'utente per l'approvazione
}

Output:

{
    "message": str,  # Messaggio di conferma
    "approved": bool | None,  # Se l'utente ha approvato il piano
}

ListMcpResources

Nome dello strumento: ListMcpResourcesTool

Input:

{
    "server": str | None  # Nome del server opzionale per filtrare le risorse
}

Output:

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

ReadMcpResource

Nome dello strumento: ReadMcpResourceTool

Input:

{
    "server": str,  # Il nome del server MCP
    "uri": str,  # L'URI della risorsa da leggere
}

Output:

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

Costruire un'interfaccia di conversazione continua

L'esempio seguente mantiene un ClaudeSDKClient connesso tra i turni, in modo che Claude ricordi i messaggi precedenti. Digita new per disconnetterti e riconnetterti per una sessione nuova, oppure exit per terminare la conversazione.

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())

Gestione degli errori

L'esempio seguente racchiude una chiamata query() in gestori per quattro dei tipi di errore che l'SDK genera.

Questo esempio cattura ResultError, che richiede Python Agent SDK 0.2.140 o versioni successive.

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())

Configurazione della Sandbox

`SandboxSettings`

Configurazione per il comportamento della sandbox. Usala per abilitare il sandboxing dei comandi e configurare le restrizioni di rete a livello di programmazione.

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

Utilizzo di esempio

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`

Configurazione specifica della rete per la modalità sandbox. Queste impostazioni si applicano ai comandi Bash in sandbox quando enabled è True nella SandboxSettings padre. Non limitano lo strumento WebFetch, che utilizza invece regole di autorizzazione.

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`

Configurazione per ignorare violazioni specifiche della sandbox.

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

Fallback delle autorizzazioni per i comandi senza sandbox

Quando allowUnsandboxedCommands è abilitato, il modello può richiedere di eseguire comandi al di fuori della sandbox impostando dangerouslyDisableSandbox: True nell'input dello strumento. Queste richieste ricadono nel sistema di autorizzazioni esistente, il che significa che il tuo handler can_use_tool verrà invocato, permettendoti di implementare una logica di autorizzazione personalizzata.

Le tue voci excludedCommands invece bypassano la sandbox senza coinvolgimento del modello; sandbox.excludedCommands copre quando una voce si applica.

L'esempio seguente registra ogni richiesta senza sandbox e la nega a meno che la tua logica di autorizzazione non la consenta:

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())

Vedi anche

• Panoramica dell'SDK - Concetti generali dell'SDK
• Riferimento TypeScript SDK - Documentazione TypeScript SDK
• Strumenti personalizzati - Definisci strumenti MCP in-process per Claude da chiamare
• Riferimento CLI - Interfaccia della riga di comando
• Flussi di lavoro comuni - Guide passo dopo passo