Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
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 la guida Definisci gli 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.
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.
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 indietro 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.
Per una manciata di operazioni comuni (gestire la memoria di lavoro, eseguire comandi shell, modificare file, controllare 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 a quello degli strumenti definiti dall'utente: la risposta contiene un blocco tool_use, il tuo codice esegue l'operazione e tu invii indietro 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 rispetto a quanto farebbe con uno strumento personalizzato che fa la stessa cosa. Lo schema è l'interfaccia che il modello già si aspetta.
Per web_search, web_fetch, code_execution e tool_search, è Anthropic a eseguire 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 restituisce l'output al 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.
Gli strumenti eseguiti dal client (sia quelli definiti dall'utente sia quelli 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:
tools e il messaggio dell'utente.stop_reason: "tool_use" e uno o più blocchi tool_use.tool_result.tool_result.stop_reason è "tool_use".In pratica si legge così: 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, la gestione delle chiamate parallele agli strumenti e la formattazione dei risultati, consulta Gestisci le chiamate agli strumenti.
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, il 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; 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 il controllo a te anche 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 torna 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.
L'uso degli strumenti è adatto quando il compito richiede qualcosa che il modello non può fare solo a partire dal testo:
Un segnale chiaro 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:
| Approccio | Quando usarlo | Cosa aspettarsi | Per saperne di più |
|---|---|---|---|
| Strumenti client definiti dall'utente | Logica di business personalizzata, API interne, dati proprietari | Gestisci tu l'esecuzione e il ciclo agentico | Definisci gli strumenti |
| Strumenti client con schema Anthropic | Operazioni di sviluppo standard (bash, modifica di file, controllo del browser) | Gestisci tu l'esecuzione; Claude chiama lo strumento in modo affidabile perché lo schema è integrato nell'addestramento | Riferimento degli strumenti |
| Strumenti eseguiti dal server | Ricerca web, sandbox di codice, recupero web | Anthropic gestisce l'esecuzione; tu leggi i risultati invece di produrli | Strumenti server |
Costruisci un agente passo dopo passo, da una singola chiamata a uno strumento fino alla produzione.
Specifica dello schema, descrizioni e tool_choice.
Elenco degli strumenti forniti da Anthropic.
Was this page helpful?