Rollback automatico degli effetti collaterali degli agenti

Il rollback di un agente può ripristinare codice, configurazione o dati selezionati dell'applicazione. Non può far dimenticare a un'altra organizzazione una richiesta, ritirare un'email consegnata da una casella di posta o fingere che un addebito su carta non sia mai arrivato a un processore di pagamento. I team che chiamano tutte queste operazioni «rollback» costruiscono un controllo rassicurante che fallisce proprio quando le conseguenze contano.

Una progettazione sicura separa quattro meccanismi: snapshot dell'applicazione, revert Git, recupero del database e azioni compensative. Ognuno ha un confine diverso. Qualsiasi azione che supera il confine dell'applicazione richiede una propria approvazione, prove, regole di nuovo tentativo e percorso di recupero prima che l'agente la esegua. Se nessuno sa descrivere quel percorso in una frase, l'azione non è pronta per l'esecuzione senza supervisione.

Il rollback ha quattro significati distinti

Il rollback è utile solo quando il team indica quale stato ripristinerà e quale non può toccare. La parola spesso nasconde quattro meccanismi con garanzie molto diverse.

Uno snapshot ripristina una versione acquisita dell'applicazione o dell'area di lavoro. A seconda del prodotto, può includere codice generato, configurazione e stato gestito selezionato. Non dice nulla dei servizi esterni, a meno che il contratto dello snapshot non li includa esplicitamente.

Un Git revert registra un nuovo commit le cui modifiche invertono un commit precedente. Ripara la cronologia del sorgente senza eliminarla. Non contatta i servizi che il vecchio codice ha chiamato durante l'esecuzione.

Il recupero del database modifica i record gestiti dal database. Il rollback di una transazione scarta le scritture non confermate di una singola transazione. Il ripristino di un backup o il recupero point-in-time sono operazioni molto più ampie, che riportano un cluster di database verso uno stato precedente. Nessuna delle due operazioni riconcilia automaticamente i sistemi esterni al database.

Un'azione compensativa crea un nuovo effetto pensato per compensarne uno precedente. Un rimborso compensa un pagamento acquisito. Una richiesta di annullamento compensa un ordine. Un'email correttiva può attenuare un'email errata, ma non può rimuovere il primo messaggio. La compensazione conserva la scomoda verità che l'azione originale è avvenuta.

Durante le revisioni di progetto uso una tabella di responsabilità degli effetti perché impone risposte precise:

L'ultima colonna è la più importante. Un'operazione inversa non dimostra che l'originale sia scomparsa. Possono restare record di audit, copie dei destinatari, voci di regolamento, webhook e lavoro fisico.

Un revert del codice modifica il programma, non il passato

Un revert del codice evita o modifica il comportamento futuro, non inverte il comportamento già causato dalla vecchia versione. Vale sia con Git, sia con uno snapshot della piattaforma o un rollback della distribuzione.

La documentazione Git descrive git revert come la registrazione di commit che invertono modifiche introdotte da commit precedenti. La formulazione è precisa: Git applica una patch inversa al contenuto del repository. Git non conosce email, pagamenti, risorse cloud, ticket di assistenza o API di partner creati durante l'esecuzione del commit annullato.

Supponiamo che un agente modifichi una funzione di fatturazione, la distribuisca e la invochi due volte prima che il monitoraggio rilevi il difetto. Il revert del commit può impedire che la funzione errata venga eseguita di nuovo. Lascia però due tentativi di pagamento presso il processore. Se il database locale ha registrato un solo tentativo, il revert può persino rendere più difficile l'indagine rimuovendo il percorso del codice che comprendeva la seconda risposta.

Il rollback della distribuzione ha lo stesso confine. Riportare il traffico a una build precedente ripristina il comportamento eseguibile. Le richieste già accettate dalla build sostituita mantengono le loro conseguenze. Anche i job in coda possono sopravvivere alla distribuzione ed eseguire vecchie ipotesi sulla versione ripristinata.

