15| Se vuoi... | Fai questo |15| Se vuoi... | Fai questo |
16| :- | :- |16| :- | :- |
17| Definire uno strumento | Usa [`@tool`](/docs/it/agent-sdk/python#tool) (Python) o [`tool()`](/docs/it/agent-sdk/typescript#tool) (TypeScript) con un nome, una descrizione, uno schema e un handler. Vedi [Creare uno strumento personalizzato](#create-a-custom-tool). |17| Definire uno strumento | Usa [`@tool`](/docs/it/agent-sdk/python#tool) (Python) o [`tool()`](/docs/it/agent-sdk/typescript#tool) (TypeScript) con un nome, una descrizione, uno schema e un handler. Vedi [Creare uno strumento personalizzato](#create-a-custom-tool). |
18| Rendere un parametro facoltativo | Dichiaralo facoltativo nello schema e applica il valore predefinito nell'handler. Vedi [Rendere un parametro facoltativo](#make-a-parameter-optional). |
18| Registrare uno strumento con Claude | Avvolgi in `create_sdk_mcp_server` / `createSdkMcpServer` e passa a `mcpServers` in `query()`. Vedi [Chiamare uno strumento personalizzato](#call-a-custom-tool). |19| Registrare uno strumento con Claude | Avvolgi in `create_sdk_mcp_server` / `createSdkMcpServer` e passa a `mcpServers` in `query()`. Vedi [Chiamare uno strumento personalizzato](#call-a-custom-tool). |
19| Pre-approvare uno strumento | Aggiungi ai tuoi strumenti consentiti. Vedi [Configurare gli strumenti consentiti](#configure-allowed-tools). |20| Pre-approvare uno strumento | Aggiungi ai tuoi strumenti consentiti. Vedi [Configurare gli strumenti consentiti](#configure-allowed-tools). |
20| Rimuovere uno strumento integrato dal contesto di Claude | Passa un array `tools` elencando solo gli strumenti integrati che desideri. Vedi [Configurare gli strumenti consentiti](#configure-allowed-tools). |21| Rimuovere uno strumento integrato dal contesto di Claude | Passa un array `tools` elencando solo gli strumenti integrati che desideri. Vedi [Configurare gli strumenti consentiti](#configure-allowed-tools). |
32 33
33* **Nome:** un identificatore univoco che Claude utilizza per chiamare lo strumento.34* **Nome:** un identificatore univoco che Claude utilizza per chiamare lo strumento.
34* **Descrizione:** cosa fa lo strumento. Claude legge questo per decidere quando chiamarlo.35* **Descrizione:** cosa fa lo strumento. Claude legge questo per decidere quando chiamarlo.
35* **Schema di input:** gli argomenti che Claude deve fornire. In TypeScript questo è sempre uno [schema Zod](https://zod.dev/), e gli `args` del handler sono tipizzati automaticamente da esso. In Python questo è un dict che mappa nomi a tipi, come `{"latitude": float}`, che l'SDK converte in JSON Schema per voi. Il decoratore Python accetta anche un dict completo di [JSON Schema](https://json-schema.org/understanding-json-schema/about) direttamente quando avete bisogno di enum, intervalli, campi opzionali o oggetti annidati.36* **Schema di input:** gli argomenti accettati dallo strumento, dichiarati in base al linguaggio:
37 * **TypeScript**: uno [schema Zod](https://zod.dev/). Gli `args` dell'handler prendono i loro tipi da esso. Chiama `.describe()` su un campo per dargli una descrizione che Claude vede.
38 * **Python**: un dict che mappa nomi a tipi, come `{"latitude": float}`, che l'SDK converte in JSON Schema per te. Avvolgi un tipo in `Annotated`, come `{"latitude": Annotated[float, "Latitude coordinate"]}`, per dare al campo una descrizione che Claude vede. Il decoratore accetta anche direttamente un dict completo di [JSON Schema](https://json-schema.org/understanding-json-schema/about) quando hai bisogno di enum, intervalli, campi opzionali o oggetti annidati.
36* **Handler:** la funzione asincrona che viene eseguita quando Claude chiama lo strumento. Riceve gli argomenti convalidati e deve restituire un oggetto con:39* **Handler:** la funzione asincrona che viene eseguita quando Claude chiama lo strumento. Riceve gli argomenti convalidati e deve restituire un oggetto con:
37 * `content` (obbligatorio): un array di blocchi di risultato, ciascuno con un `type` di `"text"`, `"image"`, `"audio"`, `"resource"` o `"resource_link"`. Vedere [Restituire immagini e risorse](#return-images-and-resources) per i blocchi non testuali.40 * `content` (obbligatorio): un array di blocchi di risultato, ciascuno con un `type` di `"text"`, `"image"`, `"audio"`, `"resource"` o `"resource_link"`. Vedere [Restituire immagini e risorse](#return-images-and-resources) per i blocchi non testuali.
38 * `structuredContent` (opzionale): un oggetto JSON che contiene il risultato come dati leggibili da macchina, restituito insieme a `content`. Vedere [Restituire dati strutturati](#return-structured-data).41 * `structuredContent` (opzionale): un oggetto JSON che contiene il risultato come dati leggibili da macchina, restituito insieme a `content`. Vedere [Restituire dati strutturati](#return-structured-data).
40 43
41Dopo aver definito uno strumento, avvolgetelo in un server con [`createSdkMcpServer`](/docs/it/agent-sdk/typescript#createsdkmcpserver) (TypeScript) o [`create_sdk_mcp_server`](/docs/it/agent-sdk/python#create_sdk_mcp_server) (Python). Il server viene eseguito in-process all'interno della vostra applicazione, non come processo separato.44Dopo aver definito uno strumento, avvolgetelo in un server con [`createSdkMcpServer`](/docs/it/agent-sdk/typescript#createsdkmcpserver) (TypeScript) o [`create_sdk_mcp_server`](/docs/it/agent-sdk/python#create_sdk_mcp_server) (Python). Il server viene eseguito in-process all'interno della vostra applicazione, non come processo separato.
42 45
46Gli esempi Python in questa pagina che effettuano richieste HTTP utilizzano [httpx](https://www.python-httpx.org/). Aggiungilo con il gestore di pacchetti utilizzato dal tuo progetto:
47
48<Tabs>
49 <Tab title="Python (uv)">
50 ```bash theme={null}
51 uv add httpx
52 ```
53 </Tab>
54
55 <Tab title="Python (pip)">
56 ```bash theme={null}
57 pip install httpx
58 ```
59 </Tab>
60</Tabs>
61
43<h3 id="weather-tool-example">62<h3 id="weather-tool-example">
44 Esempio di strumento meteo63 Esempio di strumento meteo
45</h3>64</h3>
46 65
47Questo esempio definisce uno strumento `get_temperature` e lo avvolge in un server MCP. Configura solo lo strumento; per passarlo a `query` e eseguirlo, vedere [Chiamare uno strumento personalizzato](#call-a-custom-tool) di seguito.66Questo esempio definisce uno strumento `get_temperature` e lo avvolge in un server MCP, senza passare il server a `query`. Per eseguire lo strumento, consulta [Chiamare uno strumento personalizzato](#call-a-custom-tool) di seguito.
48 67
49<CodeGroup>68<CodeGroup>
50 ```python Python theme={null}69 ```python Python theme={null}
51 from typing import Any70 from typing import Annotated, Any
52 import httpx71 import httpx
53 from claude_agent_sdk import tool, create_sdk_mcp_server72 from claude_agent_sdk import tool, create_sdk_mcp_server
54 73
57 @tool(76 @tool(
58 "get_temperature",77 "get_temperature",
59 "Get the current temperature at a location",78 "Get the current temperature at a location",
60 {"latitude": float, "longitude": float},79 {
80 "latitude": Annotated[float, "Latitude coordinate"],
81 "longitude": Annotated[float, "Longitude coordinate"],
82 },
61 )83 )
62 async def get_temperature(args: dict[str, Any]) -> dict[str, Any]:84 async def get_temperature(args: dict[str, Any]) -> dict[str, Any]:
63 async with httpx.AsyncClient() as client:85 async with httpx.AsyncClient() as client:
128 150
129Vedere il riferimento TypeScript [`tool()`](/docs/it/agent-sdk/typescript#tool) o il riferimento Python [`@tool`](/docs/it/agent-sdk/python#tool) per i dettagli completi dei parametri, inclusi i formati di input JSON Schema e la struttura del valore di ritorno.151Vedere il riferimento TypeScript [`tool()`](/docs/it/agent-sdk/typescript#tool) o il riferimento Python [`@tool`](/docs/it/agent-sdk/python#tool) per i dettagli completi dei parametri, inclusi i formati di input JSON Schema e la struttura del valore di ritorno.
130 152
131<Tip>153<h3 id="make-a-parameter-optional">
132 Per rendere un parametro opzionale: in TypeScript, aggiungete `.optional()` al campo Zod e applicate il valore predefinito nel handler. In Python, lo schema dict tratta ogni chiave come obbligatoria, quindi omettete il parametro dallo schema, menzionatelo nella stringa di descrizione e leggetelo con `args.get()` nel handler. Lo strumento [`get_precipitation_chance` di seguito](#add-more-tools) mostra entrambi i modelli.154 Rendere un parametro opzionale
133</Tip>155</h3>
156
157Per rendere un parametro opzionale, dichiaralo come opzionale nello schema e applica il valore predefinito nell'handler:
158
159* **TypeScript**: aggiungi `.optional()` al campo Zod.
160* **Python**: lo schema dict richiede ogni chiave. Usa la forma JSON Schema, lascia il parametro fuori da `required` e leggilo con `args.get()`. Per uno schema tipizzato con chiavi opzionali, consulta [classe TypedDict](/docs/it/agent-sdk/python#input-schema-options).
161
162Lo strumento [`get_precipitation_chance` di seguito](#add-more-tools) mostra entrambi i modelli.
134 163
135<h3 id="call-a-custom-tool">164<h3 id="call-a-custom-tool">
136 Chiamare uno strumento personalizzato165 Chiamare uno strumento personalizzato
182 ```211 ```
183</CodeGroup>212</CodeGroup>
184 213
185Combinate questo snippet con le definizioni di strumento e server dall'[esempio di strumento meteo](#weather-tool-example) in un unico file, quindi eseguitelo con `python weather.py` per Python o `npx tsx weather.ts` per TypeScript. Claude chiama `get_temperature` e lo script stampa una risposta su una riga con la temperatura attuale a San Francisco.214Combina questo snippet con le definizioni di strumento e server dall'[esempio di strumento meteo](#weather-tool-example) in un unico file, `weather.py` o `weather.ts`, quindi eseguilo dal tuo terminale:
215
216<Tabs>
217 <Tab title="TypeScript">
218 ```bash theme={null}
219 npx tsx weather.ts
220 ```
221 </Tab>
222
223 <Tab title="Python (uv)">
224 ```bash theme={null}
225 uv run weather.py
226 ```
227 </Tab>
228
229 <Tab title="Python (pip)">
230 Attiva l'ambiente virtuale in cui hai installato l'SDK, quindi esegui:
231
232 ```bash theme={null}
233 python weather.py
234 ```
235 </Tab>
236</Tabs>
237
238Claude chiama `get_temperature` e lo script stampa una risposta su una riga con la temperatura attuale a San Francisco.
186 239
187<h3 id="add-more-tools">240<h3 id="add-more-tools">
188 Aggiungere più strumenti241 Aggiungere più strumenti
197 # Define a second tool for the same server250 # Define a second tool for the same server
198 @tool(251 @tool(
199 "get_precipitation_chance",252 "get_precipitation_chance",
200 "Get the hourly precipitation probability for a location. "253 "Get the hourly precipitation probability for a location",
201 "Optionally pass 'hours' (1-24) to control how many hours to return.",254 {
202 {"latitude": float, "longitude": float},255 "type": "object",
256 "properties": {
257 "latitude": {"type": "number"},
258 "longitude": {"type": "number"},
259 "hours": {
260 "type": "integer",
261 "minimum": 1,
262 "maximum": 24,
263 "description": "How many hours of forecast to return",
264 },
265 },
266 # 'hours' is left out of required, so Claude can omit it
267 "required": ["latitude", "longitude"],
268 },
203 )269 )
204 async def get_precipitation_chance(args: dict[str, Any]) -> dict[str, Any]:270 async def get_precipitation_chance(args: dict[str, Any]) -> dict[str, Any]:
205 # 'hours' isn't in the schema - read it with .get() to make it optional271 # 'hours' isn't in required - read it with .get() to fall back to a default
206 hours = args.get("hours", 12)272 hours = args.get("hours", 12)
207 async with httpx.AsyncClient() as client:273 async with httpx.AsyncClient() as client:
208 response = await client.get(274 response = await client.get(
