Come rendere affidabile un agente AI: piano passo passo dalla misura al lavoro autonomo

Perché un agente non è affidabile anche con un modello forte

L'affidabilità è una proprietà dell'intero sistema, non del solo modello. Un compito lungo è fatto di decine di passi e gli errori si accumulano: se ogni passo è corretto al 95%, una catena di dieci passi senza alcun errore riesce in circa il 60% delle esecuzioni (0.95^10 ≈ 0.60), una di cinquanta passi in meno del 10%. L'accuratezza del modello non la puoi aumentare, ma puoi individuare l'errore nello stesso passo in cui avviene e renderlo economico. È proprio ciò che fa l'harness: istruzioni, strumenti, ambiente, stato e feedback attorno al modello.

Il piano che segue porta dalle impressioni a un'affidabilità misurabile e da lì al lavoro autonomo. I passi sono in ordine di efficacia: ciascuno si appoggia al precedente.

Passo 1. Smetti di valutare a sensazione

Un ingegnere è convinto che il nuovo prompt abbia cambiato tutto, un altro non vede differenze, e nessuno ha misurato nulla. Comincia con un registro dei fallimenti: ogni volta che l'agente si blocca, rompe qualcosa o dichiara completata una funzionalità che non funziona, scrivi una riga.

| data  | compito          | cosa è successo                | componente     |
|-------|------------------|--------------------------------|----------------|
| 10.10 | sconto nel carrello | "fatto", e2e non eseguito | feedback       |
| 10.10 | webhook pagamenti | non è riuscito ad avviare il DB | ambiente       |
| 11.10 | refactoring API  | ha ripetuto una soluzione scartata | stato        |

La colonna "componente" è la più importante. Dopo una settimana si vede dove sta il collo di bottiglia e correggerai quello, non tutto. Misurare l'affidabilità solo dalle esecuzioni riuscite è un errore: è il registro degli inciampi a mostrare dove l'agente cade.

Passo 2. Introduci due metriche: MTBF e MTTR

L'affidabilità si misura con due numeri. Per l'agente, l'MTBF (tempo medio tra i guasti) è quanti passi compie prima di incepparsi. L'MTTR (tempo medio di ripristino) è quanto tempo serve per tornare a uno stato funzionante dopo un guasto. La disponibilità cresce con entrambi: aumenta il primo o diminuisce il secondo.

Inseguire un agente che non sbaglia mai è una corsa senza fine. Ridurre l'MTTR di solito è possibile in un giorno. Parti quindi dal secondo numero.

Passo 3. Rendi economico l'errore

All'agente si può concedere autonomia non quando ha smesso di sbagliare, ma quando il costo dell'errore è sceso quasi a zero. Per questo servono tre cose:

• Commit piccoli e puliti — ogni modifica si può annullare con un solo comando.
• Isolamento — l'agente lavora su un branch o una copia di lavoro separata, per esempio con git worktree, e in una sandbox senza accesso alla produzione.
• Script di reset dell'ambiente — database, dipendenze e servizi tornano allo stato iniziale con un solo comando.

git worktree add ../shop-agent -b agent/discount
cd ../shop-agent
make reset   # ricrea il database, applica le migrazioni, carica le fixture

Misura con il cronometro quanto dura il ritorno completo allo stato funzionante: è il tuo MTTR. Limita anche il raggio dei danni: fissa un tetto alla dimensione delle modifiche di un singolo compito e vieta la modifica di file fuori dal suo perimetro.

Passo 4. Chiudi il ciclo di feedback

Senza verifiche l'agente è il proprio unico giudice e considera sinceramente il lavoro concluso. Dagli comandi con cui si controlla da solo e rendili obbligatori.

• Fail-fast: la verifica si ferma al primo errore con un messaggio chiaro, senza produrre cento righe di rumore.
• Controlli rapidi dopo ogni modifica: linter e controllo dei tipi tramite l'hook dell'agente.
• Ridondanza: una seconda verifica indipendente della stessa proprietà — per esempio uno scenario E2E sopra gli unit test. I test unitari verdi non dimostrano che la funzionalità funzioni per l'utente.

Scrivi il criterio di "fatto" come condizione verificabile: "lo scenario E2E dell'ordine con codice promozionale passa", non "lo sconto è implementato".

Passo 5. Sposta la memoria nei file

L'agente non ricorda la sessione precedente. Tutto ciò che serve per riprendere il lavoro deve vivere nel repository: obiettivo, lavoro svolto e come è stato verificato, decisioni con le loro motivazioni, vicoli ciechi, prossimo passo. Un buon segnale: una nuova sessione che riceve solo il repository e la parola "continua" inizia subito un lavoro utile.

Una cronologia della conversazione lunga e compressa dà una sensazione di continuità, ma perde la cosa più preziosa: le ragioni delle decisioni scartate. Azzerare la sessione in modo consapevole, con uno stato scritto completo, di solito costa meno.

Passo 6. Un compito alla volta

