Come funziona l'uso degli strumenti

Questa pagina spiega i concetti alla base dell'uso degli strumenti: dove vengono eseguiti gli strumenti, come funziona il ciclo agentico e quando l'uso degli strumenti è l'approccio giusto. Per una guida pratica, inizia con il tutorial o la guida all'implementazione.



Il contratto dell'uso degli strumenti

L'uso degli strumenti è un contratto tra la tua applicazione e il modello. Tu specifichi quali operazioni sono disponibili e quale forma assumono i loro input e output; Claude decide quando e come chiamarle. Il modello non esegue mai nulla da solo. Emette una richiesta strutturata, il tuo codice (o i server di Anthropic) esegue l'operazione, e il risultato rifluisce nella conversazione.

Questo contratto fa sì che il modello si comporti meno come un generatore di testo e più come una funzione che chiami. Gli ingegneri con esperienza nelle API classiche possono integrare l'uso degli strumenti nello stesso modo in cui integrerebbero qualsiasi altra interfaccia tipizzata: definisci lo schema, gestisci la callback, restituisci un risultato. La differenza è che il chiamante dall'altra parte è un modello linguistico che sceglie quale funzione invocare in base alla conversazione.



Dove vengono eseguiti gli strumenti

L'asse principale lungo cui gli strumenti differiscono è dove viene eseguito il codice. Ogni strumento rientra in una di tre categorie, e la categoria determina di cosa è responsabile la tua applicazione.



Strumenti definiti dall'utente (eseguiti lato client)

Tu scrivi lo schema, tu esegui il codice, tu restituisci i risultati. Questo è il caso principale: la stragrande maggioranza del traffico di uso degli strumenti è costituita da strumenti definiti dall'utente che chiamano logica specifica dell'applicazione.

Quando Claude decide di usare uno dei tuoi strumenti, la risposta dell'API contiene un blocco tool_use con il nome dello strumento e un oggetto JSON di argomenti. La tua applicazione estrae quegli argomenti, esegue l'operazione (una query al database, una chiamata HTTP, una scrittura su file, qualunque cosa faccia lo strumento) e invia l'output in un blocco tool_result nella richiesta successiva. Claude non vede mai la tua implementazione; vede solo lo schema che hai fornito e il risultato che hai restituito.



Strumenti con schema Anthropic (eseguiti lato client)

Per una manciata di operazioni comuni (gestione della memoria scratchpad, esecuzione di comandi shell, modifica di file, controllo di un browser), Anthropic pubblica lo schema dello strumento e la tua applicazione gestisce l'esecuzione. Gli strumenti in questa categoria sono memory, bash, text_editor e computer.

Il modello di esecuzione è identico agli strumenti definiti dall'utente: la risposta contiene un blocco tool_use, il tuo codice esegue l'operazione e tu invii un tool_result. Il motivo per usare uno strumento con schema Anthropic invece di definirne uno equivalente è che questi schemi sono integrati nell'addestramento. Claude è stato ottimizzato su migliaia di traiettorie di successo che usano esattamente queste firme di strumenti, quindi li chiama in modo più affidabile e si riprende dagli errori con maggiore eleganza rispetto a quanto farebbe con uno strumento personalizzato che fa la stessa cosa. Lo schema è l'interfaccia che il modello già si aspetta.



Strumenti eseguiti lato server

Per web_search, web_fetch, code_execution e tool_search, Anthropic esegue il codice. Tu abiliti lo strumento nella tua richiesta e il server gestisce tutto il resto. Non costruisci mai un blocco tool_result per questi strumenti. Quando un turno chiama solo strumenti server, il ciclo lato server esegue l'operazione e fornisce l'output al modello prima che la risposta ti raggiunga, a meno che il ciclo non si fermi prima di finire, il più delle volte perché va in pausa.

La risposta che ricevi contiene blocchi server_tool_use che mostrano cosa è stato eseguito e cosa è stato restituito. Nel caso comune, l'esecuzione è già completa quando li vedi, e il compito della tua applicazione è abilitare lo strumento e leggere la risposta finale piuttosto che partecipare al ciclo di esecuzione; le eccezioni principali sono un ciclo in pausa (pause_turn) e un turno che chiama anche uno strumento client.



Il ciclo agentico (strumenti client)

