Gestire le chiamate di strumenti

Questa pagina copre il ciclo di vita della chiamata di 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 questo automaticamente, vedi Tool Runner.

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

Gestire i risultati dagli strumenti client

La risposta avrà un 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 utilizzo dello strumento. Questo 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 a input_schema dello strumento.

Quando ricevi una risposta di utilizzo dello strumento per uno strumento client, dovresti:

1. Estrarre name, id e input dal blocco tool_use.
2. Eseguire lo strumento effettivo nel tuo codebase corrispondente a quel nome di strumento, passando l'input dello strumento.
3. 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 utilizzo dello strumento per cui questo è un risultato.
   • content: Il risultato dello strumento, come una 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 di documenti (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 o document.
   • is_error (opzionale): Impostare su true se l'esecuzione dello strumento ha generato un errore.

{
  "role": "user",
  "content": [
    { "type": "text", "text": "Here are the results:" }, // ❌ Testo prima di tool_result
    { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ }
  ]
}

{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ },
    { "type": "text", "text": "What should I do next?" } // ✅ Testo dopo tool_result
  ]
}

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

Gestire i risultati dagli strumenti server

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

Gestire gli errori con is_error

Ci sono alcuni diversi tipi di errori che possono verificarsi quando si utilizzano strumenti con Claude:

Passaggi successivi

• Per eseguire più strumenti in un turno, vedi Parallel tool use.
• Per l'astrazione SDK che automatizza questo ciclo, vedi Tool Runner.
• Per il flusso di lavoro completo di tool-use, vedi Define tools.