Prima di eseguire un revert, conserva le prove operative prodotte dalla vecchia build:

• Identificatore della distribuzione e commit sorgente
• Identificatori dell'esecuzione e dell'intento dell'agente
• Identificatori dei messaggi in coda e stato del lease
• Identificatori delle richieste esterne
• Risposte e timestamp del provider

Poi interrompi le nuove esecuzioni, riconcilia le operazioni incomplete e ripristina il codice. Fare prima il revert e porre domande dopo spesso distrugge la via più semplice per capire quali effetti sono usciti dal sistema.

Uno snapshot può essere più ampio di un commit Git, ma vale la stessa regola. Il contratto dello snapshot deve dire esattamente quali risorse contiene. Se contiene codice e configurazione, chiamalo meccanismo di recupero di codice e configurazione. Non trasformarlo in un annullamento universale con formulazioni ottimistiche nell'interfaccia.

Il recupero del database ha un compito più ristretto di quanto si pensi

Il recupero del database ripristina lo stato del database, non la realtà aziendale di ogni partecipante a una transazione. Una transazione può essere atomica dentro un database mentre l'operazione circostante resta divisa tra più sistemi.

Considera questa sequenza:

1. L'agente inserisce una riga di fattura.
2. Chiama un'API di pagamento.
3. Il processore accetta l'addebito.
4. Il commit del database fallisce.

Il rollback locale rimuove la riga della fattura. L'addebito esiste ancora. Riprovare l'intera operazione senza riconciliazione può addebitare di nuovo il cliente. Questo è il classico fallimento da doppia scrittura: l'applicazione ha tentato di rendere atomica un'azione aziendale tra sistemi che non condividono un coordinatore di transazioni.

Invertire l'ordine non risolve il problema. Se l'applicazione conferma prima la fattura e poi la chiamata di pagamento fallisce, il database contiene una fattura non pagata. È uno stato più facile da analizzare, ma l'applicazione necessita comunque di una macchina a stati che distingua payment_pending, payment_confirmed, payment_failed e payment_unknown.

La documentazione PostgreSQL spiega il recupero point-in-time come il ripristino di un backup di base e la riproduzione dei record del write ahead log fino a un obiettivo di recupero scelto. È una procedura operativa per recuperare un cluster di database. Non è un annullamento selettivo per una singola esecuzione dell'agente e non può chiedere a un processore di pagamento o a un servizio di posta di tornare allo stesso timestamp.

Riportare il database indietro può creare una seconda incoerenza. Immagina di ripristinarlo alle 10:00 dopo un'interruzione. Un provider ha accettato richieste fino alle 10:07, ma il database ripristinato non contiene più i relativi record. Gli agenti che vedono righe «mancanti» potrebbero ricreare tutti i sette minuti di lavoro. Il recupero richiede quindi una fase di riconciliazione esterna prima della ripresa dei worker.

Un pattern outbox riduce una pericolosa lacuna. L'applicazione conferma la modifica aziendale e un intento di effetto nella stessa transazione locale:

BEGIN;

INSERT INTO invoices (invoice_id, customer_id, status)
VALUES ('inv_2048', 'cust_91', 'payment_pending');

INSERT INTO effect_intents
  (intent_id, operation, subject_id, status)
VALUES
  ('eff_7f31', 'capture_payment', 'inv_2048', 'pending');

COMMIT;

Un worker acquisisce poi eff_7f31, chiama il provider con un valore di idempotenza stabile e registra il risultato. L'outbox non rende atomica la chiamata esterna. Fornisce al sistema una prova durevole che il lavoro era previsto, rendendo possibili nuovi tentativi e riconciliazione.

Le azioni esterne richiedono compensazioni, e alcune non ne hanno

Un effetto esterno richiede una compensazione specifica del provider oppure una dichiarazione esplicita che non esiste una compensazione significativa. Trattare ogni azione come reversibile è peggio che ammettere che alcune richiedono approvazione.

