Loop di agente: piano, azione, osservazione

Un agente non è un prompt più lungo. È un ciclo: riceve un obiettivo, decide un passo, usa un tool, osserva il risultato, aggiorna lo stato e decide se continuare. La qualità non dipende solo dalla risposta finale, ma da ogni transizione del ciclo.

Quando un agente sbaglia, spesso il problema è in uno di questi punti: piano troppo vago, tool sbagliato, osservazione interpretata male, contesto cresciuto troppo, condizione di stop assente.

Perché questa lezione conta

Se usi agenti per leggere file, modificare codice, cercare documentazione o orchestrare API, devi saperli diagnosticare. Dire “il modello ha sbagliato” non basta: devi sapere in quale passaggio il flusso ha perso controllo.

Il loop agentico rende visibile una cosa che nel prompting semplice resta nascosta: il modello prende decisioni intermedie. Ogni decisione intermedia può essere guidata con prompt, schema, vincoli, osservabilità e limiti.

Obiettivo operativo

Alla fine della lezione devi saper descrivere un loop agentico, leggere una traccia di esecuzione e identificare dove intervenire: prompt, tool schema, contesto, budget, permessi o condizione di terminazione.

Il ciclo base

Una forma pratica del loop:

obiettivo
  -> piano breve
  -> scelta tool
  -> chiamata tool
  -> osservazione
  -> aggiornamento stato
  -> prossimo passo o stop

Il piano non deve essere una catena di ragionamento privata o prolissa. Deve essere un piano operativo verificabile: cosa farà, in quale ordine, con quali limiti.

Esempio:

Piano:
1. Leggere package.json per capire comandi disponibili.
2. Cercare i componenti che renderizzano la pagina corso.
3. Modificare solo i file dati/contenuto necessari.
4. Eseguire build.
5. Riportare file toccati e verifiche.

Questo piano è utile perché puoi accorgerti subito se lo scope è sbagliato.

Osservazione

L’osservazione è il risultato del tool. Deve essere abbastanza ricca da guidare il passo successivo, ma non così rumorosa da saturare il contesto.

Un errore frequente è incollare output enormi: log completi, file interi, liste infinite. L’agente poi deve distinguere segnale e rumore. Meglio progettare tool che restituiscano output sintetici, filtrabili o paginati.

Stato e memoria di sessione

A ogni iterazione l’agente vede una combinazione di:

1. istruzioni iniziali;
2. obiettivo utente;
3. piano o stato corrente;
4. tool disponibili;
5. osservazioni precedenti;
6. eventuali file o dati letti.

Questo contesto cresce. Se cresce senza sintesi, l’agente perde attenzione sui vincoli importanti. Serve quindi una strategia: riassumere osservazioni, mantenere una lista di decisioni, scartare output non più utile, preservare errori e vincoli.

Una buona memoria di sessione contiene:

Fatti confermati:
- il progetto usa Astro.
- le lezioni sono Markdown in src/content/lezioni.
- il build command e npm run build.

Decisioni:
- procedere un modulo alla volta.
- verificare dopo ogni blocco.

Vincoli:
- non toccare routing/deploy.
- non usare script bulk per riscrivere contenuti.

Condizioni di stop

Un agente senza stop condition può continuare a esplorare, rifinire o consumare budget.

Definisci prima:

Successo. Quale output dimostra che il task è completo?

Fallimento. Quando deve fermarsi e chiedere aiuto?

Budget. Quante iterazioni, tool call, minuti o token può usare?

Rischio. Quali azioni richiedono conferma?

Ambiguità. Quando una decisione non va presa autonomamente?

Nel prompt puoi scrivere:

Fermati quando build e controllo contenuti passano.
Se trovi modifiche non correlate in file che devi editare, leggile e lavora con esse.
Non proseguire oltre tre tentativi sullo stesso errore senza riportare il blocco.

Dove intervenire quando sbaglia

Tool sbagliato. Migliora descrizione tool, nomi, esempi negativi o allow-list.

Troppe azioni. Riduci scope, aggiungi step di conferma, imposta limite iterazioni.

Output finale incompleto. Aggiungi criteri di accettazione e checklist.

Ripete lo stesso errore. Migliora osservazione del tool o aggiungi memoria di errori già incontrati.

Ignora vincoli. Sposta vincoli critici fuori dal prompt: validazione runtime, permessi, policy.

Laboratorio guidato

Esegui o simula un agente su un task reale di 15-20 minuti. Registra una tabella:

step | piano | tool scelto | input tool | osservazione | decisione successiva | nota

Dopo l’esecuzione, marca ogni step come:

1. corretto;
2. inefficiente ma accettabile;
3. sbagliato;
4. rischioso.

Poi proponi una modifica per ogni step problematico: prompt, schema, permesso, output tool o stop condition.

Output atteso

Devi produrre una scheda diagnostica per agenti nel tuo dominio:

1. loop atteso;
2. tool principali;
3. errori frequenti;
4. segnali di stop;
5. dati da tracciare;
6. interventi correttivi.

Questa scheda diventa la base per progettare agenti multi-step nel prossimo modulo.

Errori comuni

Confondere piano con spiegazione lunga. Il piano deve guidare azioni, non riempire contesto.

Non osservare le osservazioni. Se non leggi i risultati dei tool, non puoi capire perché l’agente devia.

Lasciare budget implicito. Senza limite l’agente tende a continuare, soprattutto nei task aperti.

Chiedere all’agente di essere prudente senza controlli. La prudenza va tradotta in permessi, stop e conferme.

Checklist di verifica

• so descrivere il ciclo piano-azione-osservazione;
• ho una traccia leggibile di almeno una run;
• distinguo errori di prompt da errori di tool schema;
• ho condizioni di successo e fallimento esplicite;
• so quali dati loggare per debuggare un agente.

Collegamenti

• Modulo: Agenti, tool use, integrazione — questa lezione è la numero 32 del corso.
• Si collega a scope, conferme e rollback della lezione 33.