541| `rewind_files(user_message_id)` | Ripristina i file al loro stato al messaggio utente specificato. Richiede `enable_file_checkpointing=True`. Vedi [File checkpointing](/docs/it/agent-sdk/file-checkpointing) |541| `rewind_files(user_message_id)` | Ripristina i file al loro stato al messaggio utente specificato. Richiede `enable_file_checkpointing=True`. Vedi [File checkpointing](/docs/it/agent-sdk/file-checkpointing) |
542| `get_mcp_status()` | Ottieni lo stato di tutti i server MCP configurati. Restituisce [`McpStatusResponse`](#mcpstatusresponse) |542| `get_mcp_status()` | Ottieni lo stato di tutti i server MCP configurati. Restituisce [`McpStatusResponse`](#mcpstatusresponse) |
543| `reconnect_mcp_server(server_name)` | Riprova a connettersi a un server MCP che ha fallito o è stato disconnesso |543| `reconnect_mcp_server(server_name)` | Riprova a connettersi a un server MCP che ha fallito o è stato disconnesso |
544| `toggle_mcp_server(server_name, enabled)` | Abilita o disabilita un server MCP a metà sessione. La disabilitazione rimuove i suoi strumenti |544| `toggle_mcp_server(server_name, enabled)` | Abilita o disabilita un server MCP a metà sessione. La disabilitazione di un server stdio, SSE o HTTP rimuove i suoi strumenti |
545| `stop_task(task_id)` | Interrompi un'attività in background in esecuzione. Un [`TaskNotificationMessage`](#tasknotificationmessage) con stato `"stopped"` segue nel flusso di messaggi |545| `stop_task(task_id)` | Interrompi un'attività in background in esecuzione. Un [`TaskNotificationMessage`](#tasknotificationmessage) con stato `"stopped"` segue nel flusso di messaggi |
546| `get_server_info()` | Ottieni le informazioni di inizializzazione del server, inclusi i comandi disponibili e gli stili di output |546| `get_server_info()` | Ottieni le informazioni di inizializzazione del server, inclusi i comandi disponibili e gli stili di output |
547| `disconnect()` | Disconnettiti da Claude |547| `disconnect()` | Disconnettiti da Claude |
616 Esempio - Input streaming con ClaudeSDKClient616 Esempio - Input streaming con ClaudeSDKClient
617</h4>617</h4>
618 618
619`query()` accetta anche un iterabile asincrono di dict di messaggi utente, quindi puoi assemblare il prompt al momento dell'invio o includere blocchi di contenuto come immagini. Claude Code inizia a rispondere al primo messaggio generato non appena arriva, senza aspettare che l'iterabile finisca, e `receive_response()` si ferma al `ResultMessage` che termina quella risposta. Metti tutto ciò che Claude dovrebbe leggere prima di rispondere in un messaggio, come fa questo generatore, e abbina ogni chiamata `query()` al suo proprio ciclo `receive_response()`.
620
619```python theme={null}621```python theme={null}
620import asyncio622import asyncio
621from claude_agent_sdk import ClaudeSDKClient623from claude_agent_sdk import ClaudeSDKClient
622 624
623 625
624async def message_stream():626async def message_stream():
625 """Generate messages dynamically."""627 """Assemble the prompt at send time and yield it as one user message."""
626 yield {628 readings = {"Temperature": "25°C", "Humidity": "60%"}
627 "type": "user",629 data = ", ".join(f"{name}: {value}" for name, value in readings.items())
628 "message": {"role": "user", "content": "Analyze the following data:"},
629 }
630 await asyncio.sleep(0.5)
631 yield {
632 "type": "user",
633 "message": {"role": "user", "content": "Temperature: 25°C, Humidity: 60%"},
634 }
635 await asyncio.sleep(0.5)
636 yield {630 yield {
637 "type": "user",631 "type": "user",
638 "message": {"role": "user", "content": "What patterns do you see?"},632 "message": {
633 "role": "user",
634 "content": f"Analyze the following sensor data and describe any patterns you see: {data}",
635 },
639 }636 }
640 637
641 638
2712 2709
2713Documentazione 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.2710Documentazione 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.
2714 2711
2712Ogni output mostrato è il valore che leggete da [`UserMessage.tool_use_result`](#usermessage) per quello strumento. I nomi delle chiavi appaiono esattamente come Claude Code li emette. Una chiave annotata `| None` con un commento "presente quando" o "opzionale" viene omessa quando non si applica.
2713
2715<h3 id="agent">2714<h3 id="agent">
2716 Agent2715 Agent
2717</h3>2716</h3>
2805```python theme={null}2804```python theme={null}
2806{2805{
2807 "status": "remote_launched",2806 "status": "remote_launched",
2808 "taskId": str, # ID dell'attività remota2807 "taskId": str, # ID dell'attività inviata
2809 "sessionUrl": str, # Collegamento alla sessione cloud remota2808 "sessionUrl": str, # Collegamento alla sessione cloud
2810 "description": str, # La descrizione del compito2809 "description": str, # La descrizione del compito
2811 "prompt": str, # Il prompt che l'agente esegue2810 "prompt": str, # Il prompt che l'agente esegue
2812 "outputFile": str, # Percorso del file dove viene scritto l'output dell'agente2811 "outputFile": str, # Percorso del file dove viene scritto l'output dell'agente
2813}2812}
2814```2813```
2815 2814
2816Restituisce 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](/docs/it/worktrees#isolate-subagents-with-worktrees), `worktreePath` sulla variante `completed` è dove trovarlo, e `worktreeBranch` è il suo ramo quando Claude Code ha creato il worktree con git.2815Restituisce 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, dove `sessionUrl` si collega a quella sessione e `taskId` l'identifica. Se Claude Code [ha mantenuto il worktree isolato del subagente](/docs/it/worktrees#isolate-subagents-with-worktrees), `worktreePath` sulla variante `completed` è dove trovarlo, e `worktreeBranch` è il suo ramo quando Claude Code ha creato il worktree con git.
2817 2816
2818Sulla variante `completed`, `resolvedModel` nomina il modello su cui il subagente ha iniziato, che può differire dal `model` input richiesto quando [`availableModels`](/docs/it/model-config#restrict-model-selection) 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.2817Sulla variante `completed`, `resolvedModel` nomina il modello su cui il subagente ha iniziato, che può differire dal `model` input richiesto quando [`availableModels`](/docs/it/model-config#restrict-model-selection) 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.
2819 2818
2885 2884
2886**Nome dello strumento:** `Bash`2885**Nome dello strumento:** `Bash`
2887 2886
2888Per ciò che imposta il limite massimo in primo piano, vedi [Timeout e limiti di output](/docs/it/tools-reference#timeout-and-output-limits). Per il limite di tempo in background, vedi [Comandi in background](/docs/it/tools-reference#background-commands).2887Per ciò che imposta il limite massimo in primo piano, vedi [Timeout e limiti di output](/docs/it/tools-reference#timeout-and-output-limits). Per il limite di tempo in background, vedi [Limite di tempo per i comandi in background](/docs/it/tools-reference#time-limit-for-background-commands).
2889 2888
2890**Input:**2889**Input:**
2891 2890
2962 2961
2963```python theme={null}2962```python theme={null}
2964{2963{
2965 "message": str, # Messaggio di conferma2964 "filePath": str, # Il file che è stato modificato
2966 "replacements": int, # Numero di sostituzioni effettuate2965 "oldString": str, # Il testo che è stato sostituito
2967 "file_path": str, # Percorso del file che è stato modificato2966 "newString": str, # Il testo che lo ha sostituito
2967 "originalFile": str | None, # Contenuto del file prima della modifica
2968 "structuredPatch": [ # Diff hunks per la modifica
2969 {
2970 "oldStart": int,
2971 "oldLines": int,
2972 "newStart": int,
2973 "newLines": int,
2974 "lines": list[str],
2975 }
2976 ],
2977 "userModified": bool, # Se l'utente ha modificato la modifica proposta prima di accettarla
2978 "replaceAll": bool, # Se tutte le occorrenze sono state sostituite
2979 "gitDiff": { # Riepilogo git diff opzionale per il file
2980 "filename": str,
2981 "status": "modified" | "added",
2982 "additions": int,
2983 "deletions": int,
2984 "changes": int,
2985 "patch": str,
2986 "repository": str | None, # Proprietario/repo GitHub quando disponibile
2987 } | None,
2968}2988}
2969```2989```
2970 2990
2984}3004}
2985```3005```
2986 3006
2987**Output (File di testo):**3007L'output assume una delle seguenti forme a seconda di ciò che Claude ha letto. Controllare la chiave `type` per distinguerle.
3008
3009**Output (type: `"text"`):**
2988 3010
2989```python theme={null}3011```python theme={null}
2990{3012{
2991 "content": str, # Contenuto del file con numeri di riga3013 "type": "text",
2992 "total_lines": int, # Numero totale di righe nel file3014 "file": {
2993 "lines_returned": int, # Righe effettivamente restituite3015 "filePath": str, # Il file che è stato letto
3016 "content": str, # Il contenuto restituito
3017 "numLines": int, # Numero di righe nel contenuto restituito
3018 "startLine": int, # Numero di riga in cui inizia il contenuto
3019 "totalLines": int, # Numero totale di righe nel file
3020 "truncatedByTokenCap": bool | None, # Presente e True quando una lettura dell'intero file ha superato il limite di token e il contenuto è la prima pagina
3021 },
2994}3022}
2995```3023```
2996 3024
2997**Output (Immagini):**3025**Output (type: `"image"`):**
2998 3026
2999```python theme={null}3027```python theme={null}
3000{3028{
3001 "image": str, # Dati dell'immagine codificati in Base643029 "type": "image",
3002 "mime_type": str, # Tipo MIME dell'immagine3030 "file": {
3003 "file_size": int, # Dimensione del file in byte3031 "base64": str, # Dati dell'immagine codificati in Base64
3032 "type": "image/jpeg" | "image/png" | "image/gif" | "image/webp", # Tipo MIME dell'immagine
3033 "originalSize": int, # Dimensione del file originale in byte
3034 "dimensions": { # Informazioni di dimensionamento opzionali per la mappatura delle coordinate
3035 "originalWidth": int | None, # Opzionale; larghezza originale in pixel
3036 "originalHeight": int | None, # Opzionale; altezza originale in pixel
3037 "displayWidth": int | None, # Opzionale; larghezza dopo il ridimensionamento
3038 "displayHeight": int | None, # Opzionale; altezza dopo il ridimensionamento
3039 } | None,
3040 },
3041}
3042```
3043
3044**Output (type: `"notebook"`):**
3045
3046```python theme={null}
3047{
3048 "type": "notebook",
3049 "file": {
3050 "filePath": str, # Il notebook che è stato letto
3051 "cells": list, # Celle del notebook
3052 },
3053}
3054```
3055
3056**Output (type: `"pdf"`):**
3057
3058```python theme={null}
3059{
3060 "type": "pdf",
3061 "file": {
3062 "filePath": str, # Il PDF che è stato letto
3063 "base64": str, # Dati PDF codificati in Base64
3064 "originalSize": int, # Dimensione del file in byte
3065 },
3066}
3067```
3068
3069**Output (type: `"parts"`):**
3070
3071```python theme={null}
3072{
3073 "type": "parts",
3074 "file": {
3075 "filePath": str, # Il PDF che è stato letto
3076 "originalSize": int, # Dimensione del file in byte
3077 "count": int, # Numero di pagine estratte come immagini
3078 "outputDir": str, # Directory contenente le immagini delle pagine estratte
3079 },
3080 "firstPage": int | None, # Numero di pagina del documento opzionale della prima pagina estratta
3081}
3082```
3083
3084**Output (type: `"file_unchanged"`):**
3085
3086```python theme={null}
3087{
3088 "type": "file_unchanged", # Il file è invariato da quando Claude l'ha letto l'ultima volta in questa sessione, quindi il contenuto non viene ripetuto
3089 "file": {
3090 "filePath": str,
3091 },
3092 "source": "seeded" | None, # Presente quando la copia precedente proveniva da un file CLAUDE.md o memory caricato all'avvio piuttosto che da una chiamata Read
3004}3093}
3005```3094```
3006 3095
3023 3112
3024```python theme={null}3113```python theme={null}
3025{3114{
3026 "message": str, # Messaggio di successo3115 "type": "create" | "update", # Se la scrittura ha creato un nuovo file o sovrascritto uno esistente
3027 "bytes_written": int, # Numero di byte scritti3116 "filePath": str, # Il file che è stato scritto
3028 "file_path": str, # Percorso del file che è stato scritto3117 "content": str, # Il contenuto che è stato scritto
3118 "structuredPatch": [ # Diff hunks; vuoto per un nuovo file, quando nulla è cambiato, o quando Claude Code ha saltato il diff
3119 {
3120 "oldStart": int,
3121 "oldLines": int,
3122 "newStart": int,
3123 "newLines": int,
3124 "lines": list[str],
3125 }
3126 ],
3127 "originalFile": str | None, # Contenuto precedente; None per un nuovo file o quando il contenuto precedente era troppo grande da includere
3128 "gitDiff": { # Riepilogo git diff opzionale per il file
3129 "filename": str,
3130 "status": "modified" | "added",
3131 "additions": int,
3132 "deletions": int,
3133 "changes": int,
3134 "patch": str,
3135 "repository": str | None, # Proprietario/repo GitHub quando disponibile
3136 } | None,
3137 "userModified": bool | None, # Opzionale; se l'utente ha modificato il contenuto proposto prima di accettarlo
3029}3138}
3030```3139```
3031 3140
3048 3157
3049```python theme={null}3158```python theme={null}
3050{3159{
3051 "matches": list[str], # Array dei percorsi dei file corrispondenti3160 "durationMs": int, # Tempo impiegato per eseguire la ricerca, in millisecondi
3052 "count": int, # Numero di corrispondenze trovate3161 "numFiles": int, # Numero di percorsi restituiti, dopo qualsiasi troncamento
3053 "search_path": str, # Directory di ricerca utilizzata3162 "filenames": list[str], # Percorsi dei file corrispondenti
3163 "truncated": bool, # Se i risultati sono stati troncati al limite di 100 file
3164 "totalMatches": int | None, # Numero totale opzionale di file corrispondenti prima del troncamento; un limite inferiore quando countIsComplete è False
3165 "countIsComplete": bool | None, # Opzionale; se totalMatches è esatto
3054}3166}
3055```3167```
3056 3168
3169`totalMatches` e `countIsComplete` richiedono Claude Code v2.1.191 o successivo.
3170
3057<h3 id="grep">3171<h3 id="grep">
3058 Grep3172 Grep
3059</h3>3173</h3>
3074 "-B": int | None, # Righe da mostrare prima di ogni corrispondenza3188 "-B": int | None, # Righe da mostrare prima di ogni corrispondenza
3075 "-A": int | None, # Righe da mostrare dopo ogni corrispondenza3189 "-A": int | None, # Righe da mostrare dopo ogni corrispondenza
3076 "-C": int | None, # Righe da mostrare prima e dopo3190 "-C": int | None, # Righe da mostrare prima e dopo
3191 "context": int | None, # Righe da mostrare prima e dopo; -C è un alias
3192 "-o": bool | None, # Stampa solo le parti corrispondenti di ogni riga
3077 "head_limit": int | None, # Limita l'output alle prime N righe/voci3193 "head_limit": int | None, # Limita l'output alle prime N righe/voci
3194 "offset": int | None, # Salta le prime N righe/voci prima di applicare head_limit
3078 "multiline": bool | None, # Abilita la modalità multilinea3195 "multiline": bool | None, # Abilita la modalità multilinea
3079}3196}
3080```3197```
3081 3198
3082**Output (modalità content):**3199**Output:**
3083 3200
3084```python theme={null}3201```python theme={null}
3085{3202{
3086 "matches": [3203 "mode": "content" | "files_with_matches" | "count" | None, # La modalità di output che è stata utilizzata
3087 {3204 "numFiles": int, # Numero di file nel risultato; sempre 0 in modalità content
3088 "file": str,3205 "filenames": list[str], # File corrispondenti in modalità files_with_matches; vuoto nelle altre modalità
3089 "line_number": int | None,3206 "content": str | None, # Righe corrispondenti in modalità content, o conteggi per file in modalità count
3090 "line": str,3207 "numLines": int | None, # Numero di righe nel contenuto, presente in modalità content
3091 "before_context": list[str] | None,3208 "numMatches": int | None, # Conteggio totale delle corrispondenze, presente in modalità count
3092 "after_context": list[str] | None,3209 "totalFiles": int | None, # Totale opzionale prima di head_limit e offset, in modalità files_with_matches
3093 }3210 "totalLines": int | None, # Totale opzionale prima di head_limit e offset, in modalità content
3094 ],3211 "appliedLimit": int | None, # Presente quando head_limit ha troncato il risultato
3095 "total_matches": int,3212 "appliedOffset": int | None, # Presente quando è stato applicato un offset
3096}3213}
3097```3214```
3098 3215
3099**Output (modalità files\_with\_matches):**3216Grep restituisce questa forma di dict in ogni modalità di output. Quali chiavi opzionali sono presenti dipende da `output_mode`.
3100 3217
3101```python theme={null}3218`totalFiles` richiede Claude Code v2.1.208 o successivo. `totalLines` richiede Claude Code v2.1.210 o successivo.
3102{
3103 "files": list[str], # File contenenti corrispondenze
3104 "count": int, # Numero di file con corrispondenze
3105}
3106```
3107 3219
3108<h3 id="notebookedit">3220<h3 id="notebookedit">
3109 NotebookEdit3221 NotebookEdit
3127 3239
3128```python theme={null}3240```python theme={null}
3129{3241{
3130 "message": str, # Messaggio di successo3242 "new_source": str, # La sorgente scritta nella cella
3131 "edit_type": "replaced" | "inserted" | "deleted", # Tipo di modifica eseguita3243 "old_source": str | None, # Sorgente della cella precedente, presente per replace e delete
3132 "cell_id": str | None, # ID della cella interessata3244 "cell_id": str | None, # ID della cella modificata, quando disponibile
3133 "total_cells": int, # Numero totale di celle nel notebook dopo la modifica3245 "cell_type": "code" | "markdown", # Il tipo della cella
3246 "language": str, # Il linguaggio di programmazione del notebook
3247 "edit_mode": str, # La modalità di modifica che è stata utilizzata
3248 "error": str | None, # Messaggio di errore quando l'operazione non è riuscita
3249 "notebook_path": str, # Il file del notebook
3250 "original_file": str, # Contenuto del notebook prima della modifica
3251 "updated_file": str, # Contenuto del notebook dopo la modifica
3134}3252}
3135```3253```
3136 3254
3228 3346
3229```python theme={null}3347```python theme={null}
3230{3348{
3231 "message": str, # Messaggio di successo3349 "oldTodos": [ # L'elenco todo prima dell'aggiornamento
3232 "stats": {"total": int, "pending": int, "in_progress": int, "completed": int},3350 {
3351 "content": str,
3352 "status": "pending" | "in_progress" | "completed",
3353 "activeForm": str,
3354 }
3355 ],
3356 "newTodos": [ # L'elenco todo dopo l'aggiornamento
3357 {
3358 "content": str,
3359 "status": "pending" | "in_progress" | "completed",
3360 "activeForm": str,
3361 }
3362 ],
3233}3363}
3234```3364```
3235 3365
3401 3531
3402```python theme={null}3532```python theme={null}
3403{3533{
3404 "message": str, # Messaggio di conferma3534 "plan": str | None, # Il piano che è stato presentato all'utente
3405 "approved": bool | None, # Se l'utente ha approvato il piano3535 "isAgent": bool, # True quando un subagente ha chiamato lo strumento
3536 "filePath": str | None, # Presente quando il piano è stato salvato in un file
3537 "hasTaskTool": bool | None, # Opzionale; se lo strumento Agent è disponibile nel contesto corrente
3538 "planWasEdited": bool | None, # Presente e True quando l'utente ha modificato il piano prima di approvarlo
3539 "awaitingLeaderApproval": bool | None, # Presente e True quando un compagno di squadra ha inviato il piano al team lead per l'approvazione
3540 "requestId": str | None, # ID opzionale di quella richiesta di approvazione
3406}3541}
3407```3542```
3408 3543
3420}3555}
3421```3556```
3422 3557
3558Il risultato è un elenco piuttosto che un dict, quindi `tool_use_result` contiene un `list` per questo strumento.
3559
3423**Output:**3560**Output:**
3424 3561
3425```python theme={null}3562```python theme={null}
3426{3563[ # Una voce per risorsa
3427 "resources": [
3428 {3564 {
3429 "uri": str,3565 "uri": str, # URI della risorsa
3430 "name": str,3566 "name": str, # Nome della risorsa
3431 "description": str | None,3567 "mimeType": str | None, # Tipo MIME opzionale
3432 "mimeType": str | None,3568 "description": str | None, # Descrizione opzionale
3433 "server": str,3569 "server": str, # Server che fornisce questa risorsa
3434 }3570 }
3435 ],3571]
3436 "total": int,
3437}
3438```3572```
3439 3573
3440<h3 id="readmcpresource">3574<h3 id="readmcpresource">
3457```python theme={null}3591```python theme={null}
3458{3592{
3459 "contents": [3593 "contents": [
3460 {"uri": str, "mimeType": str | None, "text": str | None, "blob": str | None}3594 {
3595 "uri": str, # URI della risorsa
3596 "mimeType": str | None, # Tipo MIME opzionale
3597 "text": str | None, # Contenuto di testo, o una nota sul contenuto binario
3598 "blobSavedTo": str | None, # Presente quando Claude Code ha salvato il contenuto binario su disco; percorso del file salvato
3599 }
3461 ],3600 ],
3462 "server": str,3601 "error": str | None, # Presente quando il server non poteva leggere la risorsa
3463}3602}
3464```3603```
3465 3604
