---
title: Gestire le chiamate agli strumenti
url: https://platform.claude.com/docs/it/agents-and-tools/tool-use/handle-tool-calls
description: Analizza i blocchi tool_use, formatta le risposte tool_result e gestisci gli errori con is_error.
---
Questa pagina copre il ciclo di vita delle chiamate agli strumenti: leggere i blocchi `tool_use` dalla risposta di Claude, formattare i blocchi `tool_result` nella tua risposta e segnalare gli errori. Per l'astrazione SDK che gestisce tutto questo automaticamente, consulta [Tool Runner](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-runner).
**Più semplice con Tool Runner:** La gestione manuale degli strumenti descritta in questa pagina è gestita automaticamente da [Tool Runner](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-runner). Usa questa pagina quando hai bisogno di un controllo personalizzato sull'esecuzione degli strumenti.
La risposta di Claude varia a seconda che utilizzi uno [strumento client o server](https://platform.claude.com/docs/it/agents-and-tools/tool-use/overview#how-tool-use-works).
## Gestione dei risultati degli strumenti client
La risposta avrà uno `stop_reason` pari a `tool_use` e uno o più blocchi di contenuto `tool_use` che includono:
* `id`: Un identificatore univoco per questo specifico blocco di uso dello strumento. Verrà utilizzato in seguito per abbinare i risultati dello strumento.
* `name`: Il nome dello strumento utilizzato.
* `input`: Un oggetto contenente l'input passato allo strumento, conforme all'`input_schema` dello strumento.
Un blocco `tool_use` per un membro del set di strumenti [computer use](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool) o [browser use](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool) include anche un campo `toolset_name` (`"computer"` o `"browser"`). Il suo `name` è lo strumento membro che Claude sta chiamando, come `screenshot` o `navigate`, quindi instrada questi blocchi in base a entrambi i campi.
```json JSON
{
"id": "msg_01Aq9w938a90dw8q",
"model": "claude-opus-5-5",
"stop_reason": "tool_use",
"role": "assistant",
"content": [
{
"type": "text",
"text": "I'll check the current weather in San Francisco for you."
},
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "get_weather",
"input": { "location": "San Francisco, CA", "unit": "celsius" }
}
]
}
```
Quando ricevi una risposta di uso dello strumento per uno strumento client, dovresti:
1. Estrarre `name`, `id` e `input` dal blocco `tool_use`.
2. Eseguire lo strumento effettivo nel tuo codice corrispondente a quel nome di strumento, passando l'`input` dello strumento.
3. Continuare la conversazione inviando un nuovo messaggio con `role` pari a `user` e un blocco `content` contenente il tipo `tool_result` e le seguenti informazioni:
* `tool_use_id`: L'`id` della richiesta di uso dello strumento a cui questo risultato si riferisce.
* `content` (opzionale): Il risultato dello strumento, come stringa (ad esempio, `"content": "15 degrees"`), un elenco di blocchi di contenuto annidati (ad esempio, `"content": [{"type": "text", "text": "15 degrees"}]`) o un elenco di blocchi documento (ad esempio, `"content": [{"type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 degrees"}}]`). Questi blocchi di contenuto possono usare i tipi `text`, `image`, `document` o [`search_result`](https://platform.claude.com/docs/it/build-with-claude/search-results).
* `is_error` (opzionale): Imposta a `true` se l'esecuzione dello strumento ha prodotto un errore.
Un `tool_result` che risponde a un blocco membro di computer use o browser use deve anche riportare lo stesso valore `toolset_name` del blocco `tool_use`; un risultato membro che lo omette viene rifiutato. Anche il suo `content` è più ristretto: un risultato membro può contenere solo blocchi `text` e `image`, e un risultato di browser use può aggiungere un blocco [`browser_state`](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#track-tabs-and-page-state) (i [membri di gestione delle schede](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#tab-management-results) restituiscono solo quel blocco).
**Requisiti di formattazione importanti:**
* I blocchi di risultato dello strumento devono seguire immediatamente i corrispondenti blocchi di uso dello strumento nella cronologia dei messaggi. Non puoi includere alcun messaggio tra il messaggio di uso dello strumento dell'assistente e il messaggio di risultato dello strumento dell'utente.
* Nel messaggio utente contenente i risultati degli strumenti, i blocchi tool\_result devono venire PRIMA nell'array content. Qualsiasi testo deve venire DOPO tutti i risultati degli strumenti.
* Se il turno dell'assistente ha anche chiamato uno [strumento server](https://platform.claude.com/docs/it/agents-and-tools/tool-use/server-tools) che non ha ancora un blocco di risultato, il messaggio utente deve contenere solo blocchi `tool_result`. Il testo dopo i risultati termina il turno in anticipo; per uno strumento server chiamato direttamente da Claude, la richiesta fallisce quindi con un errore 400 che indica lo strumento server non risolto. Consulta [Motivi di arresto e fallback](https://platform.claude.com/docs/it/build-with-claude/handling-stop-reasons#tool-use).
Ad esempio, questo causerà un errore 400:
```json
{
"role": "user",
"content": [
{ "type": "text", "text": "Here are the results:" }, // ❌ Text before tool_result
{ "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ }
]
}
```
Questo è corretto quando il turno dell'assistente chiama solo strumenti client:
```json
{
"role": "user",
"content": [
{ "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ },
{ "type": "text", "text": "What should I do next?" } // ✅ Text after tool_result
]
}
```
Se ricevi un errore come "tool\_use ids were found without tool\_result blocks immediately after", verifica che i risultati degli strumenti siano formattati correttamente.
I risultati degli strumenti spesso contengono contenuti provenienti da fonti al di fuori del tuo controllo: pagine web, email in arrivo, caricamenti degli utenti, API di terze parti. Tratta tali contenuti come non attendibili: un attaccante in grado di influenzarli potrebbe incorporare istruzioni che tentano di reindirizzare Claude ("indirect prompt injection", ovvero iniezione indiretta di prompt). Mantieni i contenuti non attendibili all'interno dei blocchi `tool_result` anziché nei prompt `system` o nei semplici blocchi `text` dell'utente, e consulta [Mitigare jailbreak e prompt injection](https://platform.claude.com/docs/it/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks#indirect-prompt-injection) per un ulteriore rafforzamento.
```json JSON
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "15 degrees"
}
]
}
```
```json JSON
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": [
{ "type": "text", "text": "15 degrees" },
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/jpeg",
"data": "/9j/4AAQSkZJRg..."
}
}
]
}
]
}
```
```json JSON
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9"
}
]
}
```
```json JSON
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": [
{ "type": "text", "text": "The weather is" },
{
"type": "document",
"source": {
"type": "text",
"media_type": "text/plain",
"data": "15 degrees"
}
}
]
}
]
}
```
Dopo aver ricevuto il risultato dello strumento, Claude utilizzerà tali informazioni per continuare a generare una risposta al prompt originale dell'utente.
## Gestione dei risultati degli strumenti server
Claude esegue lo strumento internamente e incorpora i risultati direttamente nella sua risposta senza richiedere ulteriori interazioni da parte dell'utente.
Una risposta può contenere sia un blocco `tool_use` client sia un blocco `server_tool_use` privo di blocco di risultato. Quella chiamata allo strumento server non è ancora terminata e il suo blocco di risultato arriva in una risposta successiva. Rispondi con un messaggio utente che contenga solo i blocchi `tool_result` per gli strumenti client e mantieni lo stesso array `tools`; per uno strumento server chiamato direttamente da Claude, l'API lo esegue in quella richiesta e la risposta successiva inizia con il suo blocco di risultato. Consulta [Motivi di arresto e fallback](https://platform.claude.com/docs/it/build-with-claude/handling-stop-reasons#tool-use).
**Differenze rispetto ad altre API**
A differenza delle API che separano l'uso degli strumenti o utilizzano ruoli speciali come `tool` o `function`, la Claude API integra gli strumenti direttamente nella struttura dei messaggi `user` e `assistant`.
I messaggi contengono array di blocchi `text`, `image`, `tool_use` e `tool_result`. I messaggi `user` includono contenuti client e `tool_result`, mentre i messaggi `assistant` contengono contenuti generati dall'IA e `tool_use`.
## Gestione degli errori con is\_error
Esistono alcuni tipi diversi di errori che possono verificarsi quando si usano gli strumenti con Claude:
Se lo strumento stesso genera un errore durante l'esecuzione (ad esempio, un errore di rete durante il recupero dei dati meteo), puoi restituire il messaggio di errore nel `content` insieme a `"is_error": true`:
```json JSON
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "ConnectionError: the weather service API is not available (HTTP 500)",
"is_error": true
}
]
}
```
Claude incorporerà quindi questo errore nella sua risposta all'utente. Ad esempio: "Mi dispiace, non sono riuscito a recuperare il meteo attuale perché l'API del servizio meteo non è disponibile. Riprova più tardi."
Scrivi messaggi di errore istruttivi. Invece di errori generici come `"failed"`, includi cosa è andato storto e cosa Claude dovrebbe provare successivamente (ad esempio, `"Rate limit exceeded. Retry after 60 seconds."`). Questo fornisce a Claude il contesto necessario per recuperare o adattarsi senza dover indovinare.
Se il tentativo di Claude di usare uno strumento non è valido (ad esempio, mancano parametri obbligatori), di solito significa che non c'erano informazioni sufficienti perché Claude usasse lo strumento correttamente. La soluzione migliore durante lo sviluppo è riprovare la richiesta con valori `description` più dettagliati nelle definizioni degli strumenti.
Tuttavia, puoi anche proseguire la conversazione con un `tool_result` che indica l'errore, e Claude proverà a usare nuovamente lo strumento con le informazioni mancanti compilate:
```json JSON
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: Missing required 'location' parameter",
"is_error": true
}
]
}
```
Se una richiesta di strumento non è valida o mancano parametri, Claude riproverà 2-3 volte con correzioni prima di scusarsi con l'utente.
Per eliminare completamente le chiamate agli strumenti non valide, attiva l'[uso rigoroso degli strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/strict-tool-use) con `strict: true` nelle definizioni degli strumenti. Questo garantisce che gli input degli strumenti corrispondano sempre esattamente al tuo schema, prevenendo parametri mancanti e incongruenze di tipo.
Quando gli strumenti server incontrano errori (ad esempio, problemi di rete con Web Search), Claude gestirà questi errori in modo trasparente e tenterà di fornire una risposta alternativa o una spiegazione all'utente. A differenza degli strumenti client, non è necessario gestire i risultati `is_error` per gli strumenti server.
Per la ricerca web in particolare, i possibili codici di errore includono:
* `too_many_requests`: Limite di velocità superato
* `invalid_input`: Parametro della query di ricerca non valido
* `max_uses_exceeded`: Numero massimo di utilizzi dello strumento di ricerca web superato
* `query_too_long`: La query supera la lunghezza massima
* `unavailable`: Si è verificato un errore interno
## Prossimi passi
Gestisci le risposte in cui Claude chiama più strumenti in un singolo turno.
Lascia che l'SDK gestisca per te il ciclo `tool_use`, la formattazione dei risultati e i tentativi ripetuti.
Scrivi schemi e descrizioni che guidino Claude verso lo strumento giusto.