Parti dal pattern più semplice che funziona
Ricorri a un ciclo agentico solo quando il compito richiede davvero che il modello decida a runtime il numero e l'ordine dei passi. Una singola chiamata a un LLM, o un workflow fisso di passi LLM e di codice, è più economica, più veloce e molto più facile da testare. Fai: prototipa come workflow deterministico e aggiungi passi agentici solo dove puoi dimostrare che servono. Non fare: costruire un agente autonomo multi-passo per un compito che una catena di prompt strutturata risolve, perché erediti tutto il costo e l'imprevedibilità senza beneficio.
Ancora ogni affermazione fattuale al contesto recuperato
Nel RAG e negli agenti che usano strumenti, le risposte dovrebbero poggiare su evidenze fornite, non sulla memoria del modello, e il modello deve poter dire di non sapere. Questo rende gli output verificabili ed è la difesa principale contro le allucinazioni. Fai: istruisci il modello a rispondere solo dal contesto fornito, richiedi citazioni e permetti una risposta esplicita "il contesto non copre questo". Non fare: chiedere al modello di "essere utile e rispondere comunque" quando l'evidenza manca, perché fabbrica affermazioni sicure e non tracciabili.
Investi nella qualità del recupero prima che in quella della generazione
Il generatore può usare solo le evidenze che il retriever fa emergere, quindi il recupero fissa il tetto della qualità delle risposte. Misura recall e precision del retriever in modo indipendente prima di incolpare il prompt. Fai: regola il chunking, prova la ricerca ibrida (lessicale + vettoriale) e aggiungi il reranking quando i passaggi migliori non sono affidabilmente in cima. Non fare: continuare a riscrivere il system prompt per correggere risposte che in realtà sono sbagliate perché il passaggio giusto non è mai stato recuperato.
Mantieni l'insieme di strumenti piccolo, distinto e ben documentato
I modelli scelgono gli strumenti dalle loro descrizioni e schemi, quindi un insieme grande e sovrapposto causa chiamate sbagliate o malformate. Tratta la descrizione e lo schema di input di ogni strumento come il contratto rispetto al quale il modello pianifica. Fai: scrivi descrizioni precise, usa enum e campi obbligatori, e instrada o raggruppa le capacità quando ne hai molte. Non fare: esporre decine di strumenti piatti e simili aspettandoti che il modello li disambigui in modo affidabile.
Vincola sempre il ciclo dell'agente
Ogni ciclo agentico deve terminare in modo prevedibile, altrimenti un modello che continua a scegliere di agire andrà avanti finché non esaurisce il budget. Vincola il ciclo su più dimensioni. Fai: imposta un numero massimo di iterazioni, un tetto di token o costo, una soglia di errori e un chiaro segnale di "risposta finale", e logga ogni passo. Non fare: rilasciare un ciclo la cui unica uscita è il modello che decide di aver finito, il che invita loop infiniti e costi fuori controllo.
Rendi idempotenti le azioni degli strumenti e proteggi quelle irreversibili
Poiché gli agenti ciclano e ritentano, un'azione non idempotente può scattare più volte e causare danni reali. Progetta per un replay sicuro e metti un umano davanti a tutto ciò che è distruttivo. Fai: passa chiavi di idempotenza, rendi le scritture sicure sotto ripetizione e richiedi approvazione umana prima di inviare denaro, messaggi o modificare la produzione. Non fare: lasciare che un agente autonomo esegua effetti collaterali irreversibili senza un gate di approvazione, confidando che "di solito" faccia la cosa giusta.
Tratta le valutazioni come un gate di regressione, non come un ripensamento
Un eval set fisso valutato a ogni modifica è ciò che trasforma il ritocco dei prompt in ingegneria. Senza, non puoi dire se una modifica ha aiutato o ha rotto qualcosa in silenzio. Fai: mantieni un golden set di domande con contesti di grounding, misura faithfulness, relevancy e context recall (RAGAS / promptfoo / DeepEval) e fai fallire la CI sotto una soglia calibrata. Non fare: giudicare le modifiche controllando a mano qualche prompt e rilasciare a sensazione.
Ingegnerizza il contesto, non solo il prompt
Per gli agenti, la qualità dipende dall'assemblare nella finestra le informazioni giuste per ogni passo, i passaggi rilevanti, i risultati degli strumenti e la memoria, escludendo i distrattori. Fai: ripartisci la finestra di contesto tra system prompt, cronologia, recupero e output; taglia o riassumi i turni vecchi; limita i chunk recuperati. Non fare: ammassare l'intera conversazione e ogni documento recuperato nel prompt assumendo che una finestra grande renda inutile il context engineering.
Isola e diffida dei contenuti non fidati
Qualsiasi testo che l'agente non ha scritto, l'input dell'utente e specialmente le pagine web o i documenti recuperati, può portare payload di prompt injection. Trattalo come dato, mai come istruzioni. Fai: delimita ed etichetta chiaramente i contenuti non fidati, applica strumenti a privilegio minimo e mantieni le istruzioni di sistema autoritative su qualsiasi cosa nel testo recuperato. Non fare: concatenare i contenuti recuperati direttamente nella regione di istruzioni del prompt dove possono sovrascrivere le tue regole.
Usa temperature bassa e output strutturato per l'affidabilità
Gli agenti che devono chiamare strumenti, estrarre dati o produrre risultati consumabili dalla macchina hanno bisogno di un comportamento riproducibile. La casualità che aiuta i compiti creativi qui danneggia. Fai: usa una temperature bassa e vincola gli output a uno schema JSON (decodifica vincolata o interfaccia di tool-call) così che il codice a valle li analizzi in modo affidabile. Non fare: analizzare testo libero con regex fragili, o lasciare la temperature alta e poi arrovellarti su run instabili e incoerenti.
Controlla il costo deliberatamente lungo tutto il ciclo
Il costo si accumula su iterazioni e tool call, quindi gestiscilo come metrica di prima classe misurata per compito. Fai: metti in cache il grande prefisso statico del prompt, instrada i sotto-compiti facili a modelli più piccoli, limita il contesto recuperato, parallelizza le tool call indipendenti e traccia i token per run accanto alla qualità sul tuo eval set. Non fare: inviare un enorme system prompt non in cache a ogni turno e scoprire la spesa solo quando arriva la fattura.
Rendi osservabile ogni passo
Non puoi debuggare o migliorare ciò che non vedi, e gli agenti falliscono in punti non ovvi, un recupero sbagliato, una tool call malformata, un ciclo inatteso. Fai: logga il ragionamento di ogni iterazione, la tool call e i suoi argomenti, l'osservazione e il costo in token, idealmente con tracing che lega un run end-to-end. Non fare: trattare l'agente come una scatola nera e cercare di correggere i guasti indovinando sul prompt senza una traccia di cosa è davvero accaduto.
Preferisci prompting e RAG al fine-tuning per la conoscenza
Il fine-tuning incorpora informazioni nei pesi che diventano obsolete e non possono essere citate o modificate, mentre il RAG mantiene la conoscenza fresca, tracciabile e aggiornabile. Fai: usa il RAG per iniettare fatti e riserva il fine-tuning per comportamenti stabili come tono, formato o un'abilità ristretta e ripetuta. Non fare: fare fine-tuning di un modello per "insegnargli i tuoi dati" quando quei dati cambiano, cosa costosa da mantenere e più difficile da verificare del recupero.