MessagesStrumenti

Come funziona l'uso degli strumenti

Copy page



Comprendi il ciclo dell'uso degli strumenti, dove vengono eseguiti gli strumenti e quando usare gli strumenti invece della prosa.

Questa pagina spiega i concetti alla base del "tool use" (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 Costruisci un agente che usa strumenti o con la guida Definisci gli strumenti.

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 determina 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 di 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 chiamare in base alla conversazione.

Dove vengono eseguiti gli strumenti

L'asse principale lungo il quale 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 dal client)

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

Quando Claude chiama 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 dal client)

Per una manciata di operazioni comuni (gestire una memoria scratchpad, eseguire comandi shell, modificare file, controllare un desktop o 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, computer e browser.

Il modello di esecuzione è identico a quello degli 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 definire un tuo 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 più eleganza di quanto farebbe con uno strumento personalizzato che fa la stessa cosa. Lo schema è l'interfaccia che il modello già si aspetta.

Strumenti eseguiti dal server

Per web_search, web_fetch, code_execution e tool_search, Anthropic esegue il codice. 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 reinserisce l'output nel modello prima che la risposta ti raggiunga, a meno che il ciclo non si fermi prima di terminare, 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 nel momento in cui li vedi, e il compito della tua applicazione è abilitare lo strumento e leggere la risposta finale piuttosto che partecipare al ciclo di esecuzione; le principali eccezioni sono un ciclo in pausa (pause_turn) e un turno che chiama anche uno strumento client.

Il ciclo agentico (strumenti client)

Gli strumenti eseguiti dal client (sia definiti dall'utente sia con schema Anthropic) richiedono che la tua applicazione guidi 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 riferisci, 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 passaggio 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 motivo di arresto ("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 meccanismi di costruzione delle richieste, gestione delle chiamate parallele agli strumenti e formattazione dei risultati, consulta Gestisci le chiamate agli strumenti.

Il ciclo lato server

Gli strumenti eseguiti dal 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, determina se 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 interrotto. Consulta Strumenti server per il pattern di continuazione.

Il ciclo restituisce inoltre 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 dello strumento client. Consulta Motivi di arresto 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 solo a partire dal 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 correnti, il meteo di oggi, il contenuto di un database. Qualsiasi cosa al di fuori dei dati di addestramento o specifica del tuo sistema richiede uno strumento per recuperarla.
• Output strutturati con forma garantita. Quando hai bisogno di un oggetto JSON con campi specifici piuttosto che di prosa che per caso contiene le informazioni, uno schema di strumento impone la forma.
• Richiamare sistemi esistenti. Database, API interne, filesystem. L'uso degli strumenti è il ponte tra le richieste in linguaggio naturale e i sistemi che le soddisfano.

Un chiaro 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 segnale che la struttura appartiene allo schema.

L'uso degli strumenti non è adatto quando:

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

Scegliere tra gli approcci

Prossimi passi