Guadagni:
- Definire un agente come "modello + strumenti + ciclo" e decidere quando è necessario
- Scrivere la definizione dello strumento con nome, descrizione e input_schema
- Monitoraggio del flusso e della gestione degli errori del ciclo tool_use e tool_result
Fino ad ora, il modello ha sempre svolto un compito: ricevere input di testo, produrre risposte di testo. Ma il lavoro reale spesso richiede qualcosa di più del semplice testo; eseguire un calcolo, interrogare un database, chiamare un'API, scoprire un tasso di cambio corrente. La modella non può fare queste cose da sola, ma può decidere quando devono essere fatte e chiedere a qualcuno di farle. Questo è ciò che l’uso degli strumenti fornisce al modello, e questa è la base degli agenti IA. In questa unità impareremo cos'è un agente, come viene definito lo strumento e come funziona il ciclo tool_use.
Cos'è un agente? Modello + Strumenti + Ciclo
Un agente AI è composto da tre parti: il modello (il cervello che prende la decisione), gli strumenti (le funzioni che il modello può chiamare: meteo, interrogazione del database, invio di e-mail) e il ciclo (il ciclo; il modello chiama lo strumento, ottiene il risultato, decide di nuovo cosa fare e così via).
Distinzione critica: una chiamata a modello singolo non è un agente. L'agente è un processo in cui il modello procede passo dopo passo, in ogni passaggio scegliendo la mossa successiva in base al risultato dello strumento. "Pensa come un essere umano, usa le mani, guarda il risultato, ripensaci."
Un fatto importante: il modello stesso non fa funzionare il veicolo. Il modello dice semplicemente "Voglio chiamare questo strumento con questi input". L'applicazione (chiamata cablaggio) esegue lo strumento e restituisce il risultato al modello. Questo è vitale per la sicurezza: il modello non tocca direttamente il tuo sistema; Ogni azione è sotto il tuo controllo.
Suggerimento: non cercare di risolvere tutti i problemi con l'agente. Agente; aumenta il rischio di ritardi, costi ed errori. Chiedi prima: "Sarà risolto con una singola chiamata o con un flusso di lavoro fisso?" Se la risposta è sì, non è necessario un agente. L'agente è destinato ad attività a tempo indeterminato in cui i passaggi non possono essere conosciuti in anticipo.
Definizione dello strumento: nome, descrizione, input_schema
Per introdurre uno strumento nel modello, devi fornire tre cose:
- nome: identità del veicolo, ad es. ottieni_meteo.
- descrizione: cosa fa lo strumento e quando chiamarlo. Questa è l'area più importante che consente al modello di scegliere lo strumento giusto al momento giusto. Scrivi non solo "cosa fa" ma anche "chiama quando".
- input_schema (schema di input): schema JSON che definisce quali parametri lo strumento si aspetta, in quale tipo.
# Definizione del veicolo (concettuale - schema JSON){ "name": "get_order_status", "description": "Recupera lo stato di spedizione corrente di un ordine. Chiama quando l'utente chiede dov'è un numero d'ordine o quando arriverà.", "input_schema": { "type": "object", "properties": { "order_no": {"type": "string", "description": "Numero ordine, es. SP-1024"} }, "richiesto": ["ordine_no"] }}
Regole per una buona descrizione dello strumento: nome chiaro e conciso, descrizione con "quando usarlo", descrizione per ogni parametro, inserendo quelli veramente obbligatori. Mantieni concentrato il numero di veicoli; Decine di modelli di veicoli simili sono sorprendenti.
zona
Cosa fa?
buon esempio
cattivo esempio
nome
Identificativo del veicolo
order_status_getir
portare
descrizione
Cosa fa + quando chiamare
"Restituisce lo stato del carico; chiama quando l'utente chiede dove si trova l'ordine"
"recupera i dati"
input_schema
Tipo di parametro e requisito
{order_no: stringa, annotato}
nessun diagramma/nessuna descrizione
uso_strumento → risultato_strumento Ciclo
Il ciclo funziona così, passo dopo passo:
- Invii la domanda dell'utente + le descrizioni dello strumento al modello.
- Il modello risponde direttamente o genera un blocco tool_use: "chiama order_durumu_getir con order_no=SP-1024."
- La tua applicazione esegue effettivamente lo strumento (interroga il database).
- Si invia il risultato al modello come tool_result.
- Con questo risultato, il modello produce la risposta finale o richiama un altro strumento. Il ciclo continua finché il modello non dice "Ho finito".
# Agent loop (concettuale)messages = [user_question] while True: risposta = model.uret(messages, tools=tool_definitions) if risposta.tur == "tool_use": risultato = cablaggio.run(response.tool_name, risposta.entries) # L'APPLICAZIONE esegue i messaggi += [risposta, tool_result(risultato)] # restituisce il risultato else: break # risposta finale; termina il ciclo
Gli SDK moderni offrono tool runner che eseguono questo ciclo per te; scrivi semplicemente le funzioni dello strumento. Ma questo è esattamente ciò che sta accadendo dietro le quinte.
Gestione degli errori
Gli strumenti potrebbero non funzionare: ordine non trovato, API scaduto, input non valido. Se non è possibile eseguire lo strumento, restituire l'errore al modello come tool_result descrittivo ("errore: numero ordine SP-9999 non trovato") e il flag di errore. Il modello può vederlo e spiegarlo gentilmente all'utente o provare un modo diverso. Non ingoiare l'errore e restituire risultati vuoti; Il modello deve sapere cosa è andato storto.
Descrizione del veicolo debole/forte
Debole (sostantivo indefinito, senza "quando"):
nome: "data", descrizione: "recupera dati"# Il modello non sa quando e come chiamare; O non chiama affatto oppure chiama in modo errato.
Forte (nome della rete + quando + descrizione del parametro):
name: "musteri_bakiyesi_getir"description: "Restituisce il saldo del conto corrente di un cliente. Chiama quando l'utente richiede debito, credito o saldo. NON effettua il pagamento."input_schema: {custeri_id: string ("ID cliente")}# Il modello chiama al momento giusto, con i parametri giusti, conoscendo il suo limite.
Tre mini custodie
Caso 1 – Agente non necessario. Un team ha creato l'attività di "riepilogo del testo" con un agente multi-strumento; Ogni riepilogo richiede 4 chiamate modello e 9 secondi. Il lavoro era in realtà un lavoro con una sola chiamata. Quando abbiamo rimosso l'agente e lo abbiamo ridotto a una singola chiamata, il tempo è sceso a 1,5 secondi e il costo è sceso a un quarto. Lezione: utilizzare l'agente quando veramente necessario.
Caso 2 – Spiegazione debole, chiamata sbagliata. In un agente di supporto, uno strumento oscuro chiamato recupero veniva chiamato in modo casuale dal modello sia nella domanda sul saldo che nella domanda sulla spedizione. Quando i veicoli sono stati divisi in balance_getir e cargo_durumu_getir e sono state aggiunte le spiegazioni "chiama quando", la selezione errata del veicolo è diminuita da 18 a 1 su 50 esempi.
Caso 3 — Errore ingoiato. Un agente restituiva risultati vuoti quando l'ordine non è stato trovato; Il modello ha interpretato questo come "l'ordine è stato consegnato" e ha ingannato il cliente. Quando il messaggio di errore viene scritto esplicitamente in tool_result ("ordine non trovato"), il modello dice correttamente "Non sono riuscito a trovare questo numero, puoi controllarlo?" cominciò a dire.
Errori comuni
- Affidare tutto a un agente: mentre una chiamata è sufficiente, l'agente aggiunge costi e ritardi.
- Descrizione vaga del veicolo: il modello non sa quando chiamare; sceglie sbagliato.
- Pensare che il modello guidi il veicolo: l'imbracatura guida il veicolo; la modella vuole e basta.
- Ingoiare l'errore: il modello deve sapere cosa è andato storto; Fornisci l'errore come open tool_result.
- Troppi veicoli simili: il modello si confonde; Mantieni il set di strumenti concentrato e minimo.
Attenzione: solo perché il modello dice "chiama quel veicolo" non significa che si debba agire. Sugli strumenti distruttivi (eliminazione, checkout, email) la tua applicazione non dovrebbe eseguire ciecamente la chiamata: questo è il fulcro dell'argomento sicurezza nella prossima unità.
In sintesi
- Agente = modello (decisione) + strumenti (funzioni) + ciclo (chiama strumento, ottieni risultato, decidi di nuovo).
- Una chiamata a modello singolo non è un agente; L'agente è un processo graduale.
- Il modello non guida il veicolo; L'applicazione viene eseguita (harness) e restituisce il risultato come tool_result.
- Lo strumento è identificato dal nome, dalla descrizione (in particolare "chiama quando") e input_schema.
- Il ciclo continua mentre tool_use → cablaggio viene eseguito → tool_result → modello continua finché il modello non dice "fatto"; gli errori vengono esplicitamente segnalati al modello.
Compito dell'applicazione
Progetta 3 strumenti della tua attività che possono essere forniti all'agente. (1) Scrivi nome, descrizione con "chiama quando" e input_schema per ciascuno; Che almeno uno sia uno strumento di lettura non distruttiva e uno di calcolo. (2) Scegli una domanda utente realistica e scrivi manualmente passo dopo passo (in un ciclo) quale di questi strumenti chiamerà il modello con quali input e cosa farà dopo l'arrivo di tool_result. (3) Impostare uno scenario in cui uno degli strumenti fallisce e mostrare come il messaggio di errore ritornerà al modello.
lista di controllo
- [] Posso definire l'agente come "modello + strumenti + ciclo" e decidere quando è necessario.
- [ ] So che l'imbracatura fa funzionare il veicolo, il modello lo vuole e basta.
- Posso scrivere una descrizione solida del veicolo con [] nome, descrizione ("chiama quando") e input_schema.
- Posso seguire il ciclo [] tool_use → tool_result passo dopo passo.
- [] Riporto gli errori dello strumento al modello come open tool_result.