Gestire le chiamate agli strumenti

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.

La risposta di Claude varia a seconda che utilizzi uno strumento client o server.

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 o browser use 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.

{
  "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.
   • 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 (i membri di gestione delle schede restituiscono solo quel blocco).

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

{
  "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..."
          }
        }
      ]
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9"
    }
  ]
}

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

Gestione degli errori con is_error

Esistono alcuni tipi diversi di errori che possono verificarsi quando si usano gli strumenti con Claude:

{
  "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
    }
  ]
}

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

Prossimi passi