Come gestire una dead-letter queue in un workflow AI

Una dead-letter queue raccoglie i casi che il workflow non è riuscito a completare entro il limite stabilito. In un'automazione tradizionale può contenere messaggi non processabili. In un workflow AI deve conservare anche il contesto necessario per capire quale versione ha agito, quali strumenti ha chiamato e quali conseguenze potrebbe aver già prodotto.

Il suo scopo non è nascondere gli errori dalla coda principale. È fermare tentativi non più sicuri, rendere il caso diagnosticabile e sostenere una decisione: correggere e rieseguire, gestire manualmente, accettare un esito parziale oppure chiudere senza altre azioni.

Distingui retry, quarantena e revisione umana

Questi meccanismi intervengono in momenti diversi.

Prima di aggiungere una quarantena, definisci i retry idempotenti del workflow AI. Se ogni nuovo tentativo può duplicare un invio o una modifica, la DLQ arriva troppo tardi: il controllo deve precedere l'azione.

Definisci il contratto della quarantena

Ogni caso deve essere leggibile senza ricostruire l'intero sistema a memoria. Un record minimo può includere:

case_id
workflow_version
input_reference
error_class
first_failure_at
last_failure_at
attempt_count
last_completed_step
effects_receipts
idempotency_key
data_classification
owner
review_due_at
disposition

Non copiare nella coda più dati del necessario. Conserva riferimenti protetti quando il contenuto originale vive altrove. Se la diagnosi richiede prompt, documenti recuperati o output intermedi, applica accessi e conservazione coerenti con la loro sensibilità.

attempt_count non è una verità universale. Google Cloud documenta che, nel proprio meccanismo, il conteggio dei tentativi può essere approssimativo. Il contratto operativo deve quindi dichiarare quale segnale è autorevole nella tua infrastruttura e non dedurre decisioni critiche da un numero che il provider definisce best effort.

Classifica prima di ritentare

Una tassonomia corta è più utile di decine di messaggi tecnici. Parti da classi che cambiano la disposizione:

• transitorio: timeout o indisponibilità entro una finestra nota

• input non valido: schema, formato o campo obbligatorio assente

• dipendenza incompatibile: API, modello, prompt o fonte non più compatibili

• policy: azione vietata, dato non ammesso o autorizzazione mancante

• qualità: output formalmente valido ma sotto la soglia dichiarata

• effetto incerto: il sistema non sa se l'azione è iniziata o completata

• difetto sconosciuto: evidenza insufficiente per una classificazione sicura

Non trasformare unknown in transient per svuotare la coda. Un errore sconosciuto richiede isolamento e diagnosi. Un effetto incerto richiede prima una verifica sul sistema destinatario, non un altro invio.

Imposta un retry budget esplicito

Il budget può combinare numero di tentativi, durata, classe d'errore e costo operativo. AWS usa maxReceiveCount nella redrive policy di SQS; è un meccanismo di piattaforma, non una soglia adatta a ogni processo.

Scrivi per ogni classe:

La coda principale non deve rallentare all'infinito per un singolo caso. Se il processo richiede ordine rigoroso, valuta però l'effetto della rimozione: AWS avverte che una DLQ può rompere la sequenza esatta di alcuni flussi FIFO. Potrebbe essere necessario bloccare l'intero gruppo, non soltanto spostare un messaggio.

Diagnostica senza modificare il caso

La prima lettura deve essere non distruttiva. Congela payload, versioni e ricevute; crea una copia di lavoro o usa riferimenti immutabili. Ricostruisci la sequenza:

1. quale input e quale versione sono entrati

2. quali controlli sono passati

3. quale ultimo passo è certamente completato

4. quali effetti sono confermati, negati o incerti

5. se la causa è locale, di dipendenza o di policy

6. quale cambiamento renderebbe sicuro un nuovo tentativo

Collega i casi gravi o ricorrenti al registro degli incidenti AI, senza confondere ogni dead letter con un incidente. La coda sostiene l'operatività; il registro governa impatto, risposta e apprendimento.

Assegna una disposizione esplicita

Ogni elemento deve finire in uno stato terminale leggibile:

• redrive_approved: causa corretta e criteri di riesecuzione verificati

• manual_completion: un owner completa o ricrea il risultato fuori dal flusso automatico

• accepted_partial: il risultato parziale è sufficiente e documentato

• discard_business_valid: il caso non deve più essere eseguito, con motivo e autorità

• incident_opened: serve un processo di risposta distinto

• blocked_evidence: mancano prove per decidere; il caso resta isolato con una scadenza

Evitare resolved come unico esito. Non dice se il lavoro è stato completato, annullato o corretto altrove.

Rilascia il redrive come un cambiamento

Il redrive non è il pulsante riprova tutto. È una release limitata di casi selezionati. Prima di avviarlo registra:

redrive_id
case_selection_query
approved_case_count
source_version
target_version
fix_reference
allowed_effects
rate_limit
stop_conditions
approver
reconciliation_owner

Prova prima un caso rappresentativo senza conseguenze irreversibili. Mantieni una velocità compatibile con monitoraggio e revisione. Se cambia prompt, modello, retrieval, tool o policy, assegna una nuova versione: altrimenti non potrai distinguere una correzione efficace da un tentativo fortunato.

Azure Service Bus consente di ricevere i messaggi dalla DLQ, ispezionarli e reinviarli dopo una correzione. Il principio utile è il passaggio esplicito tra diagnosi e nuovo invio. L'automazione deve impedire che un job periodico svuoti la coda senza una disposizione approvata.

Riconcilia le conseguenze, non solo i messaggi

Un redrive completato non dimostra che il processo sia coerente. Confronta ogni case_id con ricevute e stato del sistema destinatario:

• nessuna conseguenza precedente: esecuzione unica confermata

• conseguenza precedente completata: nuovo tentativo bloccato come duplicato

• conseguenza precedente parziale: completamento o compensazione controllata

• stato ancora incerto: caso isolato e owner informato

• risultato ricreato manualmente: collegamento tra record automatico e manuale

Monitora volume in ingresso, età del caso più vecchio, distribuzione per classe, tempo alla disposizione, quota di redrive riusciti e casi ancora incerti. Il monitoraggio del workflow AI in produzione deve mostrare anche la capacità di smaltimento, non soltanto la dimensione della coda.

Esempio fittizio

Un workflow prepara schede prodotto e le salva in un sistema interno. Dopo un aggiornamento dello schema, dodici record falliscono. I primi retry restituiscono lo stesso errore: il budget termina e i casi entrano in quarantena.

La diagnosi mostra che nessuna scheda è stata salvata, ma tre casi contengono una categoria non più valida. Il team corregge il mapping, assegna una nuova versione e seleziona nove casi per il redrive. Gli altri tre passano a manual_completion perché richiedono una decisione del catalog owner. Dopo l'esecuzione, le nove ricevute vengono confrontate con i record creati. La coda non è semplicemente vuota: tutti i dodici casi hanno una disposizione e una prova di chiusura.

Think, Build, Enable applicato alla dead-letter queue

Think: definisci classi d'errore, retry budget, dati minimi, disposizioni e autorità.

Build: implementa quarantena, ricevute, idempotenza, filtri di selezione, stop e riconciliazione.

Enable: assegna owner e scadenze, prepara il runbook, prova un redrive circoscritto e rivedi i pattern ricorrenti.

Porta workflow, classi d'errore e ricevute a MAIKER HUB per progettare automazioni e agenti AI con n8n. Il risultato utile non è una coda vuota: è sapere che fine ha fatto ogni caso senza duplicare le conseguenze.