Agenti multi-step: scope, conferme, rollback

Un agente multi-step può fare lavoro utile proprio perché non si ferma alla prima risposta. Può esplorare, leggere, modificare, testare, correggere, riprovare. Ma questa autonomia va incorniciata: cosa può toccare, cosa deve chiedere, come si torna indietro.

La differenza tra un agente utile e uno pericoloso non è solo il modello. È la definizione di scope.

Perché questa lezione conta

Quando dai a un agente accesso a file, terminale, API o database, gli stai dando capacità reali. Un errore non produce solo testo sbagliato: può modificare file, consumare budget, creare record, inviare comunicazioni, cancellare dati o introdurre regressioni.

Gli sviluppatori esperti non bloccano l’autonomia per paura. La progettano con confini chiari, conferme nei punti critici e rollback praticabile.

Obiettivo operativo

Alla fine della lezione devi saper scrivere una scheda task per agente multi-step che definisca scope, permessi, criteri di stop, verifiche, conferme e strategia di rollback.

Scope operativo

Lo scope deve rispondere a domande concrete:

1. Qual è l’obiettivo singolo?
2. Quali file o risorse sono ammessi?
3. Quali file o risorse sono vietati?
4. Quali comandi può eseguire?
5. Quali dipendenze può aggiungere?
6. Quali cambiamenti sono fuori scope?
7. Come si verifica il risultato?

Esempio:

Obiettivo:
- arricchire le lezioni del modulo 7.

Ammesso:
- file Markdown in src/content/lezioni/prompt-engineering relativi alle lezioni 31-35.

Vietato:
- routing, deploy, config build, dipendenze.

Verifica:
- controllo frontmatter/ordine.
- npm run build.

Stop:
- fermarsi dopo il modulo e riportare risultato prima di passare al successivo.

Più il task è aperto, più lo scope deve essere esplicito.

Conferme umane

Non tutte le azioni richiedono conferma. Se l’agente deve leggere file o eseguire test, la conferma può rallentare senza ridurre molto rischio. Serve invece nei punti in cui un errore ha costo elevato.

Chiedi conferma per:

1. cancellazione o sovrascrittura massiva;
2. migrazioni dati;
3. deploy;
4. invio email o messaggi pubblici;
5. operazioni economiche;
6. modifica permessi;
7. installazione dipendenze non previste;
8. accesso a dati sensibili.

Una conferma utile mostra contesto:

Sto per modificare 4 file:
- A
- B
- C
- D

Motivo:
- adeguare schema dati alla nuova API.

Rischio:
- possibile impatto sui test di integrazione.

Rollback:
- commit precedente o patch inversa.

Non basta “procedo?”. L’utente deve poter decidere.

Rollback

Il rollback va progettato prima dell’azione. In codice può essere Git, patch inversa, snapshot, backup, transazione o feature flag. In un sistema applicativo può essere idempotenza, compensating action o stato “pending” prima della conferma.

Per agenti su codebase:

1. leggere git status prima;
2. distinguere modifiche proprie da modifiche preesistenti;
3. lavorare su blocchi piccoli;
4. eseguire test dopo ogni blocco;
5. riportare file toccati;
6. non usare comandi distruttivi senza richiesta esplicita.

Per agenti su API:

1. preferire dry run;
2. usare idempotency key;
3. creare record in stato bozza;
4. confermare prima della pubblicazione;
5. loggare correlazione tra richiesta e azione.

Criteri di stop

Un task multi-step deve avere stop chiari:

Stop per successo. Tutti i criteri di accettazione sono soddisfatti.

Stop per rischio. L’agente incontra un’azione non autorizzata.

Stop per ambiguità. Due scelte hanno impatto diverso e non esiste preferenza dichiarata.

Stop per budget. Troppi tentativi, troppo tempo, troppi token, costo previsto superato.

Stop per errore ripetuto. Stesso errore dopo più tentativi.

Senza stop, l’agente tende a compensare in modo creativo.

Scheda task riusabile

Task:
Contesto:
Obiettivo:
Scope incluso:
Scope escluso:
Tool ammessi:
Tool vietati:
Conferme richieste:
Verifiche:
Rollback:
Criteri di stop:
Output finale:

Questa scheda è più utile di un prompt lungo ma non strutturato. Riduce ambiguità e rende review e audit più semplici.

Laboratorio guidato

Scegli un task realistico da 30 minuti:

1. refactor di un modulo;
2. arricchimento contenuti;
3. generazione test;
4. analisi bug;
5. integrazione API demo.

Compila la scheda task. Poi prova a far eseguire il task a un agente o simula i passi. Segna ogni punto in cui l’agente avrebbe potuto uscire dallo scope e aggiungi una regola per impedirlo.

Output atteso

Devi ottenere una scheda task pronta per agenti CLI o agenti applicativi, con:

1. scope verificabile;
2. azioni ammesse e vietate;
3. conferme richieste;
4. strategia rollback;
5. verifiche finali;
6. condizioni di stop.

Errori comuni

Scope espresso come intenzione. “Sistema il modulo” non è scope. Servono risorse, limiti e criteri.

Conferme troppo frequenti. Se chiedi conferma a ogni passo, l’agente non lavora. Se non la chiedi mai, rischi effetti laterali.

Rollback teorico. “Si può tornare indietro” non basta. Devi sapere come.

Ignorare modifiche preesistenti. In una working tree sporca, l’agente deve preservare il lavoro non suo.

Checklist di verifica

• lo scope dice cosa è incluso e cosa è escluso;
• so quali azioni richiedono conferma;
• esiste un rollback praticabile;
• le verifiche sono comandi o criteri osservabili;
• il task ha stop condition prima di iniziare.

Collegamenti

• Modulo: Agenti, tool use, integrazione — questa lezione è la numero 33 del corso.
• Si collega alla sicurezza dei tool della lezione 34.