L'email è l'esempio più semplice. Prima che il provider accetti il messaggio, l'applicazione può annullare un job in coda. Dopo l'accettazione, il provider potrebbe consentire l'annullamento durante una breve fase interna, ma non esiste una garanzia generale di richiamo tra destinatari e sistemi di posta. Una volta consegnata, un secondo messaggio può correggere il contenuto, non eliminare il primo. Dati sensibili, comunicazioni legali e danni alla reputazione restano esposti.

I pagamenti hanno diversi stati che i team spesso riducono a «addebitato». Un'autorizzazione riserva capacità di spesa. Un'acquisizione richiede il trasferimento di fondi a fronte di quell'autorizzazione. Un annullamento può liberare un'autorizzazione non regolata. Un rimborso crea una successiva voce finanziaria che restituisce denaro dopo l'acquisizione. Queste operazioni hanno tempi, commissioni, autorizzazioni e impatto sul cliente diversi. Uno strumento generico undo_payment nasconde informazioni necessarie all'agente per agire in sicurezza.

Altre API collaborano ancora meno. Una richiesta può ordinare inventario, predisporre infrastruttura, pubblicare contenuti, concedere accessi, spedire un pacco o indurre una persona a iniziare un lavoro. Un endpoint DELETE non dimostra la reversibilità. L'eliminazione di una risorsa può lasciare log di audit, dati copiati, notifiche, risorse dipendenti o conseguenze fisiche.

Classifica le compensazioni in base a ciò che possono ottenere onestamente:

• L'inverso locale esatto riporta lo stato controllato al valore precedente.
• L'annullamento del provider interrompe il lavoro non ancora completato.
• La compensazione finanziaria crea un rimborso o un credito.
• La comunicazione correttiva riconosce che il primo messaggio resta visibile.
• La correzione manuale gestisce effetti il cui contesto non può rientrare in una regola automatica sicura.

Anche la compensazione può fallire. L'endpoint di rimborso può andare in timeout. La finestra di annullamento può chiudersi. L'indirizzo del destinatario può rifiutare la correzione. L'account usato dall'agente può non avere l'autorizzazione. Per questo il sistema deve tracciare la compensazione come un'altra operazione, con identificatore dell'intento, stato, tentativi, prove e policy di approvazione propri.

Non creare una funzione ricorsiva di «rollback del rollback». Modella la cronologia come un registro delle azioni. Se una compensazione causa un nuovo errore, emetti un'altra azione esplicita dopo aver esaminato lo stato attuale. La cronologia sarà più lunga, ma resterà comprensibile durante un incidente.

L'idempotenza evita le ripetizioni ma non inverte un successo

L'idempotenza protegge i nuovi tentativi dalla produzione di effetti duplicati previsti, ma non annulla il primo effetto riuscito. I team confondono spesso queste idee e scoprono la differenza dopo un timeout.

RFC 9110 definisce un metodo di richiesta idempotente in base al fatto che l'effetto previsto di più richieste identiche sia uguale a quello di una sola richiesta. Indica PUT, DELETE e i metodi sicuri come idempotenti a livello di semantica del protocollo. POST non è generalmente idempotente, anche se un'API può aggiungere un comportamento idempotente tramite il proprio contratto.

La precisazione è importante. Un DELETE idempotente può comunque produrre ogni volta una nuova voce di log, una metrica o una risposta. L'implementazione dell'idempotenza di un provider può anche far scadere i record, limitare gli identificatori a un account, rifiutare parametri modificati o memorizzare nella cache solo risultati selezionati. Leggi il contratto del provider invece di dedurre garanzie da un verbo HTTP.

Ogni intento di effetto dovrebbe ricevere un valore di idempotenza stabile prima del primo tentativo. I nuovi tentativi per quello stesso intento lo riutilizzano. Un nuovo intento aziendale riceve un nuovo valore. Non ricavarlo solo da parametri modificabili come cliente, importo e data, perché due acquisti legittimi possono condividere quei valori.

