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_schemadello 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, segui questi passaggi:
- Per ogni blocco
tool_use, esegui lo strumento indicato dal blocco, passando il suoinput. - In una nuova richiesta, mantieni i messaggi precedenti e aggiungi il
contentdella risposta invariato come messaggioassistant. - Aggiungi un messaggio
usercon un bloccotool_resultper ogni bloccotool_usepresente in quel contenuto, anche se lo strumento ha fallito. - Invia la richiesta con gli stessi
toolsdella prima richiesta. Claude usa i risultati degli strumenti per proseguire la sua risposta. - Se anche lo
stop_reasondella 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’iddel bloccotool_usea 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 tipitext,image,documentosearch_result.is_error(opzionale): Imposta atruese lo strumento ha fallito o la chiamata non era valida.
Ad esempio, un risultato dello strumento riuscito ha questo aspetto:
{
"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).
{
"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"
}
}
]
}
]
}Ad esempio, questo causa un errore 400:
{
"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:
{
"role": "user",
"content": [
{ "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ },
{ "type": "text", "text": "What should I do next?" } // ✅ Text after tool_result
]
}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.
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:
{
"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.”
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:
{
"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.
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.
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?