Gli strumenti eseguiti lato client (sia definiti dall'utente che con schema Anthropic) richiedono che la tua applicazione gestisca un ciclo. Il modello non può eseguire il tuo codice, quindi ogni chiamata a uno strumento è un viaggio di andata e ritorno: il modello chiede, tu esegui, tu riporti il risultato, il modello continua.

La forma canonica è un ciclo while basato su stop_reason:

1. Invia una richiesta con il tuo array tools e il messaggio dell'utente.
2. Claude risponde con stop_reason: "tool_use" e uno o più blocchi tool_use.
3. Esegui ogni strumento. Formatta gli output come blocchi tool_result.
4. Invia una nuova richiesta contenente i messaggi originali, la risposta dell'assistente e un messaggio utente con i blocchi tool_result.
5. Ripeti dal passo 2 finché stop_reason è "tool_use".

In pratica questo si legge come: finché stop_reason == "tool_use", esegui gli strumenti e continua la conversazione. Il ciclo termina con qualsiasi altro stop reason ("end_turn", "max_tokens", "stop_sequence" o "refusal"), il che significa che Claude ha prodotto una risposta finale oppure si è fermato per un altro motivo che la tua applicazione dovrebbe gestire.

Per i dettagli sulla costruzione delle richieste, la gestione delle chiamate parallele agli strumenti e la formattazione dei risultati, consulta Gestire le chiamate agli strumenti.



Il ciclo lato server

Gli strumenti eseguiti lato server eseguono il proprio ciclo all'interno dell'infrastruttura di Anthropic. Una singola richiesta dalla tua applicazione potrebbe attivare diverse ricerche web o esecuzioni di codice prima che arrivi una risposta. Il modello cerca, legge i risultati, decide di cercare di nuovo e itera finché non ha ciò di cui ha bisogno, tutto senza che la tua applicazione partecipi.

Questo ciclo interno ha un limite di iterazioni. Se il modello sta ancora iterando quando raggiunge il limite, la risposta arriva con stop_reason: "pause_turn" invece di "end_turn". Un turno in pausa significa che il lavoro non è finito; reinvia la conversazione (inclusa la risposta in pausa) per permettere al modello di continuare da dove si era fermato. Consulta Strumenti server per il pattern di continuazione.

Il ciclo restituisce anche il controllo a te prima che uno strumento server venga eseguito se Claude chiama quello strumento server e uno strumento client nello stesso gruppo di chiamate parallele agli strumenti. La risposta arriva quindi con stop_reason: "tool_use" e un blocco server_tool_use che non ha ancora un blocco di risultato; l'API lo esegue dopo che hai restituito i risultati degli strumenti client. Consulta Stop reason e fallback per il contratto esatto.



Quando usare gli strumenti (e quando no)

L'uso degli strumenti è adatto quando il compito richiede qualcosa che il modello non può fare dal solo testo:

• Azioni con effetti collaterali. Inviare un'email, scrivere un file, aggiornare un record. Il modello può descrivere queste azioni, ma solo uno strumento può eseguirle.
• Dati aggiornati o esterni. Prezzi attuali, il meteo di oggi, il contenuto di un database. Qualsiasi cosa al di fuori dei dati di addestramento o specifica del tuo sistema necessita di uno strumento per recuperarla.
• Output strutturati con forma garantita. Quando hai bisogno di un oggetto JSON con campi specifici piuttosto che di testo libero che contiene casualmente le informazioni, uno schema di strumento impone la forma.
• Chiamate a sistemi esistenti. Database, API interne, file system. L'uso degli strumenti è il ponte tra le richieste in linguaggio naturale e i sistemi che le soddisfano.

Il segnale che dovresti usare gli strumenti: se stai scrivendo una regex per estrarre una decisione dall'output del modello, quella decisione avrebbe dovuto essere una chiamata a uno strumento. Analizzare testo libero per recuperare un intento strutturato è un segno che la struttura appartiene allo schema.

L'uso degli strumenti non è adatto quando:

• Il modello può rispondere solo dall'addestramento. Riassunti, traduzioni e domande di conoscenza generale non necessitano di un viaggio di andata e ritorno con uno strumento.
• L'interazione è una domanda-risposta singola senza effetti collaterali. Se non c'è nulla da eseguire, non c'è nulla che uno strumento possa fare.
• La "latency" (latenza) delle chiamate agli strumenti dominerebbe una risposta banale. Ogni chiamata a uno strumento è almeno un viaggio di andata e ritorno aggiuntivo; per compiti leggeri l'overhead può superare il lavoro stesso.



Scegliere tra gli approcci



Passaggi successivi