Come funziona l'uso dei tool

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

Il contratto di utilizzo dei tool

L'uso dei tool è 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 di API classiche possono integrare l'uso dei tool nello stesso modo in cui integrerebbero qualsiasi altra interfaccia tipizzata: definisci lo schema, gestisci il callback, restituisci un risultato. La differenza è che il chiamante dall'altro lato è un modello di linguaggio che sceglie quale funzione invocare in base alla conversazione.

Dove vengono eseguiti i tool

L'asse principale lungo il quale i tool differiscono è dove viene eseguito il codice. Ogni tool rientra in uno di tre bucket, e il bucket determina di cosa è responsabile la tua applicazione.

Tool definiti dall'utente (eseguiti dal client)

Tu scrivi lo schema, tu esegui il codice, tu restituisci i risultati. Questo è l'evento principale: la stragrande maggioranza del traffico di utilizzo dei tool riguarda tool definiti dall'utente che chiamano logica specifica dell'applicazione.

Quando Claude decide di utilizzare uno dei tuoi tool, la risposta dell'API contiene un blocco tool_use con il nome del tool e un oggetto JSON di argomenti. La tua applicazione estrae questi argomenti, esegue l'operazione (una query di database, una chiamata HTTP, una scrittura di file, qualunque cosa faccia il tool) 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.

Tool dello schema Anthropic (eseguiti dal client)

Per un numero limitato di operazioni comuni (esecuzione di comandi shell, modifica di file, controllo di un browser, gestione della memoria del blocco note), Anthropic pubblica lo schema del tool e la tua applicazione gestisce l'esecuzione. I tool in questa categoria sono bash, text_editor, computer e memory.

Il modello di esecuzione è identico ai tool 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 utilizzare uno strumento dello schema Anthropic invece di definire il tuo equivalente è che questi schemi sono addestrati. Claude è stato ottimizzato su migliaia di traiettorie di successo che utilizzano esattamente queste firme di tool, quindi li chiama in modo più affidabile e si recupera dagli errori in modo più elegante rispetto a quanto farebbe con uno strumento personalizzato che fa la stessa cosa. Lo schema è l'interfaccia che il modello si aspetta già.

Tool eseguiti dal server

Per web_search, web_fetch, code_execution e tool_search, Anthropic esegue il codice. Tu abiliti il tool nella tua richiesta e il server gestisce tutto il resto. Non costruisci mai un blocco tool_result per questi tool perché il ciclo lato server esegue l'operazione e alimenta 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 indietro, ma nel momento in cui li vedi, l'esecuzione è già completata. Il compito della tua applicazione è abilitare il tool e leggere la risposta finale, non partecipare al ciclo di esecuzione.

Il ciclo agentivo (tool client)

I tool eseguiti dal client (sia definiti dall'utente che dello schema Anthropic) richiedono che la tua applicazione guidi un ciclo. Il modello non può eseguire il tuo codice, quindi ogni chiamata di tool è un round trip: 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 tool. Formatta gli output come blocchi tool_result.
4. Invia una nuova richiesta contenente i messaggi originali, la risposta dell'assistente e un messaggio dell'utente con i blocchi tool_result.
5. Ripeti dal passaggio 2 mentre stop_reason è "tool_use".

In pratica questo si legge come: mentre stop_reason == "tool_use", esegui i tool e continua la conversazione. Il ciclo esce su qualsiasi altro motivo di arresto ("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 la meccanica della costruzione di richieste, della gestione di chiamate di tool parallele e della formattazione dei risultati, vedi Gestire le chiamate di tool.

Il ciclo lato server

I tool eseguiti dal server eseguono il loro ciclo all'interno dell'infrastruttura di Anthropic. Una singola richiesta dalla tua applicazione potrebbe attivare diverse ricerche web o esecuzioni di codice prima che una risposta torni indietro. Il modello cerca, legge i risultati, decide di cercare di nuovo e itera finché non ha quello che gli serve, tutto senza che la tua applicazione partecipi.

Questo ciclo interno ha un limite di iterazione. Se il modello sta ancora iterando quando raggiunge il limite, la risposta torna indietro 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. Vedi Tool del server per il modello di continuazione.

Quando utilizzare i tool (e quando non farlo)

L'uso dei tool è appropriato quando l'attività 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, il meteo di oggi, il contenuto 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 prosa che contiene casualmente le informazioni, uno schema di tool applica la forma.
• Chiamare sistemi esistenti. Database, API interne, file system. L'uso dei tool è il ponte tra le richieste in linguaggio naturale e i sistemi che le soddisfano.

Il segnale che dovresti usare i tool: se stai scrivendo una regex per estrarre una decisione dall'output del modello, quella decisione avrebbe dovuto essere una chiamata di tool. Analizzare il testo in forma libera per recuperare l'intento strutturato è un segno che la struttura appartiene allo schema.

L'uso dei tool non è appropriato quando:

• Il modello può rispondere solo dall'addestramento. Riassunto, traduzione e domande di conoscenza generale non hanno bisogno di un round trip di tool.
• L'interazione è una domanda e risposta una tantum senza effetti collaterali. Se non c'è nulla da eseguire, non c'è nulla che uno strumento possa fare.
• La latenza della chiamata di tool dominerebbe una risposta banale. Ogni chiamata di tool è almeno un round trip extra; per attività leggere il sovraccarico può superare il lavoro.

Scelta tra gli approcci

Passaggi successivi