Un timeout crea un esito sconosciuto, non un fallimento. Segui questa sequenza:

1. Contrassegna il tentativo come outcome_unknown, senza creare un intento sostitutivo.
2. Interroga il provider usando il valore di idempotenza o il riferimento dell'operazione.
3. Se il provider conferma il successo, registralo localmente.
4. Se conferma che non è avvenuta alcuna operazione, riprova con lo stesso valore.
5. Se non può rispondere, sospendi l'operazione per la riconciliazione o la revisione umana.

Questa struttura della risposta dà all'agente informazioni sufficienti per distinguere l'accettazione dall'incertezza di trasporto:

{
  "intent_id": "eff_7f31",
  "attempt": 2,
  "idempotency_key": "eff_7f31",
  "transport_status": "timeout",
  "provider_status": "unknown",
  "provider_reference": null,
  "next_action": "reconcile"
}

Un valore di idempotenza dovrebbe viaggiare nei log, nei messaggi in coda, nelle intestazioni API e nei metadati del provider quando supportati. Se gli operatori non possono cercarlo da entrambi i lati del confine, durante il recupero andranno a tentoni.

L'approvazione va collocata al confine dell'effetto

L'approvazione deve avvenire dopo che l'agente ha formulato l'azione esterna esatta e prima che la prima richiesta irreversibile lasci il sistema. L'approvazione all'inizio di un'attività ampia lascia all'agente troppo spazio per cambiare in seguito destinatari, importi, ambiti o strumenti.

«Gestisci l'account di questo cliente» non è un'approvazione adeguata per addebitare una carta o inviare un'email a tutti gli utenti. Un'approvazione valida descrive l'operazione concreta: destinatario, importo e valuta, digest del messaggio o del payload, account di destinazione, strumento, scadenza e numero di tentativi consentiti. Se cambia uno dei campi approvati, l'approvazione non corrisponde più.

Una policy utile ordina gli effetti in base alle conseguenze, non in base all'agente o al modello che li ha richiesti. L'accesso in lettura può comunque esporre dati privati, ma non pone lo stesso problema di recupero di un'azione in uscita. Preparare una bozza di email è locale e reversibile. Inviarla supera il confine. Creare una proposta di pagamento è locale. Acquisire fondi supera il confine.

Richiedi un'approvazione esplicita per azioni che:

• Spostano denaro o creano un obbligo finanziario
• Inviano informazioni a una persona o a un'organizzazione esterna
• Pubblicano, eliminano o divulgano dati fuori dallo spazio di archiviazione controllato
• Modificano identità, accesso, proprietà o impostazioni di sicurezza
• Avviano lavoro fisico o un altro processo che non può essere richiamato in modo affidabile

Le azioni ripetitive e a basse conseguenze possono usare un'approvazione permanente con limiti. Il limite dovrebbe indicare importo massimo, insieme dei destinatari, strumento consentito, ora di scadenza, frequenza e numero totale di operazioni. «Approvato per la fatturazione» non ha un confine applicabile.

L'approvazione necessita anche di protezione dalla riproduzione. Collegala a un digest immutabile dell'operazione e segnala che è stata consumata quando la policy consente una sola esecuzione. Se l'esecuzione restituisce un esito sconosciuto, non chiedere una nuova approvazione e non creare un secondo intento. Riconcilia prima l'intento approvato.

La schermata di approvazione dovrebbe indicare la realtà del recupero in linguaggio comune. «Questo messaggio non può essere richiamato dopo la consegna» è utile. «Questa operazione è reversibile» è fuorviante quando il recupero effettivo è un rimborso che può richiedere tempo e restare negli estratti finanziari.

I contratti degli strumenti devono esporre l'intero ciclo di vita dell'effetto

Un contratto di strumento per agenti dovrebbe descrivere intento, esecuzione, osservazione e compensazione come operazioni separate. Una singola funzione che produce un effetto e restituisce success: true lascia troppo poche prove per nuovi tentativi, approvazioni o risposta agli incidenti.

