Guida applicativaRecupero Agenti

Retry non è recovery.

I sistemi che riprovano in silenzio, o spariscono a metà task, non stanno facendo recovery. Real recovery mostra dove il lavoro si è fermato, cosa è sopravvissuto e come procedere da qui.

Di Michelangelo Zampogna · Pubblicata il 22 aprile 2026

Fatti chiave

Best fit: Team operations, supporto, finance e contesti enterprise con agenti multi-step che durano minuti, ore o giorni
Primary risk: Abbandono silenzioso e duplicazione degli effetti collaterali durante il resume
Core shift: Loop di retry → sistema di recupero esplicito
Success signal: Le run terminano con stati nominati, output parziali preservati e azioni di ripresa chiare
Doctrine mapping: P2, P8, P9, P10

Il recupero è una parte del prodotto, non solo dell'infrastruttura

Gli agenti long-running lavorano su memoria, tool, API esterne e approvazioni differite, quindi l'errore raramente è un evento isolato: più spesso è un processo interrotto con effetti parziali già prodotti. Se il sistema si limita a ritentare in background o abbandona la run, il team perde visibilità sul progresso, aumenta il rischio di azioni duplicate e non sa dove riprendere in sicurezza. Un buon recovery design assegna a ogni interruzione uno stato leggibile, un checkpoint affidabile e un prossimo passo comprensibile per le persone. Written by the AI Design Blueprint editorial team. Doctrine grounded in the 10 Blueprint Principles.

Perché il recovery design per agenti long-running conta oggi

Gli agenti long-running operano per minuti, ore o giorni, attraversando tool, memoria e sistemi esterni. Per questo il recovery design è centrale: P2 – Ensure that background work remains perceptible e P9 – Represent delegated work as a system, not merely as a conversation richiedono che il lavoro interrotto resti visibile, riprendibile e verificabile.

Senza recupero esplicito, un output finale apparentemente corretto può nascondere scritture duplicate, contesto obsoleto o lavoro parziale perso.

Snapshot e rehydration semplificano il riavvio tecnico, ma il prodotto deve comunque mostrare stati di errore comprensibili e confini di ripartenza.

L'obiettivo non è l'uptime perfetto, ma la continuazione sicura del lavoro.

Perché l'approccio standard basato sui retry fallisce per gli agenti long-running

Molti team trattano il recupero come un problema solo infrastrutturale: ritenta la chiamata, riavvia il worker, riesegui tutto il task. Negli agenti questo non basta, perché P5 – Replace implied magic with clear mental models e P8 – Make hand-offs, approvals, and blockers explicit impongono di mostrare cosa è stato tentato, cosa è stato completato e quale decisione manca.

I retry nascosti rendono opaco se l'agente stia facendo progressi o stia ripetendo lo stesso errore.

Le riesecuzioni complete mescolano passaggi innocui in sola lettura con side effect rischiosi, causando email doppie, doppie registrazioni o modifiche in conflitto.

L'abbandono silenzioso lascia output parziali senza proprietario, senza prossimo passo e senza percorso di recupero.

Un semplice transcript conversazionale non basta per capire da quale checkpoint riprendere, indebolendo P7 – Establish trust through inspectability.

Come Blueprint sostituisce il recupero basato sui retry per agenti long-running

Blueprint trasforma il recupero da meccanismo nascosto a superficie operativa di prima classe. Con P8 – Make hand-offs, approvals, and blockers explicit, P9 – Represent delegated work as a system, not merely as a conversation e P10 – Optimise for steering, not only initiating, ogni run espone stato, checkpoint, completamento parziale e azioni di recovery disponibili.

Definisci stati nominati come running, blocked, awaiting approval, partial complete, recovered e failed closed secondo P6 – Expose meaningful operational state, not internal complexity.

Inserisci checkpoint attorno a confini di business significativi, non a ogni token o singolo tool call.

Separa le azioni di recovery reversibili da quelle che richiedono approvazione.

Conserva gli artefatti completati e i gap irrisolti in un registro di completamento parziale, invece di ridurre tutto a successo o fallimento.

Permetti agli operatori di guidare il recupero: retry dal checkpoint, sostituzione input, skip di un passaggio reversibile o chiusura con motivazione.

Come implementare il recovery design per agenti long-running