Legge di Little: il numero di compiti in corso è uguale al tasso di arrivo moltiplicato per il tempo che ciascun compito trascorre nel sistema. A capacità fissa, i compiti paralleli non accelerano il lavoro, ma allungano ciascuno di essi. Per un agente è ancora più vero: tre funzionalità significano tre modelli di dominio nella stessa finestra di contesto.

• Tieni WIP=1: una funzionalità alla volta, fino a un risultato verificato.
• Taglia i compiti in pezzi piccoli: una capacità utente verificabile, 1–3 file, verifica più breve di un minuto.
• Tieni un BACKLOG.md — una valvola per le cose "già che ci sei". Se noti un difetto vicino, una riga nel backlog, non una modifica di propria iniziativa.

Passo 7. Separa chi esegue da chi verifica

L'autovalutazione dell'agente è un freno debole: la sessione che ha scritto il codice tende a considerarlo corretto. Fai valutare il risultato a un subagent o a una sessione separata, che riceva solo il requisito, il diff e i risultati delle verifiche, non il ragionamento di chi ha eseguito. Il verdetto del revisore deve basarsi su verifiche automatiche, non su "sembra a posto".

Passo 8. Affida l'agente a un ciclo autonomo

L'harness rende affidabile una singola esecuzione, il ciclo rende autonoma una serie di esecuzioni. Un ciclo costruito su un harness scadente moltiplica solo più in fretta gli errori, quindi questo passo viene per ultimo. Il ciclo più semplice si descrive in tre righe:

Obiettivo:   lo scenario di pagamento e2e con codice promozionale passa
Verifica:    make lint && make test && make e2e
Stop:        obiettivo raggiunto OPPURE 15 tentativi OPPURE 2 ore → chiama una persona

Scegli il tipo di ciclo in base al compito. Se il lavoro ha un traguardo finale, serve un ciclo orientato all'obiettivo: memoria dei progressi, revisore indipendente e budget di passi. Se non ha una fine (il controllo CI del mattino, l'analisi di nuovi errori), va bene un ciclo a calendario. L'errore frequente è pianificare a calendario un lavoro che ha una fine: ogni esecuzione lo riparte da zero.

Regole per un'autonomia sicura

• La condizione di arresto deve essere solo verificabile dalla macchina, con un limite di tentativi e di budget.
• Escalation: elenca in anticipo ciò di cui il ciclo non deve fidarsi (migrazioni di produzione, denaro, cancellazione di dati).
• Se il compito è bloccato e i progressi non crescono davvero, è il segnale per passarlo a una persona, non per far girare ancora il ciclo.
• Leggi i diff. La velocità del ciclo non deve superare la tua velocità di lettura, altrimenti smetti di capire la tua base di codice.

Errori frequenti lungo questa strada

Partire riscrivendo le istruzioni

La risposta più diffusa a un fallimento dell'agente è aggiungere una regola a AGENTS.md. Dopo qualche mese il file è di centinaia di righe e le regole importanti vi si perdono. Se il registro dei fallimenti mostra che l'agente non ha eseguito le verifiche, correggi il feedback: il comando di verifica e l'hook, non un altro paragrafo di testo.

Correggere tutto in una volta

Viene voglia di migliorare contemporaneamente i cinque componenti dell'harness. Ma così non si capisce che cosa abbia davvero aiutato. Valuta ciascun componente da 1 a 5, dedica mezz'ora al più debole ed esegui le stesse cinque attività tipiche prima e dopo. La differenza nel registro dei fallimenti dirà se c'è stato un effetto.

Confondere "test verdi" con "funzionalità funzionante"

L'agente può scrivere un test che verifica la propria implementazione e non il requisito. Un test del genere è sempre verde. La difesa è un controllo a livello utente (scenario E2E), scritto prima dell'implementazione o da un verificatore indipendente, e la regola che l'agente non modifichi il test per farlo passare.

Disattivare la verifica per velocità

Le verifiche lente tentano di saltarle "questa volta". Conviene separarle: linter e controllo dei tipi rapidi dopo ogni modifica, l'intera suite di test ed E2E prima di dire "fatto". Così il ciclo di feedback resta breve e non intralcia il lavoro.

Considerare l'ablation il primo passo

È possibile disattivare un componente alla volta dell'harness e osservare quanto cala la qualità. È un controllo utile, ma costoso e non il primo: prima il registro dei fallimenti indica il collo di bottiglia, l'ablation si limita a confermare l'ipotesi. Se disattivando un componente il calo è nullo, non significa che sia inutile: forse i compiti scelti non lo hanno mai usato.

La scala della maturità

Conclusione

Per rendere affidabile un agente AI: misura, individua nel registro dei fallimenti il componente debole, rendi economico l'errore, chiudi il ciclo di feedback, sposta la memoria nei file, tieni un solo compito alla volta e separa chi esegue da chi verifica. Solo allora un ciclo autonomo con una condizione di arresto verificabile dalla macchina diventa sicuro. Ogni passo di questo piano è mostrato in pratica in un corso su un progetto reale.