Il seguente frammento di policy è abbastanza piccolo da applicare e abbastanza specifico da revisionare:

tools:
  send_email:
    effect: irreversible
    approval: required
    idempotency_field: intent_id
    evidence_field: provider_message_id
    compensation: null

  capture_payment:
    effect: compensatable
    approval: required
    idempotency_field: intent_id
    evidence_field: provider_payment_id
    compensation: refund_payment

  update_draft:
    effect: local_reversible
    approval: none
    compensation: restore_version

effect indica al pianificatore quale classe di recupero si applica. approval blocca l'esecuzione finché gli argomenti esatti non sono autorizzati. Il campo di idempotenza fa sì che i nuovi tentativi riutilizzino un'unica identità. Il campo delle prove indica agli operatori ciò che deve sopravvivere. Il campo della compensazione punta a uno strumento separato invece di fingere che la chiamata originale possa essere eseguita al contrario.

L'esecuzione dovrebbe accettare un envelope immutabile:

{
  "intent_id": "eff_7f31",
  "operation": "capture_payment",
  "arguments": {
    "invoice_id": "inv_2048",
    "amount_minor": 12900,
    "currency": "USD"
  },
  "approval": {
    "approval_id": "apr_662",
    "scope_hash": "sha256:8b4f...",
    "expires_at": "2026-07-27T18:00:00Z"
  }
}

L'esecutore calcola il digest dell'operazione, lo confronta con scope_hash, verifica la scadenza, riserva l'intento e solo allora contatta il provider. Memorizza i metadati della richiesta prima della chiamata e la risposta dopo. Se si arresta tra queste scritture, l'intento durevole resta disponibile per la riconciliazione.

L'esecutore dovrebbe rifiutare quattro condizioni senza improvvisare: argomenti modificati, approvazione scaduta, riuso di un intento per un'operazione diversa e tentativo di compensare un effetto il cui completamento riuscito non è stato confermato. Gli agenti sanno trovare continuazioni plausibili. I controlli finanziari e di comunicazione devono preferire un arresto visibile a un'ipotesi plausibile.

Offri all'osservazione uno strumento proprio, come get_payment_status(intent_id). L'osservazione non dovrebbe creare un effetto. Tenerla separata consente all'agente di risolvere esiti ambigui senza ricevere il permesso di riprovare l'azione originale.

Una sola esecuzione fallita può superare ogni confine di recupero

Una singola esecuzione di un agente può lasciare codice, record del database e sistemi esterni in momenti diversi. Esaminare questo fallimento prima del lancio mette in luce lacune che un controllo di rollback generico nasconde.

Supponi che un agente realizzi un'applicazione per iscrizioni, distribuisca una modifica, importi un elenco di clienti, addebiti quote annuali e invii email di benvenuto. L'attività sembra unitaria, ma attraversa almeno quattro confini di recupero.

Alle 14:00, l'agente distribuisce codice che calcola la quota annuale dalla colonna sbagliata. Alle 14:02, scrive nel database 40 intenti di pagamento e bozze di email. Alle 14:03, un worker acquisisce diversi pagamenti. Alle 14:04, il provider di posta accetta messaggi di benvenuto con l'importo errato. Alle 14:05, il monitoraggio arresta il worker. Alcune chiamate di pagamento sono andate in timeout dopo aver raggiunto il processore, quindi lo stato locale non rivela se siano riuscite.

Ripristinare lo snapshot del codice delle 13:59 interrompe il calcolo errato nelle esecuzioni future. Non modifica la quota copiata negli intenti esistenti. Il revert del commit Git documenta la correzione del sorgente ma ha lo stesso limite.

Ripristinare il database alle 13:59 rimuoverebbe i record degli intenti locali che contengono riferimenti del provider e valori di idempotenza. Ciò peggiorerebbe l'incoerenza esterna. L'azione migliore sul database è una correzione logica: conserva gli intenti, contrassegna le operazioni incerte per la riconciliazione e correggi le righe solo dopo aver confrontato lo stato del provider.

