Come funziona l'uso degli strumenti

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

Il contratto di utilizzo degli strumenti

L'uso degli strumenti è un contratto tra la tua applicazione e il modello. Tu specifichi quali operazioni sono disponibili e quale forma hanno i loro input e output; Claude decide quando e come chiamarli. 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 ritorna 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 classica nelle API possono integrare l'uso degli strumenti nello stesso modo in cui farebbero con qualsiasi altra interfaccia tipizzata: definire lo schema, gestire il callback, restituire 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 il quale gli strumenti differiscono è dove viene eseguito il codice. Ogni strumento rientra in uno di tre gruppi, e il gruppo 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 è l'evento principale: la grande maggioranza del traffico di utilizzo degli strumenti riguarda 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 dal client)

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

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 definire il proprio equivalente è che questi schemi sono addestrati nel modello. Claude è stato ottimizzato su migliaia di traiettorie di successo che utilizzano esattamente queste firme di strumenti, quindi li chiama in modo più affidabile e si riprende dagli errori con più grazia rispetto a uno strumento personalizzato che fa la stessa cosa. Lo schema è l'interfaccia che il modello si aspetta già.

Strumenti eseguiti dal 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 perché il ciclo lato server esegue l'operazione e restituisce l'output al modello prima che la risposta ti raggiunga.

La risposta che ricevi contiene blocchi server_tool_use che mostrano cosa è stato eseguito e cosa è tornato, ma nel momento in cui li vedi, l'esecuzione è già completata. Il compito della tua applicazione è abilitare lo strumento e leggere la risposta finale, non partecipare al ciclo di esecuzione.

Il ciclo agentivo (strumenti client)

Gli strumenti eseguiti dal 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 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 passo 2 mentre stop_reason è "tool_use".

In pratica si legge come: mentre stop_reason == "tool_use", esegui gli strumenti e continua la conversazione. Il ciclo termina con qualsiasi altro motivo di stop ("end_turn", "max_tokens", "stop_sequence" o "refusal"), il che significa che Claude ha prodotto una risposta finale o 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, vedi Gestire 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 innescare 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 torna con stop_reason: "pause_turn" invece di "end_turn". Un turno in pausa significa che il lavoro non è finito; re-invia la conversazione (inclusa la risposta in pausa) per permettere al modello di continuare da dove si era fermato. Vedi Strumenti server per il pattern di continuazione.

Quando usare gli strumenti (e quando no)

L'uso degli strumenti è adatto quando il compito richiede qualcosa che il modello non può fare solo 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 freschi o esterni. Prezzi attuali, meteo di oggi, contenuti di un database. Qualsiasi cosa al di fuori dei dati di addestramento o specifica del tuo sistema ha bisogno di uno strumento per recuperarla.
• Output strutturati con forma garantita. Quando hai bisogno di un oggetto JSON con campi specifici piuttosto che di prosa 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 in forma libera 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 dall'addestramento. Riassunti, traduzioni e domande di cultura generale non hanno bisogno di un viaggio di andata e ritorno con uno strumento.
• L'interazione è una Q&A una tantum 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 extra; per compiti leggeri il sovraccarico può superare il lavoro.

Scegliere tra gli approcci

Prossimi passi