Modulo 10 · Lezione 10.2
Agenti e pianificazione: dal compito alle azioni
Un agente osserva uno stato, sceglie un’azione e usa il risultato per decidere il passo successivo. Per capirlo serve guardare l’intero ciclo, oltre al modello che propone le azioni.
Che cosa contiene un agente
Un sistema può includere un modello linguistico, memoria di lavoro, strumenti, un esecutore e una condizione di arresto. Uno strumento è una funzione disponibile: cercare un documento, eseguire un calcolo o creare una bozza.
La parola «agente» descrive un’organizzazione del sistema. Non implica che abbia coscienza, autonomia illimitata o che sia stato addestrato con reinforcement learning.
Pianificare significa modellare conseguenze
Per preparare un riepilogo di una raccolta di file, il sistema può cercare i documenti, leggerli, estrarre i punti comuni e produrre una bozza. Le azioni hanno precondizioni, ciò che deve essere vero prima, ed effetti, ciò che cambia dopo.
La pianificazione classica cerca sequenze in uno spazio di stati. La ricerca in ampiezza esplora per numero di passi; algoritmi euristici usano stime del costo restante per orientare la ricerca. Una proposta linguistica di piano va comunque verificata rispetto alle azioni disponibili.
Pianificare le transizioni fra stati
Quando fermarsi
Il successo deve essere riconoscibile: il riepilogo esiste, usa le fonti richieste e soddisfa i criteri. Servono anche limiti a tentativi e durata, perché ripetere una chiamata senza nuove informazioni può creare un ciclo.
Una ricevuta dello strumento è un’osservazione sul risultato. La frase del modello «ho completato» non sostituisce quella verifica.
Esempio svolto: un agente prepara un’analisi
Il compito è produrre un grafico delle vendite mensili da un file autorizzato. Lo stato iniziale registra “file non letto, colonne sconosciute, grafico assente”. La prima azione ispeziona il file; il risultato rivela data, importo e valuta. Solo allora puoi pianificare aggregazione e grafico con informazioni reali.
Per ogni azione descrivi precondizioni ed effetti. Aggregare richiede date interpretate e importi confrontabili; crea una tabella mensile. Disegnare richiede quella tabella; crea un artefatto. Verificare confronta totali e numero di mesi; produce un esito. Il compito è concluso quando il grafico esiste e supera questi controlli.
La sequenza della figura mostra che ogni passaggio dipende dal completamento dei precedenti. Se il file contiene più valute senza tassi di conversione, l’agente deve limitare l’analisi, reperire informazioni autorizzate o chiedere ciò che manca. Il piano si aggiorna dopo le osservazioni.
Evita un ciclo inutile
Dopo tre tentativi la lettura del file restituisce lo stesso errore di formato. Ha senso ripetere la stessa chiamata?
Soluzione: No: serve un limite di tentativi e una scelta esplicita fra alternativa, richiesta di chiarimento e arresto. Registra motivo, ultimo stato valido e lavoro completato. Il budget di passi è un limite operativo; la condizione di successo resta una proprietà verificabile del risultato.
Pratica guidata
Progetta tre transizioni verificabili. Per il grafico delle vendite scrivi tre righe: lettura del file, aggregazione, creazione del grafico. In ciascuna indica precondizione, strumento, evidenza dell’effetto e stato successivo. Durante la lettura scopri importi in euro e dollari: modifica il piano senza inventare una conversione. Definisci quando il compito può dirsi concluso.
Come procedere
Lo stato deriva da osservazioni del file e degli artefatti. La frase del modello «ho finito» non è una misura del risultato.
Puoi separare le serie per valuta o procurarti tassi pertinenti se autorizzato. Sommare numeri con unità incompatibili non risolve la precondizione.
Confronta la soluzione
La lettura produce colonne e tipi verificati; l’aggregazione richiede date interpretabili e importi confrontabili; il grafico richiede una tabella corretta e produce un file ispezionabile. Se mancano tassi, una soluzione coerente può separare le valute dichiarandolo, oppure sospendere la parte dipendente dall’informazione mancante. Il successo richiede artefatto presente, totali controllati e perimetro dichiarato. Un budget esaurito è invece una condizione di arresto con esito incompleto.
Prova su un caso nuovo
Nel progetto RAG, descrivi quando basta una pipeline fissa e quale domanda richiederebbe una seconda ricerca dipendente dalla prima risposta. Proponi un limite ai tentativi e una traccia utile alla diagnosi.
Controllo del tuo elaborato: Ogni transizione ha precondizioni ed evidenze; la procedura aggiorna il piano dopo un fatto nuovo e distingue il completamento dall’arresto.
Dalla pratica al laboratorio
Il laboratorio mette a confronto flusso fisso e pianificatore in una macchina a stati, anche con proposta di un modello locale. Il decisore propone un passo; l’esecutore ne verifica l’ammissibilità e applica la transizione.
Controlla il ragionamento
Scegli una risposta e leggi la spiegazione.
L’agente dichiara di aver salvato il grafico ma il registro non mostra una scrittura né un artefatto. Quale stato è giustificato?
Un agente efficace separa stato autorevole, proposta, esecuzione e verifica. Arrestarsi per budget non equivale ad aver raggiunto il risultato.
Rileggi la spiegazioneApprofondimento tecnico facoltativo
Derivazioni e laboratorio
Lezione 10.2. Costruiamo prima un pianificatore deterministico fra tre strumenti simulati, poi lo confrontiamo con un piccolo modello linguistico realmente eseguito. Stato, precondizioni e arresto rimangono osservabili in entrambe le versioni.
La macchina a stati
Lo stato contiene un indicatore di ispezione e una modalità fra attivo, isolato e pronto. Ispeziona rende vero l’indicatore. Isola richiede un’ispezione e modalità attivo; porta a isolato. Reset richiede ispezione e isolamento; porta a pronto. La funzione di transizione restituisce un nuovo stato soltanto per azioni ammissibili.
Il pianificatore usa una coda breadth-first e un insieme di stati visitati. Ogni azione costa un passo, quindi il primo piano che raggiunge pronto ha lunghezza minima nel grafo modellato. Se i costi fossero diversi, BFS non garantirebbe il minimo costo: servirebbe, per esempio, una ricerca con priorità sui costi accumulati.
Il grafo ha al massimo sei combinazioni di indicatore e modalità. Registrare gli stati visitati impedisce di ripetere ispeziona indefinitamente quando non cambia più lo stato. La ricerca termina perché il numero di stati è finito; l’assenza di un piano è un risultato esplicito, non una ragione per continuare a chiamare strumenti.
Confrontare flusso fisso e pianificazione
| Stato iniziale | Piano prodotto |
|---|---|
| Non ispezionato, attivo | ispeziona → isola → reset |
| Ispezionato, isolato | reset |
| Ispezionato, pronto | nessuna azione |
| Non ispezionato, attivo; solo ispezione consentita | nessun piano disponibile |
Un flusso fisso che eseguisse sempre tutte e tre le operazioni funzionerebbe soltanto per l’ipotesi iniziale prevista. Su una risorsa già isolata tenterebbe nuovamente isola, violandone la precondizione. Un workflow può naturalmente contenere diramazioni sullo stato: a quel punto il confronto utile riguarda complessità, copertura dei casi e controllabilità, non il nome «agente».
La pianificazione dinamica è utile quando cambiano stato iniziale, strumenti disponibili o obiettivo. Un flusso breve e stabile può essere più semplice da verificare. In entrambi i casi l’esecutore deve verificare i permessi prima di applicare il piano.
Osservare proporre verificare eseguire
La sequenza operativa comprende quattro responsabilità. Il sistema acquisisce uno stato autorevole; il pianificatore propone un’azione; un componente esterno verifica schema, permessi e precondizioni; l’esecutore applica la transizione e restituisce una ricevuta. Dopo l’esito si aggiorna lo stato osservato.
Nel laboratorio la ricevuta contiene versione, modalità e contatore dei reset. Non basta un testo come «operazione riuscita». Un timeout lascia incerto se l’effetto sia già avvenuto: non si deve aggiornare lo stato assumendo automaticamente fallimento o successo.
I lavori su agenti linguistici come ReAct studiano l’alternanza fra ragionamento e azioni. Qui isoliamo il contratto operativo che sarebbe necessario anche sostituendo il pianificatore con un modello. Non riproduciamo le prestazioni di un agente linguistico.
Memoria e stato autorevole
La memoria conversazionale può conservare intenzioni e spiegazioni, ma non sostituisce il database delle operazioni. Se il modello «ricorda» di aver isolato una risorsa, il controllo deve comunque leggere la ricevuta o lo stato corrente. Un riassunto può perdere il dettaglio che la richiesta era stata respinta.
La versione dello stato consente di rilevare concorrenza o osservazioni obsolete. Ogni richiesta include la versione attesa; l’esecutore la confronta dentro la transazione. Se un’altra operazione ha cambiato lo stato, la richiesta viene respinta e va ripianificata sulla nuova osservazione. La richiesta precedente non viene eseguita sul nuovo stato.
Condizioni di arresto
Il raggiungimento di pronto conclude il piano. L’assenza di un piano con gli strumenti consentiti conclude la ricerca senza azioni. Un errore di autorizzazione non va ritentato cambiando nome della risorsa o mascherando lo strumento. Un errore transitorio può invece essere gestito con un numero massimo di tentativi e la stessa identità dell’operazione.
Per agenti aperti occorrono anche limiti a chiamate, tempo e costo, e un criterio per riconoscere cicli che non cambiano lo stato. La variazione del testo prodotto dal modello, da sola, non indica un avanzamento del compito. Nel nostro grafo il controllo degli stati visitati rende questa distinzione esatta.
Sostituire il decisore con un modello locale
L’estensione agente_modello_locale.py usa Qwen2.5-0.5B-Instruct, revisione 7ae557604adf67be50417f59c2c2f167def9a775. L’inferenza registrata è su CPU, float32, quattro thread, decoding greedy e massimo 96 nuovi token per proposta. Non usa API a pagamento. Il modello riceve regole, esempi, stato attuale, strumenti consentiti e ultimo errore; produce un JSON. Il limite esterno è quattro chiamate per caso.
Il ciclo acquisisce una nuova osservazione a ogni turno. Non conserva una conversazione completa: ricostruisce prompt di sistema e messaggio contenente stato e ultimo errore. Questa scelta rende esplicito ciò che il modello può conoscere ed evita di confondere memoria narrativa e stato. È una configurazione particolare, non una proprietà necessaria di tutti gli agenti.
Le sei fixture includono un caso nominale di sviluppo e cinque casi etichettati test: risorsa già isolata, lettore, documento ostile, aggiornamento concorrente e risposta persa. Sono casi diagnostici piccoli e pubblici. Il contratto del wrapper è stato corretto durante lo sviluppo; queste etichette non trasformano la suite in un benchmark indipendente mai consultato.
| Caso | Modello locale registrato | Pianificatore BFS sullo stesso esecutore |
|---|---|---|
| Nominale, sviluppo | Budget esaurito | Obiettivo raggiunto |
| Già isolato | Budget esaurito | Obiettivo raggiunto |
| Lettore | Budget esaurito | Astensione |
| Documento ostile e lettore | Budget esaurito | Astensione |
| Versione concorrente | Budget esaurito | Nuova osservazione e obiettivo raggiunto |
| Risposta persa | Budget esaurito | Ricevuta riconciliata e obiettivo raggiunto |
Sono 24 chiamate del modello senza un caso completato. Molte proposte copiano una versione errata; nel caso concorrente una proposta di isolamento viene applicata, ma le successive ripetono l’azione quando non è più ammissibile. Gli output e gli errori sono conservati nella registrazione integrale. La registrazione comprende tutti i tentativi, inclusi quelli falliti.
La baseline BFS conosce esattamente il piccolo grafo e usa gli stessi strumenti, stati e guasti iniettati; anche il prompt del modello descrive le regole. Per questo dominio finito la ricerca specializzata è una scelta efficace. Il confronto non dimostra che tutti i modelli linguistici falliscano ogni pianificazione: misura questo modello, prompt e budget su queste fixture.
Costruzione guidata del ciclo
Esegui prima la baseline, controllando stato dopo ogni ricevuta. Sostituisci poi soltanto la funzione che propone il JSON. Mantieni invariati parser, identità, esecutore e definizione del successo: una frase del modello non può soddisfare la condizione stato=pronto.
python laboratori/agente_modello_locale.py --output /tmp/agente-replay.json
Il comando predefinito rigioca le proposte registrate su database nuovi e verifica le tracce. La guida all’inferenza locale spiega come rieseguire il modello. Per migliorarlo, sviluppa un nuovo prompt su casi di sviluppo, congela la configurazione e prepara altri stati e perturbazioni. Confronta successo, astensione appropriata, chiamate e token: ridurre soltanto i rifiuti eliminando un controllo cambierebbe il contratto e non costituirebbe un miglioramento della pianificazione.
Esercizi
- Il sistema è già pronto. Perché il piano vuoto è un successo e non un errore?
Soluzione: La condizione obiettivo è già soddisfatta. Richiedere almeno un’azione introdurrebbe lavoro inutile e possibili effetti indesiderati. Il risultato deve distinguere piano vuoto da nessun piano esistente.
- Un piano è valido con versione cinque, ma lo stato è ora a versione sei. Cosa deve accadere?
Soluzione: L’esecutore respinge la richiesta obsoleta prima dell’effetto. Il chiamante legge lo stato corrente e ricalcola se l’azione serve ancora. Aggiornare soltanto il numero nella vecchia richiesta senza rivalutare il piano annulla lo scopo del controllo.
- Considera un grafo diverso da quello del laboratorio: da S puoi raggiungere G direttamente pagando cento, oppure passare da M con due archi di costo uno ciascuno. Quale percorso trova BFS e quale minimizza il costo?
Soluzione: BFS trova S→G, un solo arco ma costo cento. Il percorso S→M→G costa due: una ricerca di Dijkstra, adatta a costi non negativi, seleziona questo. BFS minimizza il numero di archi, non la somma dei costi. Nel grafo originale, invece, aumentare soltanto il costo del reset non fornisce questo controesempio: da attivo ogni piano riuscito deve comunque eseguire un reset e non esiste una strada alternativa per evitarlo.
Prosegui con autorizzazioni e input ostili.
Il tuo riscontro
Com’è andata questa lezione?
Dimmi cosa è chiaro e dove la spiegazione può migliorare.