Il team di risposta dovrebbe poi procedere per classe di effetto. Interroga ogni pagamento incerto usando la sua identità operativa stabile. Le acquisizioni confermate passano alla revisione del rimborso, i tentativi falliti si chiudono senza nuovo tentativo e quelli irrisolti restano bloccati. Le email consegnate ricevono una correzione approvata con cura. I messaggi in coda che non hanno raggiunto il provider vengono annullati. Ogni compensazione ottiene un nuovo intento collegato all'originale.

Questo esempio mostra anche perché la compensazione automatica può essere pericolosa. Se il sistema rimborsa immediatamente ogni record locale payment_unknown, potrebbe emettere rimborsi per addebiti mai avvenuti o chiamare un endpoint di rimborso con il riferimento errato. Se reinvia ogni email mancante dopo il recupero del database, i destinatari potrebbero ricevere duplicati. La riconciliazione deve precedere la compensazione ogni volta che stato locale e stato del provider non coincidono.

L'esecuzione è completa solo quando ogni intento raggiunge uno stato terminale come succeeded, confirmed_failed, compensated o manual_exception. «L'applicazione è stata ripristinata» descrive solo la prima parte dell'incidente.

Il recupero funziona solo se le prove sopravvivono

I controlli di recupero falliscono quando il rollback elimina i record necessari per decidere che cosa è accaduto. Conserva un registro append-only degli effetti al di fuori dello stato dell'applicazione che snapshot o ripristini di routine possono sostituire, e trattieni prove sufficienti dal provider per riconciliare ogni operazione.

Il registro dovrebbe annotare la creazione dell'intento, il digest degli argomenti, l'approvazione, il lease di esecuzione, il tentativo, il risultato del trasporto, il riferimento del provider, lo stato osservato del provider e i collegamenti alle compensazioni. Limita le modifiche alle transizioni di stato invece di consentire agli agenti di sovrascrivere voci precedenti. Le correzioni dovrebbero aggiungere eventi invece di modificare la cronologia.

Monitora gli stati irrisolti, non solo gli errori espliciti. Un outcome_unknown che resta fermo per dieci minuti può essere più pericoloso di un rifiuto netto, perché un operatore potrebbe riprovarlo manualmente. Invia avvisi anche quando un'approvazione scade durante l'esecuzione, un valore di idempotenza compare con un digest degli argomenti diverso o una compensazione fallisce.

Esegui esercitazioni di recupero con punti di fallimento volutamente scomodi. Termina un worker dopo che il provider accetta una richiesta ma prima della scrittura locale del successo. Ripristina i dati dell'applicazione da uno snapshot precedente preservando il registro degli effetti. Fai scadere un'approvazione tra pianificazione ed esecuzione. Rendi indisponibile l'API di osservazione. L'esercitazione è superata quando il sistema si ferma, riconcilia e mostra la decisione irrisolta senza duplicare l'effetto.

Quando usi Koder.ai, considera i suoi snapshot e il rollback come il livello di recupero dell'applicazione, poi progetta controlli separati per la cronologia del database e per ogni azione esterna che l'applicazione può attivare. L'esportazione del sorgente, i controlli di distribuzione e il rollback aiutano a ripristinare il software, mentre i contratti degli strumenti dell'applicazione restano responsabili di approvazioni e compensazioni.

Un pulsante di rollback dovrebbe indicare il suo confine accanto al pulsante: codice, configurazione, dati gestiti o effetti esterni. Se l'interfaccia non riesce a rendere precisa quella frase, non dovrebbe promettere un rollback. Il controllo onesto può sembrare meno magico, ma offre al team che gestisce l'incidente ciò di cui ha bisogno alle due di notte: un resoconto affidabile di ciò che è cambiato, di ciò che è uscito dal sistema e di quale azione sia sicuro compiere dopo.