Parti dalla più piccola unità di lavoro recuperabile e dal punto più sicuro da cui riprendere dopo un'interruzione. P6 – Expose meaningful operational state, not internal complexity e P7 – Establish trust through inspectability implicano che i checkpoint debbano catturare progresso di business e condizioni operative utili, non solo trace tecniche.

Crea checkpoint prima e dopo ogni side effect esterno; salva intent, riferimenti agli input, ID degli artefatti, stato delle approvazioni e idempotency key.

Classifica i fallimenti in retryable, recoverable-with-steering, approval-required e failed-closed usando P8 – Make hand-offs, approvals, and blockers explicit.

Registra il completamento parziale come output di prima classe: elementi completati, saltati, in attesa e assunzioni usate.

Al resume confronta il contesto corrente con quello salvato nel checkpoint per intercettare drift prima del replay, in linea con P5 – Replace implied magic with clear mental models.

Mostra il prossimo passo in linguaggio operativo: safe to retry, needs approval, source changed o manual fix required.

Brief di partenza

Task: complete a multi-step workflow over durable checkpoints
Scope: read approved sources, call listed tools, and write only to pre-authorised systems within the run boundary
Escalate when: replay could repeat a side effect, source context has drifted, or a policy-gated decision is required
Success signal: the run ends in a named state with completed outputs preserved, pending work listed, and a visible resume or hand-off path

Livelli di escalation e governance

Usa questi livelli per separare le azioni di recupero sicure da quelle che richiedono revisione, seguendo P8 – Make hand-offs, approvals, and blockers explicit.

Tier	Action type	Risk level	Required approval
Tier 1 — Autonomo	Replay di step in sola lettura, refresh del contesto scaduto o resume da checkpoint senza ripetere side effect	Basso	Pre-approvato all'avvio del task
Tier 2 — Recupero guidato	Resume con input scelto dall'operatore, skip di uno step reversibile o chiusura di una nota di completamento parziale	Medio	Approvazione dell'operatore nella run view
Tier 3 — Decisione umana	Ripetizione di una scrittura esterna, modifica delle regole di business, scarto del lavoro parziale o override di un blocco	Alto	Approvazione umana esplicita per l'azione specifica

Anti-pattern vs. pattern Blueprint

Questa tabella aiuta a sostituire comportamenti di recovery opachi con una progettazione ispezionabile della run, coerente con P2 – Ensure that background work remains perceptible e P9 – Represent delegated work as a system, not merely as a conversation.

Anti-pattern: Retry silenziosi in background senza cambi di stato visibili
Pattern Blueprint: Stato di retry nominato con numero di tentativi, blocco corrente e controlli umani per fermare o riprendere

Anti-pattern: Rieseguire l'intero workflow dopo qualsiasi errore
Pattern Blueprint: Resume dall'ultimo checkpoint sicuro con protezione di idempotenza attorno ai side effect

Anti-pattern: Trattare l'output parziale come fallimento totale
Pattern Blueprint: Registro di completamento parziale che mostra cosa è finito, cosa è pendente e quali assunzioni sono state usate

Anti-pattern: Messaggi generici come sistema fallito
Pattern Blueprint: Stati di errore operativi tradotti in linguaggio utente con il prossimo passo richiesto

Anti-pattern: Transcript chat come unica superficie di recupero
Pattern Blueprint: Run view persistente con checkpoint, approvazioni, blocchi e percorsi di recovery disponibili

Prova nel mondo reale

Scenario illustrativo

Due tracce anonime mostrano perché il recupero esplicito funziona meglio della semplice riesecuzione completa.

Un team ha usato un runner finanziario con checkpoint. L'agente ha tentato di riconciliare 312 fatture e aggiornare gli stati. Il sistema ha mostrato un blocco quando, dopo un timeout di rete, il resume avrebbe potuto duplicare una scrittura. L'operatore ha autorizzato il replay dall'ultimo checkpoint in sola lettura. Il team ha preservato il lavoro completato senza doppie registrazioni.

Un team ha usato un workflow di triage documentale con snapshot durevoli. L'agente ha tentato di estrarre clausole da 1.400 contratti, ma una dipendenza di retrieval è cambiata durante la run. Il sistema ha marcato gli output precedenti come completamento parziale ed è escalato perché i riepiloghi downstream non combaciavano più con il corpus. Il revisore ha ripreso la run con una base documentale congelata.

