MessaggiStrumenti

Gestire le chiamate agli strumenti

Analizza i blocchi tool_use, formatta le risposte tool_result e gestisci gli errori con is_error.

Questa pagina tratta 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.

Più semplice con Tool Runner: La gestione manuale degli strumenti descritta in questa pagina viene gestita automaticamente da Tool Runner. Usa questa pagina quando hai bisogno di un controllo personalizzato sull'esecuzione degli strumenti.

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

Gestire i risultati degli strumenti client

La risposta avrà uno stop_reason di tool_use e uno o più blocchi di contenuto tool_use che includono:

id: Un identificatore univoco per questo particolare blocco di uso degli strumenti. Verrà utilizzato per abbinare i risultati dello strumento in seguito.
name: Il nome dello strumento utilizzato.
input: Un oggetto contenente l'input passato allo strumento, conforme all'input_schema dello strumento.

Quando ricevi una risposta di uso degli strumenti per uno strumento client, dovresti:

Estrarre name, id e input dal blocco tool_use.
Eseguire lo strumento effettivo nel tuo codebase corrispondente a quel nome di strumento, passando l'input dello strumento.
Continuare la conversazione inviando un nuovo messaggio con il role di user e un blocco content contenente il tipo tool_result e le seguenti informazioni:
- tool_use_id: L'id della richiesta di uso degli strumenti a cui si riferisce questo risultato.
- 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 utilizzare i tipi text, image, document o search_result.
- is_error (opzionale): Imposta a true se l'esecuzione dello strumento ha generato un errore.

Requisiti di formattazione importanti:

I blocchi di risultato dello strumento devono seguire immediatamente i corrispondenti blocchi di uso degli strumenti nella cronologia dei messaggi. Non puoi includere alcun messaggio tra il messaggio di uso degli strumenti 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 PER PRIMI nell'array di contenuto. Qualsiasi testo deve venire DOPO tutti i risultati degli strumenti.
Se il turno dell'assistente ha chiamato anche uno strumento server 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 anticipatamente; per uno strumento server che Claude ha chiamato direttamente, la richiesta fallisce quindi con un errore 400 che indica lo strumento server non risolto. Consulta Motivi di arresto e fallback.

Ad esempio, questo causerà 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
  ]
}

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 quel contenuto come non attendibile: un attaccante che può influenzarlo potrebbe incorporare istruzioni che tentano di reindirizzare Claude (indirect prompt injection, ovvero iniezione indiretta di prompt). Mantieni il contenuto non attendibile all'interno dei blocchi tool_result anziché nei prompt system o nei blocchi text utente semplici, e consulta Mitigare jailbreak e iniezioni di prompt per ulteriori misure di protezione.

Dopo aver ricevuto il risultato dello strumento, Claude utilizzerà tali informazioni per continuare a generare una risposta al prompt originale dell'utente.

Gestire i risultati degli strumenti server

Claude esegue lo strumento internamente e incorpora i risultati direttamente nella sua risposta senza richiedere ulteriore interazione da parte dell'utente.

Una risposta può contenere sia un blocco tool_use client sia un blocco server_tool_use che non ha ancora un 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 che Claude ha chiamato direttamente, l'API lo esegue su quella richiesta e la risposta successiva inizia con il suo blocco di risultato. Consulta Motivi di arresto e fallback.

Differenze rispetto ad altre API

A differenza delle API che separano l'uso degli strumenti o utilizzano ruoli speciali come tool o function, l'API di Claude 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 contenuto client e tool_result, mentre i messaggi assistant contengono contenuto generato dall'IA e tool_use.

Gestire gli errori con is_error

Esistono diversi tipi di errori che possono verificarsi quando si utilizzano strumenti con Claude:

Passaggi successivi

Uso parallelo degli strumenti

Gestisci le risposte in cui Claude chiama più strumenti in un singolo turno.

Tool Runner (SDK)

Lascia che l'SDK gestisca per te il ciclo tool_use, la formattazione dei risultati e i tentativi.

Definire gli strumenti

Scrivi schemi e descrizioni che guidino Claude verso lo strumento giusto.

Was this page helpful?

Gestire i risultati degli strumenti client

La risposta avrà uno stop_reason di tool_use e uno o più blocchi di contenuto tool_use che includono:

id: Un identificatore univoco per questo particolare blocco di uso degli strumenti. Verrà utilizzato per abbinare i risultati dello strumento in seguito.

name: Il nome dello strumento utilizzato.

input: Un oggetto contenente l'input passato allo strumento, conforme all'input_schema dello strumento.

Quando ricevi una risposta di uso degli strumenti per uno strumento client, dovresti:

Estrarre name, id e input dal blocco tool_use.

Eseguire lo strumento effettivo nel tuo codebase corrispondente a quel nome di strumento, passando l'input dello strumento.

Continuare la conversazione inviando un nuovo messaggio con il role di user e un blocco content contenente il tipo tool_result e le seguenti informazioni:

tool_use_id: L'id della richiesta di uso degli strumenti a cui si riferisce questo risultato.
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 utilizzare i tipi text, image, document o search_result.
is_error (opzionale): Imposta a true se l'esecuzione dello strumento ha generato un errore.

Requisiti di formattazione importanti:

I blocchi di risultato dello strumento devono seguire immediatamente i corrispondenti blocchi di uso degli strumenti nella cronologia dei messaggi. Non puoi includere alcun messaggio tra il messaggio di uso degli strumenti 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 PER PRIMI nell'array di contenuto. Qualsiasi testo deve venire DOPO tutti i risultati degli strumenti.
Se il turno dell'assistente ha chiamato anche uno strumento server 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 anticipatamente; per uno strumento server che Claude ha chiamato direttamente, la richiesta fallisce quindi con un errore 400 che indica lo strumento server non risolto. Consulta Motivi di arresto e fallback.

Ad esempio, questo causerà 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
  ]
}

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.

Dopo aver ricevuto il risultato dello strumento, Claude utilizzerà tali informazioni per continuare a generare una risposta al prompt originale dell'utente.

Gestire i risultati degli strumenti server

Claude esegue lo strumento internamente e incorpora i risultati direttamente nella sua risposta senza richiedere ulteriore interazione da parte dell'utente.

Differenze rispetto ad altre API

Gestire i risultati degli strumenti client

Esempio di risposta API con un blocco di contenuto `tool_use`

Esempio di risultato dello strumento riuscito

Esempio di risultato dello strumento con immagini

Esempio di risultato dello strumento vuoto

Esempio di risultato dello strumento con documenti

Gestire i risultati degli strumenti server

Gestire gli errori con is_error

Errore di esecuzione dello strumento

Nome dello strumento non valido

Errori degli strumenti server

Passaggi successivi

Gestire i risultati degli strumenti client

Esempio di risposta API con un blocco di contenuto `tool_use`

Esempio di risultato dello strumento riuscito

Esempio di risultato dello strumento con immagini

Esempio di risultato dello strumento vuoto

Esempio di risultato dello strumento con documenti

Gestire i risultati degli strumenti server

Gestire gli errori con is_error

Errore di esecuzione dello strumento

Nome dello strumento non valido

Errori degli strumenti server

Passaggi successivi

Gestire i risultati degli strumenti client

Gestire i risultati degli strumenti server

Gestire gli errori con is_error

Passaggi successivi

Gestire i risultati degli strumenti client

Gestire i risultati degli strumenti server

Gestire gli errori con is_error

Passaggi successivi