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

Quando la risposta di Claude contiene blocchi `tool_use`, il tuo codice esegue ogni strumento e restituisce blocchi `tool_result`, inclusi eventuali errori. Scrivi tu stesso questo codice quando hai bisogno di un controllo personalizzato sull’esecuzione degli strumenti. Altrimenti, usa il [tool runner](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-runner) dell’SDK, che esegue gli strumenti e invia i risultati per te.

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 ha 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. Viene utilizzato per associare i risultati dello strumento in un secondo momento.
* `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.

<Accordion title="Esempio di risposta API con un blocco di contenuto `tool_use`">
  ```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" }
      }
    ]
  }
  ```
</Accordion>

Quando ricevi una risposta di uso dello strumento per uno strumento client, segui questi passaggi:

1. Per ogni blocco `tool_use`, esegui lo strumento indicato dal blocco, passando il suo `input`.
2. In una nuova richiesta, mantieni i messaggi precedenti e aggiungi il `content` della risposta invariato come messaggio `assistant`.
3. Aggiungi un messaggio `user` con un blocco `tool_result` per ogni blocco `tool_use` presente in quel contenuto, anche se lo strumento ha fallito.
4. Invia la richiesta con gli stessi `tools` della prima richiesta. Claude usa i risultati degli strumenti per proseguire la sua risposta.
5. Se anche lo `stop_reason` della risposta successiva è `tool_use`, ripeti questi passaggi. Per gli altri valori, consulta il [riferimento rapido dei motivi di arresto](https://platform.claude.com/docs/it/build-with-claude/handling-stop-reasons#quick-reference).

Per questi passaggi sotto forma di programmi completi, consulta [Tutorial: Costruisci un agente che usa strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/build-a-tool-using-agent).

Ogni blocco `tool_result` ha `type` impostato su `tool_result`, più questi campi:

* `tool_use_id`: L’`id` del blocco `tool_use` a cui questo risultato risponde.
* `content` (opzionale): Il risultato dello strumento come stringa o come elenco di blocchi di contenuto. 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 lo strumento ha fallito o la chiamata non era valida.

Ad esempio, un risultato dello strumento riuscito ha questo aspetto:

```json JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 degrees"
    }
  ]
}
```

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

<Note>
  **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 dell’utente contenente i risultati degli strumenti, i blocchi `tool_result` devono venire PRIMA nell’array del contenuto. 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).

  Se ricevi un errore come “tool\_use ids were found without tool\_result blocks immediately after”, verifica che i risultati dei tuoi strumenti siano formattati correttamente.
</Note>

<Warning>
  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” (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 ulteriori misure di protezione.
</Warning>

<AccordionGroup>
  <Accordion title="Esempio di risultato dello strumento con immagini">
    ```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..."
              }
            }
          ]
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Esempio di risultato dello strumento vuoto">
    ```json JSON
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_01A09q90qw90lq917835lq9"
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Esempio di risultato dello strumento con documenti">
    ```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"
              }
            }
          ]
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Esempio di testo prima e dopo un risultato dello strumento">
    Ad esempio, questo causa 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
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

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

<Note>
  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 completa, e il suo blocco di risultato arriva in una risposta successiva. Rispondi con un messaggio dell’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).
</Note>

<Tip>
  **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 del client e `tool_result`, mentre i messaggi `assistant` contengono contenuti generati dall’IA e `tool_use`.
</Tip>

## Gestione degli errori con is\_error

Quando uno strumento client fallisce o una chiamata non è valida, invia un blocco `tool_result` con `is_error` impostato a `true`. Claude potrebbe quindi chiamare di nuovo lo strumento con un nuovo blocco `tool_use`, quindi limita il numero di tentativi consentiti dal tuo ciclo.

<AccordionGroup>
  <Accordion title="Errore di esecuzione dello strumento">
    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 può quindi chiamare di nuovo lo strumento o comunicare all’utente cosa è successo. Ad esempio, Claude potrebbe dire “Mi dispiace, non sono riuscito a recuperare il meteo attuale perché l’API del servizio meteo non è disponibile. Riprova più tardi.”

    <Tip>
      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.
    </Tip>
  </Accordion>

  <Accordion title="Chiamata allo strumento non valida">
    Se il tentativo di Claude di utilizzare uno strumento non è valido (ad esempio, mancano parametri obbligatori), di solito significa che non c’erano informazioni sufficienti affinché Claude utilizzasse lo strumento correttamente. L’approccio migliore durante lo sviluppo è riprovare la richiesta con valori `description` più dettagliati nelle definizioni dei tuoi strumenti.

    Tuttavia, puoi anche proseguire la conversazione con un `tool_result` che indica l’errore:

    ```json JSON
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
          "content": "Error: Missing required 'location' parameter",
          "is_error": true
        }
      ]
    }
    ```

    Claude può quindi chiamare di nuovo lo strumento con le informazioni mancanti compilate.

    <Tip>
      Per eliminare completamente le chiamate agli strumenti non valide, adotta l’[uso rigoroso degli strumenti](https://platform.claude.com/docs/it/agents-and-tools/tool-use/strict-tool-use) con `strict: true` nelle definizioni dei tuoi strumenti. Questo garantisce che gli input degli strumenti corrispondano sempre esattamente al tuo schema, prevenendo parametri mancanti e discrepanze di tipo.
    </Tip>
  </Accordion>

  <Accordion title="Errori degli strumenti server">
    A differenza degli strumenti client, non invii risultati `is_error` per gli strumenti server. Quando uno strumento server incontra un errore, ad esempio un problema di rete durante la ricerca web, l’API restituisce l’errore all’interno del blocco di risultato dello strumento. Nella maggior parte dei casi, Claude prosegue quindi con un altro approccio o con una spiegazione per l’utente.

    Per i codici di errore della ricerca web, consulta [Errori dello strumento di ricerca web](https://platform.claude.com/docs/it/agents-and-tools/tool-use/web-search-tool#errors).
  </Accordion>
</AccordionGroup>

## Prossimi passi

<CardGroup cols={3}>
  <Card title="Uso parallelo degli strumenti" icon="grid" href="https://platform.claude.com/docs/it/agents-and-tools/tool-use/parallel-tool-use">
    Gestisci le risposte in cui Claude chiama più strumenti in un singolo turno.
  </Card>

  <Card title="Tool runner (SDK)" icon="wrench" href="https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-runner">
    Lascia che l’SDK gestisca per te il ciclo `tool_use`, la formattazione dei risultati e i tentativi ripetuti.
  </Card>

  <Card title="Definire gli strumenti" icon="hammer" href="https://platform.claude.com/docs/it/agents-and-tools/tool-use/define-tools">
    Scrivi schemi e descrizioni che guidino Claude verso lo strumento giusto.
  </Card>
</CardGroup>