Domande frequenti

Domande comuni per i team che stanno introducendo percorsi di recupero espliciti nei sistemi agentici.

Che cosa conta davvero come checkpoint in un workflow agentico?

Un checkpoint è un confine di recupero durevole che conserva abbastanza stato da permettere il resume senza ipotesi arbitrarie. In base a P6 – Expose meaningful operational state, not internal complexity, deve riflettere progresso di business: elementi processati, approvazioni ottenute, output creati e side effect già eseguiti.

Ogni quanto un agente long-running dovrebbe creare un checkpoint?

Il checkpoint va creato in corrispondenza di confini di business significativi, soprattutto prima e dopo side effect esterni, non dopo ogni micro-passaggio. P6 – Expose meaningful operational state, not internal complexity favorisce punti di ripresa che abbiano senso per chi deve operare o approvare.

Quando il sistema può fare auto-retry invece di escalare?

L'auto-retry è sensato quando lo step è reversibile, privo di side effect e il replay non cambia il significato della run. Se il replay può duplicare un'azione, alterare un esito di business o nascondere un blocco, P8 – Make hand-offs, approvals, and blockers explicit richiede di renderlo visibile.

Come va mostrato il completamento parziale agli utenti?

Il completamento parziale va trattato come esito legittimo della run, non come errore travestito. Con P9 – Represent delegated work as a system, not merely as a conversation, l'utente deve vedere ciò che è stato completato, ciò che resta pendente, ciò che è stato saltato e le assunzioni che hanno guidato il lavoro.

Cosa deve comparire in una recovery UI?

Al minimo: stato corrente, ultimo checkpoint sicuro, lavoro completato, blocco irrisolto, prossima azione consigliata e ruolo che può approvarla. Questa struttura segue P2 – Ensure that background work remains perceptible e P10 – Optimise for steering, not only initiating.

Come si evitano side effect duplicati dopo il resume?

Servono idempotency key, registri di intent prima della scrittura e metadati di checkpoint che distinguano gli effetti già confermati da quelli ancora da eseguire. P7 – Establish trust through inspectability è essenziale, perché l'operatore deve poter capire perché un replay è sicuro o perché una scrittura deve restare bloccata.

Tutte le azioni di recovery richiedono approvazione umana?

No. P8 – Make hand-offs, approvals, and blockers explicit supporta una governance a livelli: il replay a basso rischio può essere pre-approvato, mentre scritture rischiose, cambi di regola e scarto del lavoro parziale devono avere un'approvazione specifica.

Checklist per iniziare

Mappa il workflow in stati nominati come running, blocked, awaiting approval, partial complete, recovered e failed closed usando P6 – Expose meaningful operational state, not internal complexity.
Inserisci checkpoint prima e dopo ogni side effect esterno.
Salva idempotency key, riferimenti alle fonti, approvazioni, ID degli artefatti e metadati di recovery in ogni checkpoint.
Definisci quali azioni di recupero sono autonome, quali richiedono approvazione e quali sono manuali usando P8 – Make hand-offs, approvals, and blockers explicit.
Aggiungi una run view che mostri lavoro completato, lavoro pendente, blocchi e opzioni di resume usando P2 – Ensure that background work remains perceptible e P10 – Optimise for steering, not only initiating.
Open Blueprint to validate your architecture.

Valida l'architettura

Prossimi passi

Scegli un workflow long-running già esistente e individua dove può fallire, bloccarsi o produrre output parziali. Poi usa P2 – Ensure that background work remains perceptible e P10 – Optimise for steering, not only initiating per aggiungere una run view e azioni di recovery esplicite prima di aumentare l'autonomia.

Esegui recovery drill su timeout di rete, cambio di schema del tool, ritardo di approvazione e drift del contesto.

Misura resume rate, failed-closed rate, duplicate-side-effect rate e tempo fino all'hand-off umano.

Concedi permessi più ampi solo quando i percorsi di recupero sono ispezionabili e gli operatori possono intervenire con fiducia, in linea con P7 – Establish trust through inspectability.

Principi di riferimento

Validate in Pro

Rendere espliciti i passaggi, le approvazioni e i blocchi

Leggi →Complete Foundations

Rappresentare il lavoro delegato come un sistema, non solo come una conversazione

Leggi →