1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# Riferimento SDK Agent - Python
6
7> Riferimento API completo per Python Agent SDK, incluse tutte le funzioni, i tipi e le classi.
8
9## Installazione
10
11```bash theme={null}
12pip install claude-agent-sdk
13```
14
15## Scelta tra `query()` e `ClaudeSDKClient`
16
17Python SDK fornisce due modi per interagire con Claude Code:
18
19### Confronto rapido
20
21| Funzionalità | `query()` | `ClaudeSDKClient` |
22| :--------------------------- | :--------------------------------- | :------------------------------- |
23| **Sessione** | Crea una nuova sessione ogni volta | Riutilizza la stessa sessione |
24| **Conversazione** | Singolo scambio | Più scambi nello stesso contesto |
25| **Connessione** | Gestita automaticamente | Controllo manuale |
26| **Input Streaming** | ✅ Supportato | ✅ Supportato |
27| **Interruzioni** | ❌ Non supportato | ✅ Supportato |
28| **Hooks** | ✅ Supportato | ✅ Supportato |
29| **Strumenti personalizzati** | ✅ Supportato | ✅ Supportato |
30| **Continua chat** | ❌ Nuova sessione ogni volta | ✅ Mantiene la conversazione |
31| **Caso d'uso** | Attività una tantum | Conversazioni continue |
32
33### Quando usare `query()` (nuova sessione ogni volta)
34
35**Migliore per:**
36
37* Domande una tantum dove non hai bisogno della cronologia della conversazione
38* Attività indipendenti che non richiedono contesto da scambi precedenti
39* Script di automazione semplici
40* Quando vuoi un nuovo inizio ogni volta
41
42### Quando usare `ClaudeSDKClient` (conversazione continua)
43
44**Migliore per:**
45
46* **Continuare conversazioni** - Quando hai bisogno che Claude ricordi il contesto
47* **Domande di follow-up** - Costruire su risposte precedenti
48* **Applicazioni interattive** - Interfacce chat, REPL
49* **Logica guidata dalla risposta** - Quando l'azione successiva dipende dalla risposta di Claude
50* **Controllo della sessione** - Gestire il ciclo di vita della conversazione in modo esplicito
51
52## Funzioni
53
54### `query()`
55
56Crea una nuova sessione per ogni interazione con Claude Code. Restituisce un iteratore asincrono che produce messaggi man mano che arrivano. Ogni chiamata a `query()` inizia da zero senza memoria di interazioni precedenti.
57
58```python theme={null}
59async def query(
60 *,
61 prompt: str | AsyncIterable[dict[str, Any]],
62 options: ClaudeAgentOptions | None = None,
63 transport: Transport | None = None
64) -> AsyncIterator[Message]
65```
66
67#### Parametri
68
69| Parametro | Tipo | Descrizione |
70| :---------- | :--------------------------- | :------------------------------------------------------------------------------------------------ |
71| `prompt` | `str \| AsyncIterable[dict]` | Il prompt di input come stringa o iterabile asincrono per la modalità streaming |
72| `options` | `ClaudeAgentOptions \| None` | Oggetto di configurazione opzionale (per impostazione predefinita `ClaudeAgentOptions()` se None) |
73| `transport` | `Transport \| None` | Trasporto personalizzato opzionale per comunicare con il processo CLI |
74
75#### Restituisce
76
77Restituisce un `AsyncIterator[Message]` che produce messaggi dalla conversazione.
78
79#### Esempio - Con opzioni
80
81```python theme={null}
82import asyncio
83from claude_agent_sdk import query, ClaudeAgentOptions
84
85
86async def main():
87 options = ClaudeAgentOptions(
88 system_prompt="You are an expert Python developer",
89 permission_mode="acceptEdits",
90 cwd="/home/user/project",
91 )
92
93 async for message in query(prompt="Create a Python web server", options=options):
94 print(message)
95
96
97asyncio.run(main())
98```
99
100### `tool()`
101
102Decoratore per definire strumenti MCP con sicurezza dei tipi.
103
104```python theme={null}
105def tool(
106 name: str,
107 description: str,
108 input_schema: type | dict[str, Any],
109 annotations: ToolAnnotations | None = None
110) -> Callable[[Callable[[Any], Awaitable[dict[str, Any]]]], SdkMcpTool[Any]]
111```
112
113#### Parametri
114
115| Parametro | Tipo | Descrizione |
116| :------------- | :----------------------------------------------- | :---------------------------------------------------------------------------------------------- |
117| `name` | `str` | Identificatore univoco per lo strumento |
118| `description` | `str` | Descrizione leggibile di cosa fa lo strumento |
119| `input_schema` | `type \| dict[str, Any]` | Schema che definisce i parametri di input dello strumento (vedi sotto) |
120| `annotations` | [`ToolAnnotations`](#tool-annotations)` \| None` | Annotazioni MCP dello strumento opzionali che forniscono suggerimenti comportamentali ai client |
121
122#### Opzioni dello schema di input
123
1241. **Mappatura di tipo semplice** (consigliato):
125
126 ```python theme={null}
127 {"text": str, "count": int, "enabled": bool}
128 ```
129
1302. **Formato JSON Schema** (per validazione complessa):
131 ```python theme={null}
132 {
133 "type": "object",
134 "properties": {
135 "text": {"type": "string"},
136 "count": {"type": "integer", "minimum": 0},
137 },
138 "required": ["text"],
139 }
140 ```
141
142#### Restituisce
143
144Una funzione decoratore che avvolge l'implementazione dello strumento e restituisce un'istanza `SdkMcpTool`.
145
146#### Esempio
147
148```python theme={null}
149from claude_agent_sdk import tool
150from typing import Any
151
152
153@tool("greet", "Greet a user", {"name": str})
154async def greet(args: dict[str, Any]) -> dict[str, Any]:
155 return {"content": [{"type": "text", "text": f"Hello, {args['name']}!"}]}
156```
157
158#### `ToolAnnotations`
159
160Riesportato da `mcp.types` (disponibile anche come `from claude_agent_sdk import ToolAnnotations`). Tutti i campi sono suggerimenti opzionali; i client non dovrebbero fare affidamento su di essi per decisioni di sicurezza.
161
162| Campo | Tipo | Predefinito | Descrizione |
163| :---------------- | :------------- | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
164| `title` | `str \| None` | `None` | Titolo leggibile per lo strumento |
165| `readOnlyHint` | `bool \| None` | `False` | Se `True`, lo strumento non modifica il suo ambiente |
166| `destructiveHint` | `bool \| None` | `True` | Se `True`, lo strumento può eseguire aggiornamenti distruttivi (significativo solo quando `readOnlyHint` è `False`) |
167| `idempotentHint` | `bool \| None` | `False` | Se `True`, le chiamate ripetute con gli stessi argomenti non hanno effetto aggiuntivo (significativo solo quando `readOnlyHint` è `False`) |
168| `openWorldHint` | `bool \| None` | `True` | Se `True`, lo strumento interagisce con entità esterne (ad esempio, ricerca web). Se `False`, il dominio dello strumento è chiuso (ad esempio, uno strumento di memoria) |
169
170```python theme={null}
171from claude_agent_sdk import tool, ToolAnnotations
172from typing import Any
173
174
175@tool(
176 "search",
177 "Search the web",
178 {"query": str},
179 annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
180)
181async def search(args: dict[str, Any]) -> dict[str, Any]:
182 return {"content": [{"type": "text", "text": f"Results for: {args['query']}"}]}
183```
184
185### `create_sdk_mcp_server()`
186
187Crea un server MCP in-process che viene eseguito all'interno della tua applicazione Python.
188
189```python theme={null}
190def create_sdk_mcp_server(
191 name: str,
192 version: str = "1.0.0",
193 tools: list[SdkMcpTool[Any]] | None = None
194) -> McpSdkServerConfig
195```
196
197#### Parametri
198
199| Parametro | Tipo | Predefinito | Descrizione |
200| :-------- | :------------------------------ | :---------- | :--------------------------------------------------------------- |
201| `name` | `str` | - | Identificatore univoco per il server |
202| `version` | `str` | `"1.0.0"` | Stringa della versione del server |
203| `tools` | `list[SdkMcpTool[Any]] \| None` | `None` | Elenco di funzioni di strumento create con il decoratore `@tool` |
204
205#### Restituisce
206
207Restituisce un oggetto `McpSdkServerConfig` che può essere passato a `ClaudeAgentOptions.mcp_servers`.
208
209#### Esempio
210
211```python theme={null}
212from claude_agent_sdk import tool, create_sdk_mcp_server
213
214
215@tool("add", "Add two numbers", {"a": float, "b": float})
216async def add(args):
217 return {"content": [{"type": "text", "text": f"Sum: {args['a'] + args['b']}"}]}
218
219
220@tool("multiply", "Multiply two numbers", {"a": float, "b": float})
221async def multiply(args):
222 return {"content": [{"type": "text", "text": f"Product: {args['a'] * args['b']}"}]}
223
224
225calculator = create_sdk_mcp_server(
226 name="calculator",
227 version="2.0.0",
228 tools=[add, multiply], # Pass decorated functions
229)
230
231# Use with Claude
232options = ClaudeAgentOptions(
233 mcp_servers={"calc": calculator},
234 allowed_tools=["mcp__calc__add", "mcp__calc__multiply"],
235)
236```
237
238### `list_sessions()`
239
240Elenca le sessioni passate con metadati. Filtra per directory di progetto o elenca le sessioni in tutti i progetti. Sincrono; restituisce immediatamente.
241
242```python theme={null}
243def list_sessions(
244 directory: str | None = None,
245 limit: int | None = None,
246 include_worktrees: bool = True
247) -> list[SDKSessionInfo]
248```
249
250#### Parametri
251
252| Parametro | Tipo | Predefinito | Descrizione |
253| :------------------ | :------------ | :---------- | :------------------------------------------------------------------------------------------------------------- |
254| `directory` | `str \| None` | `None` | Directory per cui elencare le sessioni. Se omesso, restituisce le sessioni in tutti i progetti |
255| `limit` | `int \| None` | `None` | Numero massimo di sessioni da restituire |
256| `include_worktrees` | `bool` | `True` | Quando `directory` si trova all'interno di un repository git, includi le sessioni da tutti i percorsi worktree |
257
258#### Tipo di ritorno: `SDKSessionInfo`
259
260| Proprietà | Tipo | Descrizione |
261| :-------------- | :------------ | :-------------------------------------------------------------------------------------------------- |
262| `session_id` | `str` | Identificatore di sessione univoco |
263| `summary` | `str` | Titolo di visualizzazione: titolo personalizzato, riepilogo generato automaticamente o primo prompt |
264| `last_modified` | `int` | Ora dell'ultima modifica in millisecondi dall'epoca |
265| `file_size` | `int \| None` | Dimensione del file di sessione in byte (`None` per backend di archiviazione remota) |
266| `custom_title` | `str \| None` | Titolo della sessione impostato dall'utente |
267| `first_prompt` | `str \| None` | Primo prompt utente significativo nella sessione |
268| `git_branch` | `str \| None` | Ramo Git alla fine della sessione |
269| `cwd` | `str \| None` | Directory di lavoro per la sessione |
270| `tag` | `str \| None` | Tag della sessione impostato dall'utente (vedi [`tag_session()`](#tag-session)) |
271| `created_at` | `int \| None` | Ora di creazione della sessione in millisecondi dall'epoca |
272
273#### Esempio
274
275Stampa 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.
276
277```python theme={null}
278from claude_agent_sdk import list_sessions
279
280for session in list_sessions(directory="/path/to/project", limit=10):
281 print(f"{session.summary} ({session.session_id})")
282```
283
284### `get_session_messages()`
285
286Recupera i messaggi da una sessione passata. Sincrono; restituisce immediatamente.
287
288```python theme={null}
289def get_session_messages(
290 session_id: str,
291 directory: str | None = None,
292 limit: int | None = None,
293 offset: int = 0
294) -> list[SessionMessage]
295```
296
297#### Parametri
298
299| Parametro | Tipo | Predefinito | Descrizione |
300| :----------- | :------------ | :----------- | :-------------------------------------------------------------------------- |
301| `session_id` | `str` | obbligatorio | L'ID della sessione per cui recuperare i messaggi |
302| `directory` | `str \| None` | `None` | Directory del progetto in cui cercare. Se omesso, cerca in tutti i progetti |
303| `limit` | `int \| None` | `None` | Numero massimo di messaggi da restituire |
304| `offset` | `int` | `0` | Numero di messaggi da saltare dall'inizio |
305
306#### Tipo di ritorno: `SessionMessage`
307
308| Proprietà | Tipo | Descrizione |
309| :------------------- | :----------------------------- | :---------------------------------- |
310| `type` | `Literal["user", "assistant"]` | Ruolo del messaggio |
311| `uuid` | `str` | Identificatore di messaggio univoco |
312| `session_id` | `str` | Identificatore di sessione |
313| `message` | `Any` | Contenuto del messaggio grezzo |
314| `parent_tool_use_id` | `None` | Riservato per uso futuro |
315
316#### Esempio
317
318```python theme={null}
319from claude_agent_sdk import list_sessions, get_session_messages
320
321sessions = list_sessions(limit=1)
322if sessions:
323 messages = get_session_messages(sessions[0].session_id)
324 for msg in messages:
325 print(f"[{msg.type}] {msg.uuid}")
326```
327
328### `get_session_info()`
329
330Legge i metadati per una singola sessione per ID senza scansionare la directory del progetto completo. Sincrono; restituisce immediatamente.
331
332```python theme={null}
333def get_session_info(
334 session_id: str,
335 directory: str | None = None,
336) -> SDKSessionInfo | None
337```
338
339#### Parametri
340
341| Parametro | Tipo | Predefinito | Descrizione |
342| :----------- | :------------ | :----------- | :----------------------------------------------------------------------------------------- |
343| `session_id` | `str` | obbligatorio | UUID della sessione da cercare |
344| `directory` | `str \| None` | `None` | Percorso della directory del progetto. Se omesso, cerca in tutte le directory del progetto |
345
346Restituisce [`SDKSessionInfo`](#return-type-sdk-session-info), o `None` se la sessione non viene trovata.
347
348#### Esempio
349
350Cerca i metadati di una singola sessione senza scansionare la directory del progetto. Utile quando hai già un ID di sessione da un'esecuzione precedente.
351
352```python theme={null}
353from claude_agent_sdk import get_session_info
354
355info = get_session_info("550e8400-e29b-41d4-a716-446655440000")
356if info:
357 print(f"{info.summary} (branch: {info.git_branch}, tag: {info.tag})")
358```
359
360### `rename_session()`
361
362Rinomina una sessione aggiungendo una voce di titolo personalizzato. Le chiamate ripetute sono sicure; il titolo più recente vince. Sincrono.
363
364```python theme={null}
365def rename_session(
366 session_id: str,
367 title: str,
368 directory: str | None = None,
369) -> None
370```
371
372#### Parametri
373
374| Parametro | Tipo | Predefinito | Descrizione |
375| :----------- | :------------ | :----------- | :----------------------------------------------------------------------------------------- |
376| `session_id` | `str` | obbligatorio | UUID della sessione da rinominare |
377| `title` | `str` | obbligatorio | Nuovo titolo. Deve essere non vuoto dopo la rimozione degli spazi bianchi |
378| `directory` | `str \| None` | `None` | Percorso della directory del progetto. Se omesso, cerca in tutte le directory del progetto |
379
380Genera `ValueError` se `session_id` non è un UUID valido o `title` è vuoto; `FileNotFoundError` se la sessione non può essere trovata.
381
382#### Esempio
383
384Rinomina la sessione più recente in modo che sia più facile da trovare in seguito. Il nuovo titolo appare in [`SDKSessionInfo.custom_title`](#return-type-sdk-session-info) nelle letture successive.
385
386```python theme={null}
387from claude_agent_sdk import list_sessions, rename_session
388
389sessions = list_sessions(directory="/path/to/project", limit=1)
390if sessions:
391 rename_session(sessions[0].session_id, "Refactor auth module")
392```
393
394### `tag_session()`
395
396Etichetta una sessione. Passa `None` per cancellare l'etichetta. Le chiamate ripetute sono sicure; l'etichetta più recente vince. Sincrono.
397
398```python theme={null}
399def tag_session(
400 session_id: str,
401 tag: str | None,
402 directory: str | None = None,
403) -> None
404```
405
406#### Parametri
407
408| Parametro | Tipo | Predefinito | Descrizione |
409| :----------- | :------------ | :----------- | :------------------------------------------------------------------------------------------ |
410| `session_id` | `str` | obbligatorio | UUID della sessione da etichettare |
411| `tag` | `str \| None` | obbligatorio | Stringa di etichetta, o `None` per cancellare. Sanitizzato Unicode prima dell'archiviazione |
412| `directory` | `str \| None` | `None` | Percorso della directory del progetto. Se omesso, cerca in tutte le directory del progetto |
413
414Genera `ValueError` se `session_id` non è un UUID valido o `tag` è vuoto dopo la sanitizzazione; `FileNotFoundError` se la sessione non può essere trovata.
415
416#### Esempio
417
418Etichetta una sessione, quindi filtra per quell'etichetta in una lettura successiva. Passa `None` per cancellare un'etichetta esistente.
419
420```python theme={null}
421from claude_agent_sdk import list_sessions, tag_session
422
423# Tag a session
424tag_session("550e8400-e29b-41d4-a716-446655440000", "needs-review")
425
426# Later: find all sessions with that tag
427for session in list_sessions(directory="/path/to/project"):
428 if session.tag == "needs-review":
429 print(session.summary)
430```
431
432## Classi
433
434### `ClaudeSDKClient`
435
436**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.
437
438#### Caratteristiche principali
439
440* **Continuità della sessione**: Mantiene il contesto della conversazione in più chiamate `query()`
441* **Stessa conversazione**: La sessione conserva i messaggi precedenti
442* **Supporto per interruzioni**: Può interrompere l'esecuzione a metà attività
443* **Ciclo di vita esplicito**: Controlli quando la sessione inizia e termina
444* **Flusso guidato dalla risposta**: Può reagire alle risposte e inviare follow-up
445* **Strumenti personalizzati e hooks**: Supporta strumenti personalizzati (creati con il decoratore `@tool`) e hooks
446
447```python theme={null}
448class ClaudeSDKClient:
449 def __init__(self, options: ClaudeAgentOptions | None = None, transport: Transport | None = None)
450 async def connect(self, prompt: str | AsyncIterable[dict] | None = None) -> None
451 async def query(self, prompt: str | AsyncIterable[dict], session_id: str = "default") -> None
452 async def receive_messages(self) -> AsyncIterator[Message]
453 async def receive_response(self) -> AsyncIterator[Message]
454 async def interrupt(self) -> None
455 async def set_permission_mode(self, mode: str) -> None
456 async def set_model(self, model: str | None = None) -> None
457 async def rewind_files(self, user_message_id: str) -> None
458 async def get_mcp_status(self) -> McpStatusResponse
459 async def reconnect_mcp_server(self, server_name: str) -> None
460 async def toggle_mcp_server(self, server_name: str, enabled: bool) -> None
461 async def stop_task(self, task_id: str) -> None
462 async def get_server_info(self) -> dict[str, Any] | None
463 async def disconnect(self) -> None
464```
465
466#### Metodi
467
468| Metodo | Descrizione |
469| :---------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
470| `__init__(options)` | Inizializza il client con configurazione opzionale |
471| `connect(prompt)` | Connettiti a Claude con un prompt iniziale opzionale o flusso di messaggi |
472| `query(prompt, session_id)` | Invia una nuova richiesta in modalità streaming |
473| `receive_messages()` | Ricevi tutti i messaggi da Claude come iteratore asincrono |
474| `receive_response()` | Ricevi messaggi fino a e incluso un ResultMessage |
475| `interrupt()` | Invia segnale di interruzione (funziona solo in modalità streaming) |
476| `set_permission_mode(mode)` | Cambia la modalità di autorizzazione per la sessione corrente |
477| `set_model(model)` | Cambia il modello per la sessione corrente. Passa `None` per ripristinare il valore predefinito |
478| `rewind_files(user_message_id)` | Ripristina i file al loro stato al messaggio utente specificato. Richiede `enable_file_checkpointing=True`. Vedi [File checkpointing](/it/agent-sdk/file-checkpointing) |
479| `get_mcp_status()` | Ottieni lo stato di tutti i server MCP configurati. Restituisce [`McpStatusResponse`](#mcp-status-response) |
480| `reconnect_mcp_server(server_name)` | Riprova a connettersi a un server MCP che ha fallito o è stato disconnesso |
481| `toggle_mcp_server(server_name, enabled)` | Abilita o disabilita un server MCP a metà sessione. La disabilitazione rimuove i suoi strumenti |
482| `stop_task(task_id)` | Interrompi un'attività in background in esecuzione. Un [`TaskNotificationMessage`](#task-notification-message) con stato `"stopped"` segue nel flusso di messaggi |
483| `get_server_info()` | Ottieni informazioni sul server incluso l'ID della sessione e le capacità |
484| `disconnect()` | Disconnettiti da Claude |
485
486#### Supporto Context Manager
487
488Il client può essere utilizzato come context manager asincrono per la gestione automatica della connessione:
489
490```python theme={null}
491async with ClaudeSDKClient() as client:
492 await client.query("Hello Claude")
493 async for message in client.receive_response():
494 print(message)
495```
496
497> **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.
498
499#### Esempio - Continuare una conversazione
500
501```python theme={null}
502import asyncio
503from claude_agent_sdk import ClaudeSDKClient, AssistantMessage, TextBlock, ResultMessage
504
505
506async def main():
507 async with ClaudeSDKClient() as client:
508 # First question
509 await client.query("What's the capital of France?")
510
511 # Process response
512 async for message in client.receive_response():
513 if isinstance(message, AssistantMessage):
514 for block in message.content:
515 if isinstance(block, TextBlock):
516 print(f"Claude: {block.text}")
517
518 # Follow-up question - the session retains the previous context
519 await client.query("What's the population of that city?")
520
521 async for message in client.receive_response():
522 if isinstance(message, AssistantMessage):
523 for block in message.content:
524 if isinstance(block, TextBlock):
525 print(f"Claude: {block.text}")
526
527 # Another follow-up - still in the same conversation
528 await client.query("What are some famous landmarks there?")
529
530 async for message in client.receive_response():
531 if isinstance(message, AssistantMessage):
532 for block in message.content:
533 if isinstance(block, TextBlock):
534 print(f"Claude: {block.text}")
535
536
537asyncio.run(main())
538```
539
540#### Esempio - Input streaming con ClaudeSDKClient
541
542```python theme={null}
543import asyncio
544from claude_agent_sdk import ClaudeSDKClient
545
546
547async def message_stream():
548 """Generate messages dynamically."""
549 yield {
550 "type": "user",
551 "message": {"role": "user", "content": "Analyze the following data:"},
552 }
553 await asyncio.sleep(0.5)
554 yield {
555 "type": "user",
556 "message": {"role": "user", "content": "Temperature: 25°C, Humidity: 60%"},
557 }
558 await asyncio.sleep(0.5)
559 yield {
560 "type": "user",
561 "message": {"role": "user", "content": "What patterns do you see?"},
562 }
563
564
565async def main():
566 async with ClaudeSDKClient() as client:
567 # Stream input to Claude
568 await client.query(message_stream())
569
570 # Process response
571 async for message in client.receive_response():
572 print(message)
573
574 # Follow-up in same session
575 await client.query("Should we be concerned about these readings?")
576
577 async for message in client.receive_response():
578 print(message)
579
580
581asyncio.run(main())
582```
583
584#### Esempio - Utilizzo di interruzioni
585
586```python theme={null}
587import asyncio
588from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, ResultMessage
589
590
591async def interruptible_task():
592 options = ClaudeAgentOptions(allowed_tools=["Bash"], permission_mode="acceptEdits")
593
594 async with ClaudeSDKClient(options=options) as client:
595 # Start a long-running task
596 await client.query("Count from 1 to 100 slowly, using the bash sleep command")
597
598 # Let it run for a bit
599 await asyncio.sleep(2)
600
601 # Interrupt the task
602 await client.interrupt()
603 print("Task interrupted!")
604
605 # Drain the interrupted task's messages (including its ResultMessage)
606 async for message in client.receive_response():
607 if isinstance(message, ResultMessage):
608 print(f"Interrupted task finished with subtype={message.subtype!r}")
609 # subtype is "error_during_execution" for interrupted tasks
610
611 # Send a new command
612 await client.query("Just say hello instead")
613
614 # Now receive the new response
615 async for message in client.receive_response():
616 if isinstance(message, ResultMessage) and message.subtype == "success":
617 print(f"New result: {message.result}")
618
619
620asyncio.run(interruptible_task())
621```
622
623<Note>
624 **Comportamento del buffer dopo l'interruzione:** `interrupt()` invia un segnale di arresto ma non cancella il buffer dei messaggi. I messaggi già prodotti dall'attività interrotta, incluso il suo `ResultMessage` (con `subtype="error_during_execution"`), rimangono nel flusso. Devi drenare con `receive_response()` prima di leggere la risposta a una nuova query. Se invii una nuova query immediatamente dopo `interrupt()` e chiami `receive_response()` una sola volta, riceverai i messaggi dell'attività interrotta, non la risposta della nuova query.
625</Note>
626
627#### Esempio - Controllo avanzato delle autorizzazioni
628
629```python theme={null}
630from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
631from claude_agent_sdk.types import (
632 PermissionResultAllow,
633 PermissionResultDeny,
634 ToolPermissionContext,
635)
636
637
638async def custom_permission_handler(
639 tool_name: str, input_data: dict, context: ToolPermissionContext
640) -> PermissionResultAllow | PermissionResultDeny:
641 """Custom logic for tool permissions."""
642
643 # Block writes to system directories
644 if tool_name == "Write" and input_data.get("file_path", "").startswith("/system/"):
645 return PermissionResultDeny(
646 message="System directory write not allowed", interrupt=True
647 )
648
649 # Redirect sensitive file operations
650 if tool_name in ["Write", "Edit"] and "config" in input_data.get("file_path", ""):
651 safe_path = f"./sandbox/{input_data['file_path']}"
652 return PermissionResultAllow(
653 updated_input={**input_data, "file_path": safe_path}
654 )
655
656 # Allow everything else
657 return PermissionResultAllow(updated_input=input_data)
658
659
660async def main():
661 options = ClaudeAgentOptions(
662 can_use_tool=custom_permission_handler, allowed_tools=["Read", "Write", "Edit"]
663 )
664
665 async with ClaudeSDKClient(options=options) as client:
666 await client.query("Update the system config file")
667
668 async for message in client.receive_response():
669 # Will use sandbox path instead
670 print(message)
671
672
673asyncio.run(main())
674```
675
676## Tipi
677
678<Note>
679 **`@dataclass` vs `TypedDict`:** Questo SDK utilizza due tipi di tipi. Le classi decorate con `@dataclass` (come `ResultMessage`, `AgentDefinition`, `TextBlock`) sono istanze di oggetti in fase di esecuzione e supportano l'accesso agli attributi: `msg.result`. Le classi definite con `TypedDict` (come `ThinkingConfigEnabled`, `McpStdioServerConfig`, `SyncHookJSONOutput`) sono **dicts semplici in fase di esecuzione** e richiedono l'accesso alle chiavi: `config["budget_tokens"]`, non `config.budget_tokens`. La sintassi di chiamata `ClassName(field=value)` funziona per entrambi, ma solo le dataclass producono oggetti con attributi.
680</Note>
681
682### `SdkMcpTool`
683
684Definizione per uno strumento SDK MCP creato con il decoratore `@tool`.
685
686```python theme={null}
687@dataclass
688class SdkMcpTool(Generic[T]):
689 name: str
690 description: str
691 input_schema: type[T] | dict[str, Any]
692 handler: Callable[[T], Awaitable[dict[str, Any]]]
693 annotations: ToolAnnotations | None = None
694```
695
696| Proprietà | Tipo | Descrizione |
697| :------------- | :----------------------------------------- | :-------------------------------------------------------------------------------------------------------------------- |
698| `name` | `str` | Identificatore univoco per lo strumento |
699| `description` | `str` | Descrizione leggibile |
700| `input_schema` | `type[T] \| dict[str, Any]` | Schema per la validazione dell'input |
701| `handler` | `Callable[[T], Awaitable[dict[str, Any]]]` | Funzione asincrona che gestisce l'esecuzione dello strumento |
702| `annotations` | `ToolAnnotations \| None` | Annotazioni MCP dello strumento opzionali (ad es. `readOnlyHint`, `destructiveHint`, `openWorldHint`). Da `mcp.types` |
703
704### `Transport`
705
706Classe 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).
707
708<Warning>
709 Questa è un'API interna di basso livello. L'interfaccia potrebbe cambiare nelle versioni future. Le implementazioni personalizzate devono essere aggiornate per corrispondere a eventuali modifiche dell'interfaccia.
710</Warning>
711
712```python theme={null}
713from abc import ABC, abstractmethod
714from collections.abc import AsyncIterator
715from typing import Any
716
717
718class Transport(ABC):
719 @abstractmethod
720 async def connect(self) -> None: ...
721
722 @abstractmethod
723 async def write(self, data: str) -> None: ...
724
725 @abstractmethod
726 def read_messages(self) -> AsyncIterator[dict[str, Any]]: ...
727
728 @abstractmethod
729 async def close(self) -> None: ...
730
731 @abstractmethod
732 def is_ready(self) -> bool: ...
733
734 @abstractmethod
735 async def end_input(self) -> None: ...
736```
737
738| Metodo | Descrizione |
739| :---------------- | :---------------------------------------------------------------------------- |
740| `connect()` | Connetti il trasporto e preparati per la comunicazione |
741| `write(data)` | Scrivi dati grezzi (JSON + newline) nel trasporto |
742| `read_messages()` | Iteratore asincrono che produce messaggi JSON analizzati |
743| `close()` | Chiudi la connessione e pulisci le risorse |
744| `is_ready()` | Restituisce `True` se il trasporto può inviare e ricevere |
745| `end_input()` | Chiudi il flusso di input (ad esempio, chiudi stdin per trasporti subprocess) |
746
747Importazione: `from claude_agent_sdk import Transport`
748
749### `ClaudeAgentOptions`
750
751Dataclass di configurazione per le query Claude Code.
752
753```python theme={null}
754@dataclass
755class ClaudeAgentOptions:
756 tools: list[str] | ToolsPreset | None = None
757 allowed_tools: list[str] = field(default_factory=list)
758 system_prompt: str | SystemPromptPreset | None = None
759 mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)
760 permission_mode: PermissionMode | None = None
761 continue_conversation: bool = False
762 resume: str | None = None
763 max_turns: int | None = None
764 max_budget_usd: float | None = None
765 disallowed_tools: list[str] = field(default_factory=list)
766 model: str | None = None
767 fallback_model: str | None = None
768 betas: list[SdkBeta] = field(default_factory=list)
769 output_format: dict[str, Any] | None = None
770 permission_prompt_tool_name: str | None = None
771 cwd: str | Path | None = None
772 cli_path: str | Path | None = None
773 settings: str | None = None
774 add_dirs: list[str | Path] = field(default_factory=list)
775 env: dict[str, str] = field(default_factory=dict)
776 extra_args: dict[str, str | None] = field(default_factory=dict)
777 max_buffer_size: int | None = None
778 debug_stderr: Any = sys.stderr # Deprecated
779 stderr: Callable[[str], None] | None = None
780 can_use_tool: CanUseTool | None = None
781 hooks: dict[HookEvent, list[HookMatcher]] | None = None
782 user: str | None = None
783 include_partial_messages: bool = False
784 fork_session: bool = False
785 agents: dict[str, AgentDefinition] | None = None
786 setting_sources: list[SettingSource] | None = None
787 sandbox: SandboxSettings | None = None
788 plugins: list[SdkPluginConfig] = field(default_factory=list)
789 max_thinking_tokens: int | None = None # Deprecated: use thinking instead
790 thinking: ThinkingConfig | None = None
791 effort: Literal["low", "medium", "high", "max"] | None = None
792 enable_file_checkpointing: bool = False
793 session_store: SessionStore | None = None
794```
795
796| Proprietà | Tipo | Predefinito | Descrizione |
797| :---------------------------- | :------------------------------------------------------------------------------------- | :---------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
798| `tools` | `list[str] \| ToolsPreset \| None` | `None` | Configurazione degli strumenti. Usa `{"type": "preset", "preset": "claude_code"}` per gli strumenti predefiniti di Claude Code |
799| `allowed_tools` | `list[str]` | `[]` | Strumenti da approvare automaticamente senza chiedere. Questo non limita Claude a solo questi strumenti; gli strumenti non elencati ricadono in `permission_mode` e `can_use_tool`. Usa `disallowed_tools` per bloccare gli strumenti. Vedi [Autorizzazioni](/it/agent-sdk/permissions#allow-and-deny-rules) |
800| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | Configurazione del prompt di sistema. Passa una stringa per un prompt personalizzato, o usa `{"type": "preset", "preset": "claude_code"}` per il prompt di sistema di Claude Code. Aggiungi `"append"` per estendere il preset |
801| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | Configurazioni del server MCP o percorso al file di configurazione |
802| `permission_mode` | `PermissionMode \| None` | `None` | Modalità di autorizzazione per l'utilizzo dello strumento |
803| `continue_conversation` | `bool` | `False` | Continua la conversazione più recente |
804| `resume` | `str \| None` | `None` | ID della sessione da riprendere |
805| `max_turns` | `int \| None` | `None` | Numero massimo di turni agentici (round trip di utilizzo dello strumento) |
806| `max_budget_usd` | `float \| None` | `None` | Interrompi la query quando la stima del costo lato client raggiunge questo valore in USD. Confrontato con la stessa stima di `total_cost_usd`; vedi [Traccia costo e utilizzo](/it/agent-sdk/cost-tracking) per avvertenze di accuratezza |
807| `disallowed_tools` | `list[str]` | `[]` | Strumenti da sempre negare. Le regole di negazione vengono controllate per prime e sovrascrivono `allowed_tools` e `permission_mode` (incluso `bypassPermissions`) |
808| `enable_file_checkpointing` | `bool` | `False` | Abilita il tracciamento dei cambiamenti dei file per il rewind. Vedi [File checkpointing](/it/agent-sdk/file-checkpointing) |
809| `model` | `str \| None` | `None` | Modello Claude da utilizzare |
810| `fallback_model` | `str \| None` | `None` | Modello di fallback da utilizzare se il modello primario fallisce |
811| `betas` | `list[SdkBeta]` | `[]` | Funzionalità beta da abilitare. Vedi [`SdkBeta`](#sdk-beta) per le opzioni disponibili |
812| `output_format` | `dict[str, Any] \| None` | `None` | Formato di output per risposte strutturate (ad es. `{"type": "json_schema", "schema": {...}}`). Vedi [Output strutturati](/it/agent-sdk/structured-outputs) per i dettagli |
813| `permission_prompt_tool_name` | `str \| None` | `None` | Nome dello strumento MCP per i prompt di autorizzazione |
814| `cwd` | `str \| Path \| None` | `None` | Directory di lavoro corrente |
815| `cli_path` | `str \| Path \| None` | `None` | Percorso personalizzato all'eseguibile CLI di Claude Code |
816| `settings` | `str \| None` | `None` | Percorso al file di impostazioni |
817| `add_dirs` | `list[str \| Path]` | `[]` | Directory aggiuntive a cui Claude può accedere |
818| `env` | `dict[str, str]` | `{}` | Variabili di ambiente unite in cima all'ambiente del processo ereditato. Vedi [Variabili di ambiente](/it/env-vars) per le variabili che la CLI sottostante legge |
819| `extra_args` | `dict[str, str \| None]` | `{}` | Argomenti CLI aggiuntivi da passare direttamente alla CLI |
820| `max_buffer_size` | `int \| None` | `None` | Byte massimi durante il buffering dell'stdout della CLI |
821| `debug_stderr` | `Any` | `sys.stderr` | *Deprecato* - Oggetto simile a un file per l'output di debug. Usa il callback `stderr` invece |
822| `stderr` | `Callable[[str], None] \| None` | `None` | Funzione di callback per l'output stderr dalla CLI |
823| `can_use_tool` | [`CanUseTool`](#can-use-tool) ` \| None` | `None` | Funzione di callback per l'autorizzazione dello strumento. Vedi [Tipi di autorizzazione](#can-use-tool) per i dettagli |
824| `hooks` | `dict[HookEvent, list[HookMatcher]] \| None` | `None` | Configurazioni hook per intercettare gli eventi |
825| `user` | `str \| None` | `None` | Identificatore utente |
826| `include_partial_messages` | `bool` | `False` | Includi eventi di streaming di messaggi parziali. Se abilitato, i messaggi [`StreamEvent`](#stream-event) vengono prodotti |
827| `fork_session` | `bool` | `False` | Quando si riprende con `resume`, esegui il fork a un nuovo ID di sessione invece di continuare la sessione originale |
828| `agents` | `dict[str, AgentDefinition] \| None` | `None` | Subagenti definiti programmaticamente |
829| `plugins` | `list[SdkPluginConfig]` | `[]` | Carica plugin personalizzati da percorsi locali. Vedi [Plugin](/it/agent-sdk/plugins) per i dettagli |
830| `sandbox` | [`SandboxSettings`](#sandbox-settings) ` \| None` | `None` | Configura il comportamento della sandbox a livello di programmazione. Vedi [Impostazioni sandbox](#sandbox-settings) per i dettagli |
831| `setting_sources` | `list[SettingSource] \| None` | `None` (Impostazioni predefinite CLI: tutte le fonti) | Controlla quali impostazioni del filesystem caricare. Passa `[]` per disabilitare le impostazioni utente, progetto e locali. Le impostazioni della politica gestita vengono caricate indipendentemente. Vedi [Usa le funzionalità di Claude Code](/it/agent-sdk/claude-code-features#what-settingsources-does-not-control) |
832| `max_thinking_tokens` | `int \| None` | `None` | *Deprecato* - Token massimi per i blocchi di pensiero. Usa `thinking` invece |
833| `thinking` | [`ThinkingConfig`](#thinking-config) ` \| None` | `None` | Controlla il comportamento del pensiero esteso. Ha la precedenza su `max_thinking_tokens` |
834| `effort` | `Literal["low", "medium", "high", "max"] \| None` | `None` | Livello di sforzo per la profondità del pensiero |
835| `session_store` | [`SessionStore`](/it/agent-sdk/session-storage#the-session-store-interface) ` \| None` | `None` | Specchia i trascritti di sessione in un backend esterno in modo che qualsiasi host possa riprenderli. Vedi [Persisti le sessioni nell'archiviazione esterna](/it/agent-sdk/session-storage) |
836
837### `OutputFormat`
838
839Configurazione per la validazione dell'output strutturato. Passa questo come `dict` al campo `output_format` su `ClaudeAgentOptions`:
840
841```python theme={null}
842# Expected dict shape for output_format
843{
844 "type": "json_schema",
845 "schema": {...}, # Your JSON Schema definition
846}
847```
848
849| Campo | Obbligatorio | Descrizione |
850| :------- | :----------- | :--------------------------------------------------------- |
851| `type` | Sì | Deve essere `"json_schema"` per la validazione JSON Schema |
852| `schema` | Sì | Definizione JSON Schema per la validazione dell'output |
853
854### `SystemPromptPreset`
855
856Configurazione per l'utilizzo del prompt di sistema preset di Claude Code con aggiunte opzionali.
857
858```python theme={null}
859class SystemPromptPreset(TypedDict):
860 type: Literal["preset"]
861 preset: Literal["claude_code"]
862 append: NotRequired[str]
863 exclude_dynamic_sections: NotRequired[bool]
864```
865
866| Campo | Obbligatorio | Descrizione |
867| :------------------------- | :----------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
868| `type` | Sì | Deve essere `"preset"` per utilizzare un prompt di sistema preset |
869| `preset` | Sì | Deve essere `"claude_code"` per utilizzare il prompt di sistema di Claude Code |
870| `append` | No | Istruzioni aggiuntive da aggiungere al prompt di sistema preset |
871| `exclude_dynamic_sections` | No | Sposta il contesto per sessione come directory di lavoro, stato git e percorsi di memoria dal prompt di sistema nel primo messaggio utente. Migliora il riutilizzo della cache dei prompt tra utenti e macchine. Vedi [Modifica i prompt di sistema](/it/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |
872
873### `SettingSource`
874
875Controlla quali fonti di configurazione basate su filesystem l'SDK carica le impostazioni da.
876
877```python theme={null}
878SettingSource = Literal["user", "project", "local"]
879```
880
881| Valore | Descrizione | Posizione |
882| :---------- | :-------------------------------------------------------------- | :---------------------------- |
883| `"user"` | Impostazioni utente globali | `~/.claude/settings.json` |
884| `"project"` | Impostazioni di progetto condivise (controllate dalla versione) | `.claude/settings.json` |
885| `"local"` | Impostazioni di progetto locali (gitignored) | `.claude/settings.local.json` |
886
887#### Comportamento predefinito
888
889Quando `setting_sources` è omesso o `None`, `query()` carica le stesse impostazioni del filesystem della CLI di Claude Code: utente, progetto e locale. Le impostazioni della politica gestita vengono caricate in tutti i casi. Vedi [Cosa settingSources non controlla](/it/agent-sdk/claude-code-features#what-settingsources-does-not-control) per gli input che vengono letti indipendentemente da questa opzione, e come disabilitarli.
890
891#### Perché usare setting\_sources
892
893**Disabilita le impostazioni del filesystem:**
894
895```python theme={null}
896# Do not load user, project, or local settings from disk
897from claude_agent_sdk import query, ClaudeAgentOptions
898
899async for message in query(
900 prompt="Analyze this code",
901 options=ClaudeAgentOptions(
902 setting_sources=[]
903 ),
904):
905 print(message)
906```
907
908<Note>
909 In Python SDK 0.1.59 e versioni precedenti, un elenco vuoto era trattato come l'omissione dell'opzione, quindi `setting_sources=[]` non disabilitava le impostazioni del filesystem. Aggiorna a una versione più recente se hai bisogno che un elenco vuoto abbia effetto. TypeScript SDK non è interessato.
910</Note>
911
912**Carica tutte le impostazioni del filesystem in modo esplicito:**
913
914```python theme={null}
915from claude_agent_sdk import query, ClaudeAgentOptions
916
917async for message in query(
918 prompt="Analyze this code",
919 options=ClaudeAgentOptions(
920 setting_sources=["user", "project", "local"]
921 ),
922):
923 print(message)
924```
925
926**Carica solo fonti di impostazioni specifiche:**
927
928```python theme={null}
929# Load only project settings, ignore user and local
930async for message in query(
931 prompt="Run CI checks",
932 options=ClaudeAgentOptions(
933 setting_sources=["project"] # Only .claude/settings.json
934 ),
935):
936 print(message)
937```
938
939**Ambienti di test e CI:**
940
941```python theme={null}
942# Ensure consistent behavior in CI by excluding local settings
943async for message in query(
944 prompt="Run tests",
945 options=ClaudeAgentOptions(
946 setting_sources=["project"], # Only team-shared settings
947 permission_mode="bypassPermissions",
948 ),
949):
950 print(message)
951```
952
953**Applicazioni solo SDK:**
954
955```python theme={null}
956# Define everything programmatically.
957# Pass [] to opt out of filesystem setting sources.
958async for message in query(
959 prompt="Review this PR",
960 options=ClaudeAgentOptions(
961 setting_sources=[],
962 agents={...},
963 mcp_servers={...},
964 allowed_tools=["Read", "Grep", "Glob"],
965 ),
966):
967 print(message)
968```
969
970**Caricamento delle istruzioni del progetto CLAUDE.md:**
971
972```python theme={null}
973# Load project settings to include CLAUDE.md files
974async for message in query(
975 prompt="Add a new feature following project conventions",
976 options=ClaudeAgentOptions(
977 system_prompt={
978 "type": "preset",
979 "preset": "claude_code", # Use Claude Code's system prompt
980 },
981 setting_sources=["project"], # Loads CLAUDE.md from project
982 allowed_tools=["Read", "Write", "Edit"],
983 ),
984):
985 print(message)
986```
987
988#### Precedenza delle impostazioni
989
990Quando più fonti vengono caricate, le impostazioni vengono unite con questa precedenza (da più alta a più bassa):
991
9921. Impostazioni locali (`.claude/settings.local.json`)
9932. Impostazioni di progetto (`.claude/settings.json`)
9943. Impostazioni utente (`~/.claude/settings.json`)
995
996Le opzioni programmatiche come `agents` e `allowed_tools` sovrascrivono le impostazioni del filesystem utente, progetto e locale. Le impostazioni della politica gestita hanno la precedenza sulle opzioni programmatiche.
997
998### `AgentDefinition`
999
1000Configurazione per un subagente definito programmaticamente.
1001
1002```python theme={null}
1003@dataclass
1004class AgentDefinition:
1005 description: str
1006 prompt: str
1007 tools: list[str] | None = None
1008 disallowedTools: list[str] | None = None
1009 model: str | None = None
1010 skills: list[str] | None = None
1011 memory: Literal["user", "project", "local"] | None = None
1012 mcpServers: list[str | dict[str, Any]] | None = None
1013 initialPrompt: str | None = None
1014 maxTurns: int | None = None
1015 background: bool | None = None
1016 effort: Literal["low", "medium", "high", "max"] | int | None = None
1017 permissionMode: PermissionMode | None = None
1018```
1019
1020| Campo | Obbligatorio | Descrizione |
1021| :---------------- | :----------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1022| `description` | Sì | Descrizione in linguaggio naturale di quando utilizzare questo agente |
1023| `prompt` | Sì | Il prompt di sistema dell'agente |
1024| `tools` | No | Array di nomi di strumenti consentiti. Se omesso, eredita tutti gli strumenti |
1025| `disallowedTools` | No | Array di nomi di strumenti da rimuovere dal set di strumenti dell'agente |
1026| `model` | No | Override del modello per questo agente. Accetta un alias come `"sonnet"`, `"opus"`, `"haiku"`, o `"inherit"`, o un ID modello completo. Se omesso, utilizza il modello principale |
1027| `skills` | No | Elenco dei nomi di skills disponibili per questo agente |
1028| `memory` | No | Fonte di memoria per questo agente: `"user"`, `"project"`, o `"local"` |
1029| `mcpServers` | No | Server MCP disponibili per questo agente. Ogni voce è un nome di server o un dict `{name: config}` inline |
1030| `initialPrompt` | No | Auto-inviato come il primo turno utente quando questo agente viene eseguito come agente del thread principale |
1031| `maxTurns` | No | Numero massimo di turni agentici prima che l'agente si fermi |
1032| `background` | No | Esegui questo agente come attività in background non bloccante quando invocato |
1033| `effort` | No | Livello di sforzo di ragionamento per questo agente. Accetta un livello denominato o un numero intero |
1034| `permissionMode` | No | Modalità di autorizzazione per l'esecuzione dello strumento all'interno di questo agente. Vedi [`PermissionMode`](#permission-mode) |
1035
1036<Note>
1037 I nomi dei campi `AgentDefinition` usano camelCase, come `disallowedTools`, `permissionMode` e `maxTurns`. Questi nomi si mappano direttamente al formato wire condiviso con TypeScript SDK. Questo differisce da `ClaudeAgentOptions`, che usa Python snake\_case per i campi di livello superiore equivalenti come `disallowed_tools` e `permission_mode`. Poiché `AgentDefinition` è una dataclass, passare una parola chiave snake\_case genera un `TypeError` al momento della costruzione.
1038</Note>
1039
1040### `PermissionMode`
1041
1042Modalità di autorizzazione per controllare l'esecuzione dello strumento.
1043
1044```python theme={null}
1045PermissionMode = Literal[
1046 "default", # Standard permission behavior
1047 "acceptEdits", # Auto-accept file edits
1048 "plan", # Planning mode - no execution
1049 "dontAsk", # Deny anything not pre-approved instead of prompting
1050 "bypassPermissions", # Bypass all permission checks (use with caution)
1051]
1052```
1053
1054### `CanUseTool`
1055
1056Alias di tipo per le funzioni di callback di autorizzazione dello strumento.
1057
1058```python theme={null}
1059CanUseTool = Callable[
1060 [str, dict[str, Any], ToolPermissionContext], Awaitable[PermissionResult]
1061]
1062```
1063
1064Il callback riceve:
1065
1066* `tool_name`: Nome dello strumento che viene chiamato
1067* `input_data`: I parametri di input dello strumento
1068* `context`: Un `ToolPermissionContext` con informazioni aggiuntive
1069
1070Restituisce un `PermissionResult` (sia `PermissionResultAllow` che `PermissionResultDeny`).
1071
1072### `ToolPermissionContext`
1073
1074Informazioni di contesto passate ai callback di autorizzazione dello strumento.
1075
1076```python theme={null}
1077@dataclass
1078class ToolPermissionContext:
1079 signal: Any | None = None # Future: abort signal support
1080 suggestions: list[PermissionUpdate] = field(default_factory=list)
1081```
1082
1083| Campo | Tipo | Descrizione |
1084| :------------ | :----------------------- | :----------------------------------------------------------- |
1085| `signal` | `Any \| None` | Riservato per il supporto futuro del segnale di interruzione |
1086| `suggestions` | `list[PermissionUpdate]` | Suggerimenti di aggiornamento delle autorizzazioni dalla CLI |
1087
1088### `PermissionResult`
1089
1090Tipo di unione per i risultati del callback di autorizzazione.
1091
1092```python theme={null}
1093PermissionResult = PermissionResultAllow | PermissionResultDeny
1094```
1095
1096### `PermissionResultAllow`
1097
1098Risultato che indica che la chiamata dello strumento deve essere consentita.
1099
1100```python theme={null}
1101@dataclass
1102class PermissionResultAllow:
1103 behavior: Literal["allow"] = "allow"
1104 updated_input: dict[str, Any] | None = None
1105 updated_permissions: list[PermissionUpdate] | None = None
1106```
1107
1108| Campo | Tipo | Predefinito | Descrizione |
1109| :-------------------- | :------------------------------- | :---------- | :----------------------------------------------------- |
1110| `behavior` | `Literal["allow"]` | `"allow"` | Deve essere "allow" |
1111| `updated_input` | `dict[str, Any] \| None` | `None` | Input modificato da utilizzare al posto dell'originale |
1112| `updated_permissions` | `list[PermissionUpdate] \| None` | `None` | Aggiornamenti delle autorizzazioni da applicare |
1113
1114### `PermissionResultDeny`
1115
1116Risultato che indica che la chiamata dello strumento deve essere negata.
1117
1118```python theme={null}
1119@dataclass
1120class PermissionResultDeny:
1121 behavior: Literal["deny"] = "deny"
1122 message: str = ""
1123 interrupt: bool = False
1124```
1125
1126| Campo | Tipo | Predefinito | Descrizione |
1127| :---------- | :---------------- | :---------- | :------------------------------------------------------ |
1128| `behavior` | `Literal["deny"]` | `"deny"` | Deve essere "deny" |
1129| `message` | `str` | `""` | Messaggio che spiega perché lo strumento è stato negato |
1130| `interrupt` | `bool` | `False` | Se interrompere l'esecuzione corrente |
1131
1132### `PermissionUpdate`
1133
1134Configurazione per l'aggiornamento delle autorizzazioni a livello di programmazione.
1135
1136```python theme={null}
1137@dataclass
1138class PermissionUpdate:
1139 type: Literal[
1140 "addRules",
1141 "replaceRules",
1142 "removeRules",
1143 "setMode",
1144 "addDirectories",
1145 "removeDirectories",
1146 ]
1147 rules: list[PermissionRuleValue] | None = None
1148 behavior: Literal["allow", "deny", "ask"] | None = None
1149 mode: PermissionMode | None = None
1150 directories: list[str] | None = None
1151 destination: (
1152 Literal["userSettings", "projectSettings", "localSettings", "session"] | None
1153 ) = None
1154```
1155
1156| Campo | Tipo | Descrizione |
1157| :------------ | :---------------------------------------- | :---------------------------------------------------------- |
1158| `type` | `Literal[...]` | Il tipo di operazione di aggiornamento delle autorizzazioni |
1159| `rules` | `list[PermissionRuleValue] \| None` | Regole per le operazioni add/replace/remove |
1160| `behavior` | `Literal["allow", "deny", "ask"] \| None` | Comportamento per le operazioni basate su regole |
1161| `mode` | `PermissionMode \| None` | Modalità per l'operazione setMode |
1162| `directories` | `list[str] \| None` | Directory per le operazioni add/remove directory |
1163| `destination` | `Literal[...] \| None` | Dove applicare l'aggiornamento delle autorizzazioni |
1164
1165### `PermissionRuleValue`
1166
1167Una regola da aggiungere, sostituire o rimuovere in un aggiornamento delle autorizzazioni.
1168
1169```python theme={null}
1170@dataclass
1171class PermissionRuleValue:
1172 tool_name: str
1173 rule_content: str | None = None
1174```
1175
1176### `ToolsPreset`
1177
1178Configurazione degli strumenti preset per l'utilizzo del set di strumenti predefinito di Claude Code.
1179
1180```python theme={null}
1181class ToolsPreset(TypedDict):
1182 type: Literal["preset"]
1183 preset: Literal["claude_code"]
1184```
1185
1186### `ThinkingConfig`
1187
1188Controlla il comportamento del pensiero esteso. Un'unione di tre configurazioni:
1189
1190```python theme={null}
1191class ThinkingConfigAdaptive(TypedDict):
1192 type: Literal["adaptive"]
1193
1194
1195class ThinkingConfigEnabled(TypedDict):
1196 type: Literal["enabled"]
1197 budget_tokens: int
1198
1199
1200class ThinkingConfigDisabled(TypedDict):
1201 type: Literal["disabled"]
1202
1203
1204ThinkingConfig = ThinkingConfigAdaptive | ThinkingConfigEnabled | ThinkingConfigDisabled
1205```
1206
1207| Variante | Campi | Descrizione |
1208| :--------- | :---------------------- | :--------------------------------------------------- |
1209| `adaptive` | `type` | Claude decide adattivamente quando pensare |
1210| `enabled` | `type`, `budget_tokens` | Abilita il pensiero con un budget di token specifico |
1211| `disabled` | `type` | Disabilita il pensiero |
1212
1213Poiché 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`:
1214
1215```python theme={null}
1216from claude_agent_sdk import ClaudeAgentOptions, ThinkingConfigEnabled
1217
1218# Option 1: dict literal (recommended, no import needed)
1219options = ClaudeAgentOptions(thinking={"type": "enabled", "budget_tokens": 20000})
1220
1221# Option 2: constructor-style (returns a plain dict)
1222config = ThinkingConfigEnabled(type="enabled", budget_tokens=20000)
1223print(config["budget_tokens"]) # 20000
1224# config.budget_tokens would raise AttributeError
1225```
1226
1227### `SdkBeta`
1228
1229Tipo letterale per le funzionalità beta dell'SDK.
1230
1231```python theme={null}
1232SdkBeta = Literal["context-1m-2025-08-07"]
1233```
1234
1235Usa con il campo `betas` in `ClaudeAgentOptions` per abilitare le funzionalità beta.
1236
1237<Warning>
1238 La beta `context-1m-2025-08-07` è ritirata a partire dal 30 aprile 2026. Passare questo header con Claude Sonnet 4.5 o Sonnet 4 non ha effetto, e le richieste che superano la finestra di contesto standard di 200k token restituiscono un errore. Per utilizzare una finestra di contesto di 1M token, esegui la migrazione a [Claude Sonnet 4.6, Claude Opus 4.6, o Claude Opus 4.7](https://platform.claude.com/docs/en/about-claude/models/overview), che includono 1M di contesto a prezzi standard senza header beta richiesto.
1239</Warning>
1240
1241### `McpSdkServerConfig`
1242
1243Configurazione per i server MCP dell'SDK creati con `create_sdk_mcp_server()`.
1244
1245```python theme={null}
1246class McpSdkServerConfig(TypedDict):
1247 type: Literal["sdk"]
1248 name: str
1249 instance: Any # MCP Server instance
1250```
1251
1252### `McpServerConfig`
1253
1254Tipo di unione per le configurazioni del server MCP.
1255
1256```python theme={null}
1257McpServerConfig = (
1258 McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig
1259)
1260```
1261
1262#### `McpStdioServerConfig`
1263
1264```python theme={null}
1265class McpStdioServerConfig(TypedDict):
1266 type: NotRequired[Literal["stdio"]] # Optional for backwards compatibility
1267 command: str
1268 args: NotRequired[list[str]]
1269 env: NotRequired[dict[str, str]]
1270```
1271
1272#### `McpSSEServerConfig`
1273
1274```python theme={null}
1275class McpSSEServerConfig(TypedDict):
1276 type: Literal["sse"]
1277 url: str
1278 headers: NotRequired[dict[str, str]]
1279```
1280
1281#### `McpHttpServerConfig`
1282
1283```python theme={null}
1284class McpHttpServerConfig(TypedDict):
1285 type: Literal["http"]
1286 url: str
1287 headers: NotRequired[dict[str, str]]
1288```
1289
1290### `McpServerStatusConfig`
1291
1292La configurazione di un server MCP come riportato da [`get_mcp_status()`](#methods). Questa è l'unione di tutte le varianti di trasporto [`McpServerConfig`](#mcp-server-config) più una variante di output-only `claudeai-proxy` per i server proxy attraverso claude.ai.
1293
1294```python theme={null}
1295McpServerStatusConfig = (
1296 McpStdioServerConfig
1297 | McpSSEServerConfig
1298 | McpHttpServerConfig
1299 | McpSdkServerConfigStatus
1300 | McpClaudeAIProxyServerConfig
1301)
1302```
1303
1304`McpSdkServerConfigStatus` è la forma serializzabile di [`McpSdkServerConfig`](#mcp-sdk-server-config) 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`).
1305
1306### `McpStatusResponse`
1307
1308Risposta da [`ClaudeSDKClient.get_mcp_status()`](#methods). Avvolge l'elenco degli stati del server sotto la chiave `mcpServers`.
1309
1310```python theme={null}
1311class McpStatusResponse(TypedDict):
1312 mcpServers: list[McpServerStatus]
1313```
1314
1315### `McpServerStatus`
1316
1317Stato di un server MCP connesso, contenuto in [`McpStatusResponse`](#mcp-status-response).
1318
1319```python theme={null}
1320class McpServerStatus(TypedDict):
1321 name: str
1322 status: McpServerConnectionStatus # "connected" | "failed" | "needs-auth" | "pending" | "disabled"
1323 serverInfo: NotRequired[McpServerInfo]
1324 error: NotRequired[str]
1325 config: NotRequired[McpServerStatusConfig]
1326 scope: NotRequired[str]
1327 tools: NotRequired[list[McpToolInfo]]
1328```
1329
1330| Campo | Tipo | Descrizione |
1331| :----------- | :--------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1332| `name` | `str` | Nome del server |
1333| `status` | `str` | Uno di `"connected"`, `"failed"`, `"needs-auth"`, `"pending"`, o `"disabled"` |
1334| `serverInfo` | `dict` (opzionale) | Nome e versione del server (`{"name": str, "version": str}`) |
1335| `error` | `str` (opzionale) | Messaggio di errore se il server non si è connesso |
1336| `config` | [`McpServerStatusConfig`](#mcp-server-status-config) (opzionale) | Configurazione del server. Stessa forma di [`McpServerConfig`](#mcp-server-config) (stdio, SSE, HTTP, o SDK), più una variante `claudeai-proxy` per i server connessi tramite claude.ai |
1337| `scope` | `str` (opzionale) | Ambito di configurazione |
1338| `tools` | `list` (opzionale) | Strumenti forniti da questo server, ognuno con i campi `name`, `description`, e `annotations` |
1339
1340### `SdkPluginConfig`
1341
1342Configurazione per il caricamento dei plugin nell'SDK.
1343
1344```python theme={null}
1345class SdkPluginConfig(TypedDict):
1346 type: Literal["local"]
1347 path: str
1348```
1349
1350| Campo | Tipo | Descrizione |
1351| :----- | :----------------- | :--------------------------------------------------------------------- |
1352| `type` | `Literal["local"]` | Deve essere `"local"` (attualmente sono supportati solo plugin locali) |
1353| `path` | `str` | Percorso assoluto o relativo alla directory del plugin |
1354
1355**Esempio:**
1356
1357```python theme={null}
1358plugins = [
1359 {"type": "local", "path": "./my-plugin"},
1360 {"type": "local", "path": "/absolute/path/to/plugin"},
1361]
1362```
1363
1364Per informazioni complete sulla creazione e l'utilizzo dei plugin, vedi [Plugin](/it/agent-sdk/plugins).
1365
1366## Tipi di messaggio
1367
1368### `Message`
1369
1370Tipo di unione di tutti i possibili messaggi.
1371
1372```python theme={null}
1373Message = (
1374 UserMessage
1375 | AssistantMessage
1376 | SystemMessage
1377 | ResultMessage
1378 | StreamEvent
1379 | RateLimitEvent
1380)
1381```
1382
1383### `UserMessage`
1384
1385Messaggio di input dell'utente.
1386
1387```python theme={null}
1388@dataclass
1389class UserMessage:
1390 content: str | list[ContentBlock]
1391 uuid: str | None = None
1392 parent_tool_use_id: str | None = None
1393 tool_use_result: dict[str, Any] | None = None
1394```
1395
1396| Campo | Tipo | Descrizione |
1397| :------------------- | :-------------------------- | :--------------------------------------------------------------------------------------------- |
1398| `content` | `str \| list[ContentBlock]` | Contenuto del messaggio come testo o blocchi di contenuto |
1399| `uuid` | `str \| None` | Identificatore di messaggio univoco |
1400| `parent_tool_use_id` | `str \| None` | ID di utilizzo dello strumento se questo messaggio è una risposta al risultato dello strumento |
1401| `tool_use_result` | `dict[str, Any] \| None` | Dati del risultato dello strumento se applicabile |
1402
1403### `AssistantMessage`
1404
1405Messaggio di risposta dell'assistente con blocchi di contenuto.
1406
1407```python theme={null}
1408@dataclass
1409class AssistantMessage:
1410 content: list[ContentBlock]
1411 model: str
1412 parent_tool_use_id: str | None = None
1413 error: AssistantMessageError | None = None
1414 usage: dict[str, Any] | None = None
1415 message_id: str | None = None
1416```
1417
1418| Campo | Tipo | Descrizione |
1419| :------------------- | :------------------------------------------------------------- | :------------------------------------------------------------------------------------------- |
1420| `content` | `list[ContentBlock]` | Elenco di blocchi di contenuto nella risposta |
1421| `model` | `str` | Modello che ha generato la risposta |
1422| `parent_tool_use_id` | `str \| None` | ID di utilizzo dello strumento se questa è una risposta nidificata |
1423| `error` | [`AssistantMessageError`](#assistant-message-error) ` \| None` | Tipo di errore se la risposta ha riscontrato un errore |
1424| `usage` | `dict[str, Any] \| None` | Utilizzo dei token per messaggio (stesse chiavi di [`ResultMessage.usage`](#result-message)) |
1425| `message_id` | `str \| None` | ID del messaggio API. Più messaggi da un turno condividono lo stesso ID |
1426
1427### `AssistantMessageError`
1428
1429Possibili tipi di errore per i messaggi dell'assistente.
1430
1431```python theme={null}
1432AssistantMessageError = Literal[
1433 "authentication_failed",
1434 "billing_error",
1435 "rate_limit",
1436 "invalid_request",
1437 "server_error",
1438 "max_output_tokens",
1439 "unknown",
1440]
1441```
1442
1443### `SystemMessage`
1444
1445Messaggio di sistema con metadati.
1446
1447```python theme={null}
1448@dataclass
1449class SystemMessage:
1450 subtype: str
1451 data: dict[str, Any]
1452```
1453
1454### `ResultMessage`
1455
1456Messaggio di risultato finale con informazioni su costo e utilizzo.
1457
1458```python theme={null}
1459@dataclass
1460class ResultMessage:
1461 subtype: str
1462 duration_ms: int
1463 duration_api_ms: int
1464 is_error: bool
1465 num_turns: int
1466 session_id: str
1467 total_cost_usd: float | None = None
1468 usage: dict[str, Any] | None = None
1469 result: str | None = None
1470 stop_reason: str | None = None
1471 structured_output: Any = None
1472 model_usage: dict[str, Any] | None = None
1473```
1474
1475Il dict `usage` contiene le seguenti chiavi quando presenti:
1476
1477| Chiave | Tipo | Descrizione |
1478| ----------------------------- | ----- | ------------------------------------------------ |
1479| `input_tokens` | `int` | Token di input totali consumati. |
1480| `output_tokens` | `int` | Token di output totali generati. |
1481| `cache_creation_input_tokens` | `int` | Token utilizzati per creare nuove voci di cache. |
1482| `cache_read_input_tokens` | `int` | Token letti dalle voci di cache esistenti. |
1483
1484Il dict `model_usage` mappa i nomi dei modelli all'utilizzo per modello. Le chiavi del dict interno usano camelCase perché il valore viene passato senza modifiche dal processo CLI sottostante, corrispondendo al tipo TypeScript [`ModelUsage`](/it/agent-sdk/typescript#model-usage):
1485
1486| Chiave | Tipo | Descrizione |
1487| -------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1488| `inputTokens` | `int` | Token di input per questo modello. |
1489| `outputTokens` | `int` | Token di output per questo modello. |
1490| `cacheReadInputTokens` | `int` | Token di lettura della cache per questo modello. |
1491| `cacheCreationInputTokens` | `int` | Token di creazione della cache per questo modello. |
1492| `webSearchRequests` | `int` | Richieste di ricerca web effettuate da questo modello. |
1493| `costUSD` | `float` | Costo stimato in USD per questo modello, calcolato lato client. Vedi [Traccia costo e utilizzo](/it/agent-sdk/cost-tracking) per avvertenze di fatturazione. |
1494| `contextWindow` | `int` | Dimensione della finestra di contesto per questo modello. |
1495| `maxOutputTokens` | `int` | Limite massimo di token di output per questo modello. |
1496
1497### `StreamEvent`
1498
1499Evento 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`.
1500
1501```python theme={null}
1502@dataclass
1503class StreamEvent:
1504 uuid: str
1505 session_id: str
1506 event: dict[str, Any] # The raw Claude API stream event
1507 parent_tool_use_id: str | None = None
1508```
1509
1510| Campo | Tipo | Descrizione |
1511| :------------------- | :--------------- | :----------------------------------------------------------------------------- |
1512| `uuid` | `str` | Identificatore univoco per questo evento |
1513| `session_id` | `str` | Identificatore di sessione |
1514| `event` | `dict[str, Any]` | I dati dell'evento di flusso dell'API Claude grezzo |
1515| `parent_tool_use_id` | `str \| None` | ID di utilizzo dello strumento padre se questo evento proviene da un subagente |
1516
1517### `RateLimitEvent`
1518
1519Emesso 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"`.
1520
1521```python theme={null}
1522@dataclass
1523class RateLimitEvent:
1524 rate_limit_info: RateLimitInfo
1525 uuid: str
1526 session_id: str
1527```
1528
1529| Campo | Tipo | Descrizione |
1530| :---------------- | :---------------------------------- | :------------------------------------ |
1531| `rate_limit_info` | [`RateLimitInfo`](#rate-limit-info) | Stato del limite di velocità corrente |
1532| `uuid` | `str` | Identificatore di evento univoco |
1533| `session_id` | `str` | Identificatore di sessione |
1534
1535### `RateLimitInfo`
1536
1537Stato del limite di velocità trasportato da [`RateLimitEvent`](#rate-limit-event).
1538
1539```python theme={null}
1540RateLimitStatus = Literal["allowed", "allowed_warning", "rejected"]
1541RateLimitType = Literal[
1542 "five_hour", "seven_day", "seven_day_opus", "seven_day_sonnet", "overage"
1543]
1544
1545
1546@dataclass
1547class RateLimitInfo:
1548 status: RateLimitStatus
1549 resets_at: int | None = None
1550 rate_limit_type: RateLimitType | None = None
1551 utilization: float | None = None
1552 overage_status: RateLimitStatus | None = None
1553 overage_resets_at: int | None = None
1554 overage_disabled_reason: str | None = None
1555 raw: dict[str, Any] = field(default_factory=dict)
1556```
1557
1558| Campo | Tipo | Descrizione |
1559| :------------------------ | :------------------------ | :-------------------------------------------------------------------------------------------------------------------------- |
1560| `status` | `RateLimitStatus` | Stato corrente. `"allowed_warning"` significa avvicinarsi al limite; `"rejected"` significa che il limite è stato raggiunto |
1561| `resets_at` | `int \| None` | Timestamp Unix quando la finestra del limite di velocità si ripristina |
1562| `rate_limit_type` | `RateLimitType \| None` | Quale finestra del limite di velocità si applica |
1563| `utilization` | `float \| None` | Frazione del limite di velocità consumato (0.0 a 1.0) |
1564| `overage_status` | `RateLimitStatus \| None` | Stato dell'utilizzo di overage pay-as-you-go, se applicabile |
1565| `overage_resets_at` | `int \| None` | Timestamp Unix quando la finestra di overage si ripristina |
1566| `overage_disabled_reason` | `str \| None` | Perché l'overage non è disponibile, se lo stato è `"rejected"` |
1567| `raw` | `dict[str, Any]` | Dict grezzo completo dalla CLI, inclusi i campi non modellati sopra |
1568
1569### `TaskStartedMessage`
1570
1571Emesso 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`.
1572
1573```python theme={null}
1574@dataclass
1575class TaskStartedMessage(SystemMessage):
1576 task_id: str
1577 description: str
1578 uuid: str
1579 session_id: str
1580 tool_use_id: str | None = None
1581 task_type: str | None = None
1582```
1583
1584| Campo | Tipo | Descrizione |
1585| :------------ | :------------ | :------------------------------------------------------------------------------------------------------------------------------- |
1586| `task_id` | `str` | Identificatore univoco per l'attività |
1587| `description` | `str` | Descrizione dell'attività |
1588| `uuid` | `str` | Identificatore di messaggio univoco |
1589| `session_id` | `str` | Identificatore di sessione |
1590| `tool_use_id` | `str \| None` | ID di utilizzo dello strumento associato |
1591| `task_type` | `str \| None` | Quale tipo di attività in background: `"local_bash"` per Bash in background e watch Monitor, `"local_agent"`, o `"remote_agent"` |
1592
1593### `TaskUsage`
1594
1595Dati di token e timing per un'attività in background.
1596
1597```python theme={null}
1598class TaskUsage(TypedDict):
1599 total_tokens: int
1600 tool_uses: int
1601 duration_ms: int
1602```
1603
1604### `TaskProgressMessage`
1605
1606Emesso periodicamente con aggiornamenti di progresso per un'attività in background in esecuzione.
1607
1608```python theme={null}
1609@dataclass
1610class TaskProgressMessage(SystemMessage):
1611 task_id: str
1612 description: str
1613 usage: TaskUsage
1614 uuid: str
1615 session_id: str
1616 tool_use_id: str | None = None
1617 last_tool_name: str | None = None
1618```
1619
1620| Campo | Tipo | Descrizione |
1621| :--------------- | :------------ | :-------------------------------------------------- |
1622| `task_id` | `str` | Identificatore univoco per l'attività |
1623| `description` | `str` | Descrizione dello stato corrente |
1624| `usage` | `TaskUsage` | Utilizzo dei token per questa attività finora |
1625| `uuid` | `str` | Identificatore di messaggio univoco |
1626| `session_id` | `str` | Identificatore di sessione |
1627| `tool_use_id` | `str \| None` | ID di utilizzo dello strumento associato |
1628| `last_tool_name` | `str \| None` | Nome dell'ultimo strumento utilizzato dall'attività |
1629
1630### `TaskNotificationMessage`
1631
1632Emesso 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.
1633
1634```python theme={null}
1635@dataclass
1636class TaskNotificationMessage(SystemMessage):
1637 task_id: str
1638 status: TaskNotificationStatus # "completed" | "failed" | "stopped"
1639 output_file: str
1640 summary: str
1641 uuid: str
1642 session_id: str
1643 tool_use_id: str | None = None
1644 usage: TaskUsage | None = None
1645```
1646
1647| Campo | Tipo | Descrizione |
1648| :------------ | :----------------------- | :---------------------------------------------- |
1649| `task_id` | `str` | Identificatore univoco per l'attività |
1650| `status` | `TaskNotificationStatus` | Uno di `"completed"`, `"failed"`, o `"stopped"` |
1651| `output_file` | `str` | Percorso al file di output dell'attività |
1652| `summary` | `str` | Riepilogo del risultato dell'attività |
1653| `uuid` | `str` | Identificatore di messaggio univoco |
1654| `session_id` | `str` | Identificatore di sessione |
1655| `tool_use_id` | `str \| None` | ID di utilizzo dello strumento associato |
1656| `usage` | `TaskUsage \| None` | Utilizzo dei token finale per l'attività |
1657
1658## Tipi di blocco di contenuto
1659
1660### `ContentBlock`
1661
1662Tipo di unione di tutti i blocchi di contenuto.
1663
1664```python theme={null}
1665ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock
1666```
1667
1668### `TextBlock`
1669
1670Blocco di contenuto di testo.
1671
1672```python theme={null}
1673@dataclass
1674class TextBlock:
1675 text: str
1676```
1677
1678### `ThinkingBlock`
1679
1680Blocco di contenuto di pensiero (per modelli con capacità di pensiero).
1681
1682```python theme={null}
1683@dataclass
1684class ThinkingBlock:
1685 thinking: str
1686 signature: str
1687```
1688
1689### `ToolUseBlock`
1690
1691Blocco di richiesta di utilizzo dello strumento.
1692
1693```python theme={null}
1694@dataclass
1695class ToolUseBlock:
1696 id: str
1697 name: str
1698 input: dict[str, Any]
1699```
1700
1701### `ToolResultBlock`
1702
1703Blocco di risultato dell'esecuzione dello strumento.
1704
1705```python theme={null}
1706@dataclass
1707class ToolResultBlock:
1708 tool_use_id: str
1709 content: str | list[dict[str, Any]] | None = None
1710 is_error: bool | None = None
1711```
1712
1713## Tipi di errore
1714
1715### `ClaudeSDKError`
1716
1717Classe di eccezione base per tutti gli errori dell'SDK.
1718
1719```python theme={null}
1720class ClaudeSDKError(Exception):
1721 """Base error for Claude SDK."""
1722```
1723
1724### `CLINotFoundError`
1725
1726Generato quando Claude Code CLI non è installato o non viene trovato.
1727
1728```python theme={null}
1729class CLINotFoundError(CLIConnectionError):
1730 def __init__(
1731 self, message: str = "Claude Code not found", cli_path: str | None = None
1732 ):
1733 """
1734 Args:
1735 message: Error message (default: "Claude Code not found")
1736 cli_path: Optional path to the CLI that was not found
1737 """
1738```
1739
1740### `CLIConnectionError`
1741
1742Generato quando la connessione a Claude Code fallisce.
1743
1744```python theme={null}
1745class CLIConnectionError(ClaudeSDKError):
1746 """Failed to connect to Claude Code."""
1747```
1748
1749### `ProcessError`
1750
1751Generato quando il processo Claude Code fallisce.
1752
1753```python theme={null}
1754class ProcessError(ClaudeSDKError):
1755 def __init__(
1756 self, message: str, exit_code: int | None = None, stderr: str | None = None
1757 ):
1758 self.exit_code = exit_code
1759 self.stderr = stderr
1760```
1761
1762### `CLIJSONDecodeError`
1763
1764Generato quando l'analisi JSON fallisce.
1765
1766```python theme={null}
1767class CLIJSONDecodeError(ClaudeSDKError):
1768 def __init__(self, line: str, original_error: Exception):
1769 """
1770 Args:
1771 line: The line that failed to parse
1772 original_error: The original JSON decode exception
1773 """
1774 self.line = line
1775 self.original_error = original_error
1776```
1777
1778## Tipi di Hook
1779
1780Per una guida completa sull'utilizzo degli hooks con esempi e modelli comuni, vedi la [guida Hooks](/it/agent-sdk/hooks).
1781
1782### `HookEvent`
1783
1784Tipi di evento hook supportati.
1785
1786```python theme={null}
1787HookEvent = Literal[
1788 "PreToolUse", # Called before tool execution
1789 "PostToolUse", # Called after tool execution
1790 "PostToolUseFailure", # Called when a tool execution fails
1791 "UserPromptSubmit", # Called when user submits a prompt
1792 "Stop", # Called when stopping execution
1793 "SubagentStop", # Called when a subagent stops
1794 "PreCompact", # Called before message compaction
1795 "Notification", # Called for notification events
1796 "SubagentStart", # Called when a subagent starts
1797 "PermissionRequest", # Called when a permission decision is needed
1798]
1799```
1800
1801<Note>
1802 TypeScript SDK supporta eventi hook aggiuntivi non ancora disponibili in Python: `SessionStart`, `SessionEnd`, `Setup`, `TeammateIdle`, `TaskCompleted`, `ConfigChange`, `WorktreeCreate`, `WorktreeRemove`, e `PostToolBatch`.
1803</Note>
1804
1805### `HookCallback`
1806
1807Definizione di tipo per le funzioni di callback hook.
1808
1809```python theme={null}
1810HookCallback = Callable[[HookInput, str | None, HookContext], Awaitable[HookJSONOutput]]
1811```
1812
1813Parametri:
1814
1815* `input`: Input hook fortemente tipizzato con unioni discriminate basate su `hook_event_name` (vedi [`HookInput`](#hook-input))
1816* `tool_use_id`: Identificatore di utilizzo dello strumento opzionale (per hook correlati allo strumento)
1817* `context`: Contesto hook con informazioni aggiuntive
1818
1819Restituisce un [`HookJSONOutput`](#hook-json-output) che può contenere:
1820
1821* `decision`: `"block"` per bloccare l'azione
1822* `systemMessage`: Messaggio di sistema da aggiungere al trascritto
1823* `hookSpecificOutput`: Dati di output specifici dell'hook
1824
1825### `HookContext`
1826
1827Informazioni di contesto passate ai callback hook.
1828
1829```python theme={null}
1830class HookContext(TypedDict):
1831 signal: Any | None # Future: abort signal support
1832```
1833
1834### `HookMatcher`
1835
1836Configurazione per l'abbinamento degli hook a eventi o strumenti specifici.
1837
1838```python theme={null}
1839@dataclass
1840class HookMatcher:
1841 matcher: str | None = (
1842 None # Tool name or pattern to match (e.g., "Bash", "Write|Edit")
1843 )
1844 hooks: list[HookCallback] = field(
1845 default_factory=list
1846 ) # List of callbacks to execute
1847 timeout: float | None = (
1848 None # Timeout in seconds for all hooks in this matcher (default: 60)
1849 )
1850```
1851
1852### `HookInput`
1853
1854Tipo di unione di tutti i tipi di input hook. Il tipo effettivo dipende dal campo `hook_event_name`.
1855
1856```python theme={null}
1857HookInput = (
1858 PreToolUseHookInput
1859 | PostToolUseHookInput
1860 | PostToolUseFailureHookInput
1861 | UserPromptSubmitHookInput
1862 | StopHookInput
1863 | SubagentStopHookInput
1864 | PreCompactHookInput
1865 | NotificationHookInput
1866 | SubagentStartHookInput
1867 | PermissionRequestHookInput
1868)
1869```
1870
1871### `BaseHookInput`
1872
1873Campi di base presenti in tutti i tipi di input hook.
1874
1875```python theme={null}
1876class BaseHookInput(TypedDict):
1877 session_id: str
1878 transcript_path: str
1879 cwd: str
1880 permission_mode: NotRequired[str]
1881```
1882
1883| Campo | Tipo | Descrizione |
1884| :---------------- | :---------------- | :-------------------------------------------- |
1885| `session_id` | `str` | Identificatore di sessione corrente |
1886| `transcript_path` | `str` | Percorso al file di trascritto della sessione |
1887| `cwd` | `str` | Directory di lavoro corrente |
1888| `permission_mode` | `str` (opzionale) | Modalità di autorizzazione corrente |
1889
1890### `PreToolUseHookInput`
1891
1892Dati di input per gli eventi hook `PreToolUse`.
1893
1894```python theme={null}
1895class PreToolUseHookInput(BaseHookInput):
1896 hook_event_name: Literal["PreToolUse"]
1897 tool_name: str
1898 tool_input: dict[str, Any]
1899 tool_use_id: str
1900 agent_id: NotRequired[str]
1901 agent_type: NotRequired[str]
1902```
1903
1904| Campo | Tipo | Descrizione |
1905| :---------------- | :---------------------- | :----------------------------------------------------------------------------------------- |
1906| `hook_event_name` | `Literal["PreToolUse"]` | Sempre "PreToolUse" |
1907| `tool_name` | `str` | Nome dello strumento che sta per essere eseguito |
1908| `tool_input` | `dict[str, Any]` | Parametri di input per lo strumento |
1909| `tool_use_id` | `str` | Identificatore univoco per questo utilizzo dello strumento |
1910| `agent_id` | `str` (opzionale) | Identificatore del subagente, presente quando l'hook si attiva all'interno di un subagente |
1911| `agent_type` | `str` (opzionale) | Tipo di subagente, presente quando l'hook si attiva all'interno di un subagente |
1912
1913### `PostToolUseHookInput`
1914
1915Dati di input per gli eventi hook `PostToolUse`.
1916
1917```python theme={null}
1918class PostToolUseHookInput(BaseHookInput):
1919 hook_event_name: Literal["PostToolUse"]
1920 tool_name: str
1921 tool_input: dict[str, Any]
1922 tool_response: Any
1923 tool_use_id: str
1924 agent_id: NotRequired[str]
1925 agent_type: NotRequired[str]
1926```
1927
1928| Campo | Tipo | Descrizione |
1929| :---------------- | :----------------------- | :----------------------------------------------------------------------------------------- |
1930| `hook_event_name` | `Literal["PostToolUse"]` | Sempre "PostToolUse" |
1931| `tool_name` | `str` | Nome dello strumento che è stato eseguito |
1932| `tool_input` | `dict[str, Any]` | Parametri di input che sono stati utilizzati |
1933| `tool_response` | `Any` | Risposta dall'esecuzione dello strumento |
1934| `tool_use_id` | `str` | Identificatore univoco per questo utilizzo dello strumento |
1935| `agent_id` | `str` (opzionale) | Identificatore del subagente, presente quando l'hook si attiva all'interno di un subagente |
1936| `agent_type` | `str` (opzionale) | Tipo di subagente, presente quando l'hook si attiva all'interno di un subagente |
1937
1938### `PostToolUseFailureHookInput`
1939
1940Dati di input per gli eventi hook `PostToolUseFailure`. Chiamato quando l'esecuzione di uno strumento fallisce.
1941
1942```python theme={null}
1943class PostToolUseFailureHookInput(BaseHookInput):
1944 hook_event_name: Literal["PostToolUseFailure"]
1945 tool_name: str
1946 tool_input: dict[str, Any]
1947 tool_use_id: str
1948 error: str
1949 is_interrupt: NotRequired[bool]
1950 agent_id: NotRequired[str]
1951 agent_type: NotRequired[str]
1952```
1953
1954| Campo | Tipo | Descrizione |
1955| :---------------- | :------------------------------ | :----------------------------------------------------------------------------------------- |
1956| `hook_event_name` | `Literal["PostToolUseFailure"]` | Sempre "PostToolUseFailure" |
1957| `tool_name` | `str` | Nome dello strumento che ha fallito |
1958| `tool_input` | `dict[str, Any]` | Parametri di input che sono stati utilizzati |
1959| `tool_use_id` | `str` | Identificatore univoco per questo utilizzo dello strumento |
1960| `error` | `str` | Messaggio di errore dall'esecuzione fallita |
1961| `is_interrupt` | `bool` (opzionale) | Se il fallimento è stato causato da un'interruzione |
1962| `agent_id` | `str` (opzionale) | Identificatore del subagente, presente quando l'hook si attiva all'interno di un subagente |
1963| `agent_type` | `str` (opzionale) | Tipo di subagente, presente quando l'hook si attiva all'interno di un subagente |
1964
1965### `UserPromptSubmitHookInput`
1966
1967Dati di input per gli eventi hook `UserPromptSubmit`.
1968
1969```python theme={null}
1970class UserPromptSubmitHookInput(BaseHookInput):
1971 hook_event_name: Literal["UserPromptSubmit"]
1972 prompt: str
1973```
1974
1975| Campo | Tipo | Descrizione |
1976| :---------------- | :---------------------------- | :---------------------------- |
1977| `hook_event_name` | `Literal["UserPromptSubmit"]` | Sempre "UserPromptSubmit" |
1978| `prompt` | `str` | Il prompt inviato dall'utente |
1979
1980### `StopHookInput`
1981
1982Dati di input per gli eventi hook `Stop`.
1983
1984```python theme={null}
1985class StopHookInput(BaseHookInput):
1986 hook_event_name: Literal["Stop"]
1987 stop_hook_active: bool
1988```
1989
1990| Campo | Tipo | Descrizione |
1991| :----------------- | :---------------- | :---------------------------- |
1992| `hook_event_name` | `Literal["Stop"]` | Sempre "Stop" |
1993| `stop_hook_active` | `bool` | Se l'hook di arresto è attivo |
1994
1995### `SubagentStopHookInput`
1996
1997Dati di input per gli eventi hook `SubagentStop`.
1998
1999```python theme={null}
2000class SubagentStopHookInput(BaseHookInput):
2001 hook_event_name: Literal["SubagentStop"]
2002 stop_hook_active: bool
2003 agent_id: str
2004 agent_transcript_path: str
2005 agent_type: str
2006```
2007
2008| Campo | Tipo | Descrizione |
2009| :---------------------- | :------------------------ | :------------------------------------------- |
2010| `hook_event_name` | `Literal["SubagentStop"]` | Sempre "SubagentStop" |
2011| `stop_hook_active` | `bool` | Se l'hook di arresto è attivo |
2012| `agent_id` | `str` | Identificatore univoco per il subagente |
2013| `agent_transcript_path` | `str` | Percorso al file di trascritto del subagente |
2014| `agent_type` | `str` | Tipo del subagente |
2015
2016### `PreCompactHookInput`
2017
2018Dati di input per gli eventi hook `PreCompact`.
2019
2020```python theme={null}
2021class PreCompactHookInput(BaseHookInput):
2022 hook_event_name: Literal["PreCompact"]
2023 trigger: Literal["manual", "auto"]
2024 custom_instructions: str | None
2025```
2026
2027| Campo | Tipo | Descrizione |
2028| :-------------------- | :-------------------------- | :--------------------------------------------- |
2029| `hook_event_name` | `Literal["PreCompact"]` | Sempre "PreCompact" |
2030| `trigger` | `Literal["manual", "auto"]` | Cosa ha attivato la compattazione |
2031| `custom_instructions` | `str \| None` | Istruzioni personalizzate per la compattazione |
2032
2033### `NotificationHookInput`
2034
2035Dati di input per gli eventi hook `Notification`.
2036
2037```python theme={null}
2038class NotificationHookInput(BaseHookInput):
2039 hook_event_name: Literal["Notification"]
2040 message: str
2041 title: NotRequired[str]
2042 notification_type: str
2043```
2044
2045| Campo | Tipo | Descrizione |
2046| :------------------ | :------------------------ | :---------------------------------- |
2047| `hook_event_name` | `Literal["Notification"]` | Sempre "Notification" |
2048| `message` | `str` | Contenuto del messaggio di notifica |
2049| `title` | `str` (opzionale) | Titolo della notifica |
2050| `notification_type` | `str` | Tipo di notifica |
2051
2052### `SubagentStartHookInput`
2053
2054Dati di input per gli eventi hook `SubagentStart`.
2055
2056```python theme={null}
2057class SubagentStartHookInput(BaseHookInput):
2058 hook_event_name: Literal["SubagentStart"]
2059 agent_id: str
2060 agent_type: str
2061```
2062
2063| Campo | Tipo | Descrizione |
2064| :---------------- | :------------------------- | :-------------------------------------- |
2065| `hook_event_name` | `Literal["SubagentStart"]` | Sempre "SubagentStart" |
2066| `agent_id` | `str` | Identificatore univoco per il subagente |
2067| `agent_type` | `str` | Tipo del subagente |
2068
2069### `PermissionRequestHookInput`
2070
2071Dati di input per gli eventi hook `PermissionRequest`. Consente agli hook di gestire le decisioni di autorizzazione a livello di programmazione.
2072
2073```python theme={null}
2074class PermissionRequestHookInput(BaseHookInput):
2075 hook_event_name: Literal["PermissionRequest"]
2076 tool_name: str
2077 tool_input: dict[str, Any]
2078 permission_suggestions: NotRequired[list[Any]]
2079```
2080
2081| Campo | Tipo | Descrizione |
2082| :----------------------- | :----------------------------- | :-------------------------------------------------- |
2083| `hook_event_name` | `Literal["PermissionRequest"]` | Sempre "PermissionRequest" |
2084| `tool_name` | `str` | Nome dello strumento che richiede l'autorizzazione |
2085| `tool_input` | `dict[str, Any]` | Parametri di input per lo strumento |
2086| `permission_suggestions` | `list[Any]` (opzionale) | Aggiornamenti di autorizzazione suggeriti dalla CLI |
2087
2088### `HookJSONOutput`
2089
2090Tipo di unione per i valori di ritorno del callback hook.
2091
2092```python theme={null}
2093HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput
2094```
2095
2096#### `SyncHookJSONOutput`
2097
2098Output hook sincrono con campi di controllo e decisione.
2099
2100```python theme={null}
2101class SyncHookJSONOutput(TypedDict):
2102 # Control fields
2103 continue_: NotRequired[bool] # Whether to proceed (default: True)
2104 suppressOutput: NotRequired[bool] # Hide stdout from transcript
2105 stopReason: NotRequired[str] # Message when continue is False
2106
2107 # Decision fields
2108 decision: NotRequired[Literal["block"]]
2109 systemMessage: NotRequired[str] # Warning message for user
2110 reason: NotRequired[str] # Feedback for Claude
2111
2112 # Hook-specific output
2113 hookSpecificOutput: NotRequired[HookSpecificOutput]
2114```
2115
2116<Note>
2117 Usa `continue_` (con underscore) nel codice Python. Viene automaticamente convertito a `continue` quando inviato alla CLI.
2118</Note>
2119
2120#### `HookSpecificOutput`
2121
2122Un `TypedDict` contenente il nome dell'evento hook e i campi specifici dell'evento. La forma dipende dal valore `hookEventName`. Per i dettagli completi sui campi disponibili per evento hook, vedi [Controlla l'esecuzione con gli hooks](/it/agent-sdk/hooks#outputs).
2123
2124Un'unione discriminata di tipi di output specifici dell'evento. Il campo `hookEventName` determina quali campi sono validi.
2125
2126```python theme={null}
2127class PreToolUseHookSpecificOutput(TypedDict):
2128 hookEventName: Literal["PreToolUse"]
2129 permissionDecision: NotRequired[Literal["allow", "deny", "ask"]]
2130 permissionDecisionReason: NotRequired[str]
2131 updatedInput: NotRequired[dict[str, Any]]
2132 additionalContext: NotRequired[str]
2133
2134
2135class PostToolUseHookSpecificOutput(TypedDict):
2136 hookEventName: Literal["PostToolUse"]
2137 additionalContext: NotRequired[str]
2138 updatedMCPToolOutput: NotRequired[Any]
2139
2140
2141class PostToolUseFailureHookSpecificOutput(TypedDict):
2142 hookEventName: Literal["PostToolUseFailure"]
2143 additionalContext: NotRequired[str]
2144
2145
2146class UserPromptSubmitHookSpecificOutput(TypedDict):
2147 hookEventName: Literal["UserPromptSubmit"]
2148 additionalContext: NotRequired[str]
2149
2150
2151class NotificationHookSpecificOutput(TypedDict):
2152 hookEventName: Literal["Notification"]
2153 additionalContext: NotRequired[str]
2154
2155
2156class SubagentStartHookSpecificOutput(TypedDict):
2157 hookEventName: Literal["SubagentStart"]
2158 additionalContext: NotRequired[str]
2159
2160
2161class PermissionRequestHookSpecificOutput(TypedDict):
2162 hookEventName: Literal["PermissionRequest"]
2163 decision: dict[str, Any]
2164
2165
2166HookSpecificOutput = (
2167 PreToolUseHookSpecificOutput
2168 | PostToolUseHookSpecificOutput
2169 | PostToolUseFailureHookSpecificOutput
2170 | UserPromptSubmitHookSpecificOutput
2171 | NotificationHookSpecificOutput
2172 | SubagentStartHookSpecificOutput
2173 | PermissionRequestHookSpecificOutput
2174)
2175```
2176
2177#### `AsyncHookJSONOutput`
2178
2179Output hook asincrono che rinvia l'esecuzione dell'hook.
2180
2181```python theme={null}
2182class AsyncHookJSONOutput(TypedDict):
2183 async_: Literal[True] # Set to True to defer execution
2184 asyncTimeout: NotRequired[int] # Timeout in milliseconds
2185```
2186
2187<Note>
2188 Usa `async_` (con underscore) nel codice Python. Viene automaticamente convertito a `async` quando inviato alla CLI.
2189</Note>
2190
2191### Esempio di utilizzo di Hook
2192
2193Questo 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.
2194
2195```python theme={null}
2196from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, HookContext
2197from typing import Any
2198
2199
2200async def validate_bash_command(
2201 input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
2202) -> dict[str, Any]:
2203 """Validate and potentially block dangerous bash commands."""
2204 if input_data["tool_name"] == "Bash":
2205 command = input_data["tool_input"].get("command", "")
2206 if "rm -rf /" in command:
2207 return {
2208 "hookSpecificOutput": {
2209 "hookEventName": "PreToolUse",
2210 "permissionDecision": "deny",
2211 "permissionDecisionReason": "Dangerous command blocked",
2212 }
2213 }
2214 return {}
2215
2216
2217async def log_tool_use(
2218 input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
2219) -> dict[str, Any]:
2220 """Log all tool usage for auditing."""
2221 print(f"Tool used: {input_data.get('tool_name')}")
2222 return {}
2223
2224
2225options = ClaudeAgentOptions(
2226 hooks={
2227 "PreToolUse": [
2228 HookMatcher(
2229 matcher="Bash", hooks=[validate_bash_command], timeout=120
2230 ), # 2 min for validation
2231 HookMatcher(
2232 hooks=[log_tool_use]
2233 ), # Applies to all tools (default 60s timeout)
2234 ],
2235 "PostToolUse": [HookMatcher(hooks=[log_tool_use])],
2236 }
2237)
2238
2239async for message in query(prompt="Analyze this codebase", options=options):
2240 print(message)
2241```
2242
2243## Tipi di input/output dello strumento
2244
2245Documentazione 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.
2246
2247### Agent
2248
2249**Nome dello strumento:** `Agent` (precedentemente `Task`, che è ancora accettato come alias)
2250
2251**Input:**
2252
2253```python theme={null}
2254{
2255 "description": str, # A short (3-5 word) description of the task
2256 "prompt": str, # The task for the agent to perform
2257 "subagent_type": str, # The type of specialized agent to use
2258}
2259```
2260
2261**Output:**
2262
2263```python theme={null}
2264{
2265 "result": str, # Final result from the subagent
2266 "usage": dict | None, # Token usage statistics
2267 "total_cost_usd": float | None, # Estimated total cost in USD
2268 "duration_ms": int | None, # Execution duration in milliseconds
2269}
2270```
2271
2272### AskUserQuestion
2273
2274**Nome dello strumento:** `AskUserQuestion`
2275
2276Chiede all'utente domande di chiarimento durante l'esecuzione. Vedi [Gestisci approvazioni e input dell'utente](/it/agent-sdk/user-input#handle-clarifying-questions) per i dettagli di utilizzo.
2277
2278**Input:**
2279
2280```python theme={null}
2281{
2282 "questions": [ # Questions to ask the user (1-4 questions)
2283 {
2284 "question": str, # The complete question to ask the user
2285 "header": str, # Very short label displayed as a chip/tag (max 12 chars)
2286 "options": [ # The available choices (2-4 options)
2287 {
2288 "label": str, # Display text for this option (1-5 words)
2289 "description": str, # Explanation of what this option means
2290 }
2291 ],
2292 "multiSelect": bool, # Set to true to allow multiple selections
2293 }
2294 ],
2295 "answers": dict | None, # User answers populated by the permission system
2296}
2297```
2298
2299**Output:**
2300
2301```python theme={null}
2302{
2303 "questions": [ # The questions that were asked
2304 {
2305 "question": str,
2306 "header": str,
2307 "options": [{"label": str, "description": str}],
2308 "multiSelect": bool,
2309 }
2310 ],
2311 "answers": dict[str, str], # Maps question text to answer string
2312 # Multi-select answers are comma-separated
2313}
2314```
2315
2316### Bash
2317
2318**Nome dello strumento:** `Bash`
2319
2320**Input:**
2321
2322```python theme={null}
2323{
2324 "command": str, # The command to execute
2325 "timeout": int | None, # Optional timeout in milliseconds (max 600000)
2326 "description": str | None, # Clear, concise description (5-10 words)
2327 "run_in_background": bool | None, # Set to true to run in background
2328}
2329```
2330
2331**Output:**
2332
2333```python theme={null}
2334{
2335 "output": str, # Combined stdout and stderr output
2336 "exitCode": int, # Exit code of the command
2337 "killed": bool | None, # Whether command was killed due to timeout
2338 "shellId": str | None, # Shell ID for background processes
2339}
2340```
2341
2342### Monitor
2343
2344**Nome dello strumento:** `Monitor`
2345
2346Esegue uno script in background e fornisce ogni riga stdout a Claude come evento in modo che possa reagire senza polling. Monitor segue le stesse regole di autorizzazione di Bash. Vedi il [riferimento dello strumento Monitor](/it/tools-reference#monitor-tool) per il comportamento e la disponibilità del provider.
2347
2348**Input:**
2349
2350```python theme={null}
2351{
2352 "command": str, # Shell script; each stdout line is an event, exit ends the watch
2353 "description": str, # Short description shown in notifications
2354 "timeout_ms": int | None, # Kill after this deadline (default 300000, max 3600000)
2355 "persistent": bool | None, # Run for the lifetime of the session; stop with TaskStop
2356}
2357```
2358
2359**Output:**
2360
2361```python theme={null}
2362{
2363 "taskId": str, # ID of the background monitor task
2364 "timeoutMs": int, # Timeout deadline in milliseconds (0 when persistent)
2365 "persistent": bool | None, # True when running until TaskStop or session end
2366}
2367```
2368
2369### Edit
2370
2371**Nome dello strumento:** `Edit`
2372
2373**Input:**
2374
2375```python theme={null}
2376{
2377 "file_path": str, # The absolute path to the file to modify
2378 "old_string": str, # The text to replace
2379 "new_string": str, # The text to replace it with
2380 "replace_all": bool | None, # Replace all occurrences (default False)
2381}
2382```
2383
2384**Output:**
2385
2386```python theme={null}
2387{
2388 "message": str, # Confirmation message
2389 "replacements": int, # Number of replacements made
2390 "file_path": str, # File path that was edited
2391}
2392```
2393
2394### Read
2395
2396**Nome dello strumento:** `Read`
2397
2398**Input:**
2399
2400```python theme={null}
2401{
2402 "file_path": str, # The absolute path to the file to read
2403 "offset": int | None, # The line number to start reading from
2404 "limit": int | None, # The number of lines to read
2405}
2406```
2407
2408**Output (File di testo):**
2409
2410```python theme={null}
2411{
2412 "content": str, # File contents with line numbers
2413 "total_lines": int, # Total number of lines in file
2414 "lines_returned": int, # Lines actually returned
2415}
2416```
2417
2418**Output (Immagini):**
2419
2420```python theme={null}
2421{
2422 "image": str, # Base64 encoded image data
2423 "mime_type": str, # Image MIME type
2424 "file_size": int, # File size in bytes
2425}
2426```
2427
2428### Write
2429
2430**Nome dello strumento:** `Write`
2431
2432**Input:**
2433
2434```python theme={null}
2435{
2436 "file_path": str, # The absolute path to the file to write
2437 "content": str, # The content to write to the file
2438}
2439```
2440
2441**Output:**
2442
2443```python theme={null}
2444{
2445 "message": str, # Success message
2446 "bytes_written": int, # Number of bytes written
2447 "file_path": str, # File path that was written
2448}
2449```
2450
2451### Glob
2452
2453**Nome dello strumento:** `Glob`
2454
2455**Input:**
2456
2457```python theme={null}
2458{
2459 "pattern": str, # The glob pattern to match files against
2460 "path": str | None, # The directory to search in (defaults to cwd)
2461}
2462```
2463
2464**Output:**
2465
2466```python theme={null}
2467{
2468 "matches": list[str], # Array of matching file paths
2469 "count": int, # Number of matches found
2470 "search_path": str, # Search directory used
2471}
2472```
2473
2474### Grep
2475
2476**Nome dello strumento:** `Grep`
2477
2478**Input:**
2479
2480```python theme={null}
2481{
2482 "pattern": str, # The regular expression pattern
2483 "path": str | None, # File or directory to search in
2484 "glob": str | None, # Glob pattern to filter files
2485 "type": str | None, # File type to search
2486 "output_mode": str | None, # "content", "files_with_matches", or "count"
2487 "-i": bool | None, # Case insensitive search
2488 "-n": bool | None, # Show line numbers
2489 "-B": int | None, # Lines to show before each match
2490 "-A": int | None, # Lines to show after each match
2491 "-C": int | None, # Lines to show before and after
2492 "head_limit": int | None, # Limit output to first N lines/entries
2493 "multiline": bool | None, # Enable multiline mode
2494}
2495```
2496
2497**Output (modalità content):**
2498
2499```python theme={null}
2500{
2501 "matches": [
2502 {
2503 "file": str,
2504 "line_number": int | None,
2505 "line": str,
2506 "before_context": list[str] | None,
2507 "after_context": list[str] | None,
2508 }
2509 ],
2510 "total_matches": int,
2511}
2512```
2513
2514**Output (modalità files\_with\_matches):**
2515
2516```python theme={null}
2517{
2518 "files": list[str], # Files containing matches
2519 "count": int, # Number of files with matches
2520}
2521```
2522
2523### NotebookEdit
2524
2525**Nome dello strumento:** `NotebookEdit`
2526
2527**Input:**
2528
2529```python theme={null}
2530{
2531 "notebook_path": str, # Absolute path to the Jupyter notebook
2532 "cell_id": str | None, # The ID of the cell to edit
2533 "new_source": str, # The new source for the cell
2534 "cell_type": "code" | "markdown" | None, # The type of the cell
2535 "edit_mode": "replace" | "insert" | "delete" | None, # Edit operation type
2536}
2537```
2538
2539**Output:**
2540
2541```python theme={null}
2542{
2543 "message": str, # Success message
2544 "edit_type": "replaced" | "inserted" | "deleted", # Type of edit performed
2545 "cell_id": str | None, # Cell ID that was affected
2546 "total_cells": int, # Total cells in notebook after edit
2547}
2548```
2549
2550### WebFetch
2551
2552**Nome dello strumento:** `WebFetch`
2553
2554**Input:**
2555
2556```python theme={null}
2557{
2558 "url": str, # The URL to fetch content from
2559 "prompt": str, # The prompt to run on the fetched content
2560}
2561```
2562
2563**Output:**
2564
2565```python theme={null}
2566{
2567 "response": str, # AI model's response to the prompt
2568 "url": str, # URL that was fetched
2569 "final_url": str | None, # Final URL after redirects
2570 "status_code": int | None, # HTTP status code
2571}
2572```
2573
2574### WebSearch
2575
2576**Nome dello strumento:** `WebSearch`
2577
2578**Input:**
2579
2580```python theme={null}
2581{
2582 "query": str, # The search query to use
2583 "allowed_domains": list[str] | None, # Only include results from these domains
2584 "blocked_domains": list[str] | None, # Never include results from these domains
2585}
2586```
2587
2588**Output:**
2589
2590```python theme={null}
2591{
2592 "results": [{"title": str, "url": str, "snippet": str, "metadata": dict | None}],
2593 "total_results": int,
2594 "query": str,
2595}
2596```
2597
2598### TodoWrite
2599
2600**Nome dello strumento:** `TodoWrite`
2601
2602**Input:**
2603
2604```python theme={null}
2605{
2606 "todos": [
2607 {
2608 "content": str, # The task description
2609 "status": "pending" | "in_progress" | "completed", # Task status
2610 "activeForm": str, # Active form of the description
2611 }
2612 ]
2613}
2614```
2615
2616**Output:**
2617
2618```python theme={null}
2619{
2620 "message": str, # Success message
2621 "stats": {"total": int, "pending": int, "in_progress": int, "completed": int},
2622}
2623```
2624
2625### BashOutput
2626
2627**Nome dello strumento:** `BashOutput`
2628
2629**Input:**
2630
2631```python theme={null}
2632{
2633 "bash_id": str, # The ID of the background shell
2634 "filter": str | None, # Optional regex to filter output lines
2635}
2636```
2637
2638**Output:**
2639
2640```python theme={null}
2641{
2642 "output": str, # New output since last check
2643 "status": "running" | "completed" | "failed", # Current shell status
2644 "exitCode": int | None, # Exit code when completed
2645}
2646```
2647
2648### KillBash
2649
2650**Nome dello strumento:** `KillBash`
2651
2652**Input:**
2653
2654```python theme={null}
2655{
2656 "shell_id": str # The ID of the background shell to kill
2657}
2658```
2659
2660**Output:**
2661
2662```python theme={null}
2663{
2664 "message": str, # Success message
2665 "shell_id": str, # ID of the killed shell
2666}
2667```
2668
2669### ExitPlanMode
2670
2671**Nome dello strumento:** `ExitPlanMode`
2672
2673**Input:**
2674
2675```python theme={null}
2676{
2677 "plan": str # The plan to run by the user for approval
2678}
2679```
2680
2681**Output:**
2682
2683```python theme={null}
2684{
2685 "message": str, # Confirmation message
2686 "approved": bool | None, # Whether user approved the plan
2687}
2688```
2689
2690### ListMcpResources
2691
2692**Nome dello strumento:** `ListMcpResources`
2693
2694**Input:**
2695
2696```python theme={null}
2697{
2698 "server": str | None # Optional server name to filter resources by
2699}
2700```
2701
2702**Output:**
2703
2704```python theme={null}
2705{
2706 "resources": [
2707 {
2708 "uri": str,
2709 "name": str,
2710 "description": str | None,
2711 "mimeType": str | None,
2712 "server": str,
2713 }
2714 ],
2715 "total": int,
2716}
2717```
2718
2719### ReadMcpResource
2720
2721**Nome dello strumento:** `ReadMcpResource`
2722
2723**Input:**
2724
2725```python theme={null}
2726{
2727 "server": str, # The MCP server name
2728 "uri": str, # The resource URI to read
2729}
2730```
2731
2732**Output:**
2733
2734```python theme={null}
2735{
2736 "contents": [
2737 {"uri": str, "mimeType": str | None, "text": str | None, "blob": str | None}
2738 ],
2739 "server": str,
2740}
2741```
2742
2743## Funzionalità avanzate con ClaudeSDKClient
2744
2745### Costruire un'interfaccia di conversazione continua
2746
2747```python theme={null}
2748from claude_agent_sdk import (
2749 ClaudeSDKClient,
2750 ClaudeAgentOptions,
2751 AssistantMessage,
2752 TextBlock,
2753)
2754import asyncio
2755
2756
2757class ConversationSession:
2758 """Maintains a single conversation session with Claude."""
2759
2760 def __init__(self, options: ClaudeAgentOptions | None = None):
2761 self.client = ClaudeSDKClient(options)
2762 self.turn_count = 0
2763
2764 async def start(self):
2765 await self.client.connect()
2766 print("Starting conversation session. Claude will remember context.")
2767 print(
2768 "Commands: 'exit' to quit, 'interrupt' to stop current task, 'new' for new session"
2769 )
2770
2771 while True:
2772 user_input = input(f"\n[Turn {self.turn_count + 1}] You: ")
2773
2774 if user_input.lower() == "exit":
2775 break
2776 elif user_input.lower() == "interrupt":
2777 await self.client.interrupt()
2778 print("Task interrupted!")
2779 continue
2780 elif user_input.lower() == "new":
2781 # Disconnect and reconnect for a fresh session
2782 await self.client.disconnect()
2783 await self.client.connect()
2784 self.turn_count = 0
2785 print("Started new conversation session (previous context cleared)")
2786 continue
2787
2788 # Send message - the session retains all previous messages
2789 await self.client.query(user_input)
2790 self.turn_count += 1
2791
2792 # Process response
2793 print(f"[Turn {self.turn_count}] Claude: ", end="")
2794 async for message in self.client.receive_response():
2795 if isinstance(message, AssistantMessage):
2796 for block in message.content:
2797 if isinstance(block, TextBlock):
2798 print(block.text, end="")
2799 print() # New line after response
2800
2801 await self.client.disconnect()
2802 print(f"Conversation ended after {self.turn_count} turns.")
2803
2804
2805async def main():
2806 options = ClaudeAgentOptions(
2807 allowed_tools=["Read", "Write", "Bash"], permission_mode="acceptEdits"
2808 )
2809 session = ConversationSession(options)
2810 await session.start()
2811
2812
2813# Example conversation:
2814# Turn 1 - You: "Create a file called hello.py"
2815# Turn 1 - Claude: "I'll create a hello.py file for you..."
2816# Turn 2 - You: "What's in that file?"
2817# Turn 2 - Claude: "The hello.py file I just created contains..." (remembers!)
2818# Turn 3 - You: "Add a main function to it"
2819# Turn 3 - Claude: "I'll add a main function to hello.py..." (knows which file!)
2820
2821asyncio.run(main())
2822```
2823
2824### Utilizzo di Hook per la modifica del comportamento
2825
2826```python theme={null}
2827from claude_agent_sdk import (
2828 ClaudeSDKClient,
2829 ClaudeAgentOptions,
2830 HookMatcher,
2831 HookContext,
2832)
2833import asyncio
2834from typing import Any
2835
2836
2837async def pre_tool_logger(
2838 input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
2839) -> dict[str, Any]:
2840 """Log all tool usage before execution."""
2841 tool_name = input_data.get("tool_name", "unknown")
2842 print(f"[PRE-TOOL] About to use: {tool_name}")
2843
2844 # You can modify or block the tool execution here
2845 if tool_name == "Bash" and "rm -rf" in str(input_data.get("tool_input", {})):
2846 return {
2847 "hookSpecificOutput": {
2848 "hookEventName": "PreToolUse",
2849 "permissionDecision": "deny",
2850 "permissionDecisionReason": "Dangerous command blocked",
2851 }
2852 }
2853 return {}
2854
2855
2856async def post_tool_logger(
2857 input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
2858) -> dict[str, Any]:
2859 """Log results after tool execution."""
2860 tool_name = input_data.get("tool_name", "unknown")
2861 print(f"[POST-TOOL] Completed: {tool_name}")
2862 return {}
2863
2864
2865async def user_prompt_modifier(
2866 input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
2867) -> dict[str, Any]:
2868 """Add context to user prompts."""
2869 original_prompt = input_data.get("prompt", "")
2870
2871 # Add a timestamp as additional context for Claude to see
2872 from datetime import datetime
2873
2874 timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
2875
2876 return {
2877 "hookSpecificOutput": {
2878 "hookEventName": "UserPromptSubmit",
2879 "additionalContext": f"[Submitted at {timestamp}] Original prompt: {original_prompt}",
2880 }
2881 }
2882
2883
2884async def main():
2885 options = ClaudeAgentOptions(
2886 hooks={
2887 "PreToolUse": [
2888 HookMatcher(hooks=[pre_tool_logger]),
2889 HookMatcher(matcher="Bash", hooks=[pre_tool_logger]),
2890 ],
2891 "PostToolUse": [HookMatcher(hooks=[post_tool_logger])],
2892 "UserPromptSubmit": [HookMatcher(hooks=[user_prompt_modifier])],
2893 },
2894 allowed_tools=["Read", "Write", "Bash"],
2895 )
2896
2897 async with ClaudeSDKClient(options=options) as client:
2898 await client.query("List files in current directory")
2899
2900 async for message in client.receive_response():
2901 # Hooks will automatically log tool usage
2902 pass
2903
2904
2905asyncio.run(main())
2906```
2907
2908### Monitoraggio del progresso in tempo reale
2909
2910```python theme={null}
2911from claude_agent_sdk import (
2912 ClaudeSDKClient,
2913 ClaudeAgentOptions,
2914 AssistantMessage,
2915 ToolUseBlock,
2916 ToolResultBlock,
2917 TextBlock,
2918)
2919import asyncio
2920
2921
2922async def monitor_progress():
2923 options = ClaudeAgentOptions(
2924 allowed_tools=["Write", "Bash"], permission_mode="acceptEdits"
2925 )
2926
2927 async with ClaudeSDKClient(options=options) as client:
2928 await client.query("Create 5 Python files with different sorting algorithms")
2929
2930 # Monitor progress in real-time
2931 async for message in client.receive_response():
2932 if isinstance(message, AssistantMessage):
2933 for block in message.content:
2934 if isinstance(block, ToolUseBlock):
2935 if block.name == "Write":
2936 file_path = block.input.get("file_path", "")
2937 print(f"Creating: {file_path}")
2938 elif isinstance(block, ToolResultBlock):
2939 print("Completed tool execution")
2940 elif isinstance(block, TextBlock):
2941 print(f"Claude says: {block.text[:100]}...")
2942
2943 print("Task completed!")
2944
2945
2946asyncio.run(monitor_progress())
2947```
2948
2949## Utilizzo di esempio
2950
2951### Operazioni di file di base (usando query)
2952
2953```python theme={null}
2954from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock
2955import asyncio
2956
2957
2958async def create_project():
2959 options = ClaudeAgentOptions(
2960 allowed_tools=["Read", "Write", "Bash"],
2961 permission_mode="acceptEdits",
2962 cwd="/home/user/project",
2963 )
2964
2965 async for message in query(
2966 prompt="Create a Python project structure with setup.py", options=options
2967 ):
2968 if isinstance(message, AssistantMessage):
2969 for block in message.content:
2970 if isinstance(block, ToolUseBlock):
2971 print(f"Using tool: {block.name}")
2972
2973
2974asyncio.run(create_project())
2975```
2976
2977### Gestione degli errori
2978
2979```python theme={null}
2980from claude_agent_sdk import query, CLINotFoundError, ProcessError, CLIJSONDecodeError
2981
2982try:
2983 async for message in query(prompt="Hello"):
2984 print(message)
2985except CLINotFoundError:
2986 print(
2987 "Claude Code CLI not found. Try reinstalling: pip install --force-reinstall claude-agent-sdk"
2988 )
2989except ProcessError as e:
2990 print(f"Process failed with exit code: {e.exit_code}")
2991except CLIJSONDecodeError as e:
2992 print(f"Failed to parse response: {e}")
2993```
2994
2995### Modalità streaming con client
2996
2997```python theme={null}
2998from claude_agent_sdk import ClaudeSDKClient
2999import asyncio
3000
3001
3002async def interactive_session():
3003 async with ClaudeSDKClient() as client:
3004 # Send initial message
3005 await client.query("What's the weather like?")
3006
3007 # Process responses
3008 async for msg in client.receive_response():
3009 print(msg)
3010
3011 # Send follow-up
3012 await client.query("Tell me more about that")
3013
3014 # Process follow-up response
3015 async for msg in client.receive_response():
3016 print(msg)
3017
3018
3019asyncio.run(interactive_session())
3020```
3021
3022### Utilizzo di strumenti personalizzati con ClaudeSDKClient
3023
3024```python theme={null}
3025from claude_agent_sdk import (
3026 ClaudeSDKClient,
3027 ClaudeAgentOptions,
3028 tool,
3029 create_sdk_mcp_server,
3030 AssistantMessage,
3031 TextBlock,
3032)
3033import asyncio
3034from typing import Any
3035
3036
3037# Define custom tools with @tool decorator
3038@tool("calculate", "Perform mathematical calculations", {"expression": str})
3039async def calculate(args: dict[str, Any]) -> dict[str, Any]:
3040 try:
3041 result = eval(args["expression"], {"__builtins__": {}})
3042 return {"content": [{"type": "text", "text": f"Result: {result}"}]}
3043 except Exception as e:
3044 return {
3045 "content": [{"type": "text", "text": f"Error: {str(e)}"}],
3046 "is_error": True,
3047 }
3048
3049
3050@tool("get_time", "Get current time", {})
3051async def get_time(args: dict[str, Any]) -> dict[str, Any]:
3052 from datetime import datetime
3053
3054 current_time = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
3055 return {"content": [{"type": "text", "text": f"Current time: {current_time}"}]}
3056
3057
3058async def main():
3059 # Create SDK MCP server with custom tools
3060 my_server = create_sdk_mcp_server(
3061 name="utilities", version="1.0.0", tools=[calculate, get_time]
3062 )
3063
3064 # Configure options with the server
3065 options = ClaudeAgentOptions(
3066 mcp_servers={"utils": my_server},
3067 allowed_tools=["mcp__utils__calculate", "mcp__utils__get_time"],
3068 )
3069
3070 # Use ClaudeSDKClient for interactive tool usage
3071 async with ClaudeSDKClient(options=options) as client:
3072 await client.query("What's 123 * 456?")
3073
3074 # Process calculation response
3075 async for message in client.receive_response():
3076 if isinstance(message, AssistantMessage):
3077 for block in message.content:
3078 if isinstance(block, TextBlock):
3079 print(f"Calculation: {block.text}")
3080
3081 # Follow up with time query
3082 await client.query("What time is it now?")
3083
3084 async for message in client.receive_response():
3085 if isinstance(message, AssistantMessage):
3086 for block in message.content:
3087 if isinstance(block, TextBlock):
3088 print(f"Time: {block.text}")
3089
3090
3091asyncio.run(main())
3092```
3093
3094## Configurazione della Sandbox
3095
3096### `SandboxSettings`
3097
3098Configurazione per il comportamento della sandbox. Usala per abilitare il sandboxing dei comandi e configurare le restrizioni di rete a livello di programmazione.
3099
3100```python theme={null}
3101class SandboxSettings(TypedDict, total=False):
3102 enabled: bool
3103 autoAllowBashIfSandboxed: bool
3104 excludedCommands: list[str]
3105 allowUnsandboxedCommands: bool
3106 network: SandboxNetworkConfig
3107 ignoreViolations: SandboxIgnoreViolations
3108 enableWeakerNestedSandbox: bool
3109```
3110
3111| Proprietà | Tipo | Predefinito | Descrizione |
3112| :-------------------------- | :------------------------------------------------------ | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
3113| `enabled` | `bool` | `False` | Abilita la modalità sandbox per l'esecuzione dei comandi |
3114| `autoAllowBashIfSandboxed` | `bool` | `True` | Approva automaticamente i comandi bash quando la sandbox è abilitata |
3115| `excludedCommands` | `list[str]` | `[]` | Comandi che sempre bypassano le restrizioni della sandbox (ad es. `["docker"]`). Questi vengono eseguiti senza sandbox automaticamente senza coinvolgimento del modello |
3116| `allowUnsandboxedCommands` | `bool` | `True` | Consenti al modello di richiedere l'esecuzione di comandi al di fuori della sandbox. Quando `True`, il modello può impostare `dangerouslyDisableSandbox` nell'input dello strumento, che ricade nel [sistema di autorizzazioni](#permissions-fallback-for-unsandboxed-commands) |
3117| `network` | [`SandboxNetworkConfig`](#sandbox-network-config) | `None` | Configurazione della sandbox specifica della rete |
3118| `ignoreViolations` | [`SandboxIgnoreViolations`](#sandbox-ignore-violations) | `None` | Configura quali violazioni della sandbox ignorare |
3119| `enableWeakerNestedSandbox` | `bool` | `False` | Abilita una sandbox nidificata più debole per la compatibilità |
3120
3121#### Utilizzo di esempio
3122
3123```python theme={null}
3124from claude_agent_sdk import query, ClaudeAgentOptions, SandboxSettings
3125
3126sandbox_settings: SandboxSettings = {
3127 "enabled": True,
3128 "autoAllowBashIfSandboxed": True,
3129 "network": {"allowLocalBinding": True},
3130}
3131
3132async for message in query(
3133 prompt="Build and test my project",
3134 options=ClaudeAgentOptions(sandbox=sandbox_settings),
3135):
3136 print(message)
3137```
3138
3139<Warning>
3140 **Sicurezza del socket Unix**: L'opzione `allowUnixSockets` può concedere l'accesso a potenti servizi di sistema. Ad esempio, consentire `/var/run/docker.sock` concede effettivamente l'accesso completo al sistema host tramite l'API Docker, bypassando l'isolamento della sandbox. Consenti solo i socket Unix strettamente necessari e comprendi le implicazioni di sicurezza di ognuno.
3141</Warning>
3142
3143### `SandboxNetworkConfig`
3144
3145Configurazione specifica della rete per la modalità sandbox.
3146
3147```python theme={null}
3148class SandboxNetworkConfig(TypedDict, total=False):
3149 allowedDomains: list[str]
3150 deniedDomains: list[str]
3151 allowManagedDomainsOnly: bool
3152 allowUnixSockets: list[str]
3153 allowAllUnixSockets: bool
3154 allowLocalBinding: bool
3155 allowMachLookup: list[str]
3156 httpProxyPort: int
3157 socksProxyPort: int
3158```
3159
3160| Proprietà | Tipo | Predefinito | Descrizione |
3161| :------------------------ | :---------- | :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
3162| `allowedDomains` | `list[str]` | `[]` | Nomi di dominio a cui i processi in sandbox possono accedere |
3163| `deniedDomains` | `list[str]` | `[]` | Nomi di dominio a cui i processi in sandbox non possono accedere. Ha la precedenza su `allowedDomains` |
3164| `allowManagedDomainsOnly` | `bool` | `False` | Solo impostazioni gestite: quando impostato nelle impostazioni gestite, ignora `allowedDomains` da fonti di impostazioni non gestite. Non ha effetto quando impostato tramite opzioni SDK |
3165| `allowUnixSockets` | `list[str]` | `[]` | Percorsi dei socket Unix a cui i processi possono accedere (ad es. socket Docker) |
3166| `allowAllUnixSockets` | `bool` | `False` | Consenti l'accesso a tutti i socket Unix |
3167| `allowLocalBinding` | `bool` | `False` | Consenti ai processi di associarsi alle porte locali (ad es. per server di sviluppo) |
3168| `allowMachLookup` | `list[str]` | `[]` | Solo macOS: nomi dei servizi XPC/Mach da consentire. Supporta un carattere jolly finale |
3169| `httpProxyPort` | `int` | `None` | Porta proxy HTTP per le richieste di rete |
3170| `socksProxyPort` | `int` | `None` | Porta proxy SOCKS per le richieste di rete |
3171
3172<Note>
3173 Il proxy sandbox integrato applica l'allowlist di rete in base al nome host richiesto e non termina o ispeziona il traffico TLS, quindi tecniche come il [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) possono potenzialmente bypassarlo. Vedi [Limitazioni di sicurezza del sandboxing](/it/sandboxing#security-limitations) per i dettagli e [Distribuzione sicura](/it/agent-sdk/secure-deployment#traffic-forwarding) per configurare un proxy che termina TLS.
3174</Note>
3175
3176### `SandboxIgnoreViolations`
3177
3178Configurazione per ignorare violazioni specifiche della sandbox.
3179
3180```python theme={null}
3181class SandboxIgnoreViolations(TypedDict, total=False):
3182 file: list[str]
3183 network: list[str]
3184```
3185
3186| Proprietà | Tipo | Predefinito | Descrizione |
3187| :-------- | :---------- | :---------- | :------------------------------------------------------ |
3188| `file` | `list[str]` | `[]` | Modelli di percorso file per cui ignorare le violazioni |
3189| `network` | `list[str]` | `[]` | Modelli di rete per cui ignorare le violazioni |
3190
3191### Fallback delle autorizzazioni per i comandi senza sandbox
3192
3193Quando `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.
3194
3195<Note>
3196 **`excludedCommands` vs `allowUnsandboxedCommands`:**
3197
3198 * `excludedCommands`: Un elenco statico di comandi che sempre bypassano la sandbox automaticamente (ad es. `["docker"]`). Il modello non ha controllo su questo.
3199 * `allowUnsandboxedCommands`: Consenti al modello di decidere in fase di esecuzione se richiedere l'esecuzione senza sandbox impostando `dangerouslyDisableSandbox: True` nell'input dello strumento.
3200</Note>
3201
3202```python theme={null}
3203from claude_agent_sdk import (
3204 query,
3205 ClaudeAgentOptions,
3206 HookMatcher,
3207 PermissionResultAllow,
3208 PermissionResultDeny,
3209 ToolPermissionContext,
3210)
3211
3212
3213async def can_use_tool(
3214 tool: str, input: dict, context: ToolPermissionContext
3215) -> PermissionResultAllow | PermissionResultDeny:
3216 # Check if the model is requesting to bypass the sandbox
3217 if tool == "Bash" and input.get("dangerouslyDisableSandbox"):
3218 # The model is requesting to run this command outside the sandbox
3219 print(f"Unsandboxed command requested: {input.get('command')}")
3220
3221 if is_command_authorized(input.get("command")):
3222 return PermissionResultAllow()
3223 return PermissionResultDeny(
3224 message="Command not authorized for unsandboxed execution"
3225 )
3226 return PermissionResultAllow()
3227
3228
3229# Required: dummy hook keeps the stream open for can_use_tool
3230async def dummy_hook(input_data, tool_use_id, context):
3231 return {"continue_": True}
3232
3233
3234async def prompt_stream():
3235 yield {
3236 "type": "user",
3237 "message": {"role": "user", "content": "Deploy my application"},
3238 }
3239
3240
3241async def main():
3242 async for message in query(
3243 prompt=prompt_stream(),
3244 options=ClaudeAgentOptions(
3245 sandbox={
3246 "enabled": True,
3247 "allowUnsandboxedCommands": True, # Model can request unsandboxed execution
3248 },
3249 permission_mode="default",
3250 can_use_tool=can_use_tool,
3251 hooks={"PreToolUse": [HookMatcher(matcher=None, hooks=[dummy_hook])]},
3252 ),
3253 ):
3254 print(message)
3255```
3256
3257Questo modello ti consente di:
3258
3259* **Controllare le richieste del modello**: Registra quando il modello richiede l'esecuzione senza sandbox
3260* **Implementare allowlist**: Consenti solo comandi specifici di essere eseguiti senza sandbox
3261* **Aggiungere flussi di lavoro di approvazione**: Richiedi un'autorizzazione esplicita per operazioni privilegiate
3262
3263<Warning>
3264 I comandi in esecuzione con `dangerouslyDisableSandbox: True` hanno accesso completo al sistema. Assicurati che il tuo handler `can_use_tool` validi queste richieste attentamente.
3265
3266 Se `permission_mode` è impostato su `bypassPermissions` e `allow_unsandboxed_commands` è abilitato, il modello può autonomamente eseguire comandi al di fuori della sandbox senza alcun prompt di approvazione. Questa combinazione consente effettivamente al modello di sfuggire all'isolamento della sandbox silenziosamente.
3267</Warning>
3268
3269## Vedi anche
3270
3271* [Panoramica dell'SDK](/it/agent-sdk/overview) - Concetti generali dell'SDK
3272* [Riferimento TypeScript SDK](/it/agent-sdk/typescript) - Documentazione TypeScript SDK
3273* [Riferimento CLI](/it/cli-reference) - Interfaccia della riga di comando
3274* [Flussi di lavoro comuni](/it/common-workflows) - Guide passo dopo passo
