Claude Platform Docs
MessaggiStrumenti

Gestire le chiamate agli strumenti

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

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

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.

Per questi passaggi sotto forma di programmi completi, consulta Tutorial: Costruisci un agente che usa strumenti.

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

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

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.

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.

Questa pagina ti è stata utile?