Geautomatiseerde rollback voor neveneffecten van agenten

Een rollback van een agent kan code, configuratie of geselecteerde applicatiegegevens herstellen. Hij kan een andere organisatie niet laten vergeten dat ze een verzoek ontving, een afgeleverde e-mail niet uit een inbox terughalen en niet doen alsof een kaartafschrijving nooit een betaalverwerker bereikte. Teams die al deze handelingen «rollback» noemen, bouwen een geruststellend controlemechanisme dat juist faalt wanneer de gevolgen ertoe doen.

Een veilig ontwerp scheidt vier mechanismen: applicatiesnapshots, Git-reverts, databaseherstel en compenserende acties. Elk heeft een eigen grens. Voor elke actie die de applicatiegrens overschrijdt, moeten goedkeuring, bewijs, een regel voor opnieuw proberen en een herstelpad vastliggen voordat de agent haar uitvoert. Kan niemand dat pad in één zin omschrijven, dan is de actie niet klaar voor onbewaakte uitvoering.

Rollback heeft vier afzonderlijke betekenissen

Rollback is alleen nuttig wanneer het team benoemt welke toestand wordt hersteld en welke toestand buiten bereik blijft. Het woord verbergt meestal vier mechanismen met heel verschillende garanties.

Een snapshot herstelt een vastgelegde versie van een applicatie of werkruimte. Afhankelijk van het product kan die snapshot gegenereerde code, configuratie en geselecteerde beheerde toestand bevatten. Over externe diensten zegt hij niets, tenzij het snapshotcontract die uitdrukkelijk omvat.

Een Git-revert legt een nieuwe commit vast waarvan de wijzigingen een eerdere commit terugdraaien. Hij herstelt de broncodegeschiedenis zonder die geschiedenis te verwijderen. Hij neemt geen contact op met diensten die de oude code tijdens het uitvoeren heeft aangeroepen.

Databaseherstel wijzigt records die de database bewaart. Een transactie-rollback verwerpt niet-vastgelegde schrijfacties binnen één transactie. Een back-up herstellen of point-in-time recovery gebruiken is een veel grotere ingreep die een databasecluster naar een eerdere toestand verplaatst. Geen van beide stemt systemen buiten die database automatisch af.

Een compenserende actie creëert een nieuw effect dat bedoeld is om een oud effect te compenseren. Een terugbetaling compenseert een geïncasseerde betaling. Een annuleringsverzoek compenseert een bestelling. Een corrigerende e-mail kan een verkeerde e-mail verzachten, maar kan het eerste bericht niet verwijderen. Compensatie houdt de ongemakkelijke waarheid overeind dat de oorspronkelijke actie heeft plaatsgevonden.

Tijdens ontwerpbeoordelingen gebruik ik een tabel voor eigenaarschap van effecten, omdat die tot precieze antwoorden dwingt:

De laatste kolom is het belangrijkst. Een tegengestelde handeling bewijst niet dat het oorspronkelijke effect is verdwenen. Auditrecords, kopieën bij ontvangers, afwikkelingsboekingen, webhooks en fysiek werk kunnen blijven bestaan.

Een coderevert wijzigt het programma, niet het verleden

Een coderevert voorkomt of wijzigt toekomstig gedrag. Hij draait gedrag dat de oude versie al heeft veroorzaakt niet terug. Dat blijft zo, of het team nu Git, een platformsnapshot of een implementatierollback gebruikt.

De Git-documentatie beschrijft git revert als het vastleggen van commits die wijzigingen terugdraaien die eerdere commits hebben ingevoerd. Die formulering klopt precies: Git past een omgekeerde patch toe op de inhoud van de repository. Git weet niets van e-mails, betalingen, cloudresources, supporttickets of partner-API's die zijn gemaakt toen de teruggedraaide commit draaide.

Stel dat een agent een factureringsfunctie wijzigt, implementeert en twee keer aanroept voordat monitoring het probleem ontdekt. De commit terugdraaien kan voorkomen dat de foute functie opnieuw draait. Bij de verwerker blijven twee betaalpogingen staan. Als de lokale database maar één poging vastlegde, kan de revert het onderzoek zelfs moeilijker maken doordat hij het codepad verwijdert dat de tweede reactie begreep.

Een implementatierollback heeft dezelfde grens. Verkeer terugzetten naar een eerdere build herstelt uitvoerbaar gedrag. Verzoeken die de vervangen build al accepteerde, houden hun gevolgen. Wachtrijtaken kunnen de implementatie ook overleven en oude aannames uitvoeren tegen de herstelde versie.

Bewaar vóór je terugdraait het operationele bewijsmateriaal dat de oude build heeft geproduceerd:

• Implementatie-ID en broncommit
• ID's van agentrun en intentie
• ID's van wachtrijberichten en leasestatus
• ID's van externe verzoeken
• Reacties en tijdstempels van de provider

Stop daarna nieuwe uitvoering, stem onvoltooide handelingen af en herstel de code. Eerst terugdraaien en pas daarna vragen stellen vernietigt vaak de eenvoudigste route om te begrijpen welke effecten zijn ontsnapt.

Een snapshot kan breder zijn dan een Git-commit, maar dezelfde regel geldt. Het snapshotcontract moet precies aangeven welke resources hij bevat. Bevat hij code en configuratie, noem hem dan een herstelmechanisme voor code en configuratie. Maak er geen universele ongedaanmaking van met hoopvolle tekst in de interface.

Databaseherstel heeft een beperktere taak dan mensen aannemen

Databaseherstel herstelt de databasetoestand, niet de zakelijke werkelijkheid bij elke deelnemer aan een transactie. Een transactie kan atomair zijn binnen één database, terwijl de omringende handeling verdeeld blijft over meerdere systemen.

Bekijk deze volgorde:

1. De agent voegt een factuurrij toe.
2. Hij roept een betaal-API aan.
3. De verwerker accepteert de afschrijving.
4. De databasecommit mislukt.

De lokale rollback verwijdert de factuurrij. De afschrijving bestaat nog steeds. De volledige handeling opnieuw proberen zonder afstemming kan de klant opnieuw belasten. Dit is de klassieke dual-writefout: de applicatie probeerde één zakelijke actie atomair te maken over systemen die geen transactiecoördinator delen.

De volgorde omdraaien lost dit niet op. Als de applicatie eerst de factuur vastlegt en de betaaloproep daarna mislukt, bevat de database een onbetaalde factuur. Die toestand is makkelijker te onderzoeken, maar de applicatie heeft nog steeds een toestandsmachine nodig die onderscheid maakt tussen payment_pending, payment_confirmed, payment_failed en payment_unknown.

De PostgreSQL-documentatie legt point-in-time recovery uit als het herstellen van een basisback-up en het opnieuw afspelen van write-ahead-logrecords tot een gekozen hersteldoel. Dit is een procedure voor beheerders om een databasecluster te herstellen. Het is geen selectieve ongedaanmaking voor één agentrun en kan een betaalverwerker of maildienst niet vragen om naar hetzelfde tijdstip terug te keren.

De database terugzetten kan een tweede afwijking veroorzaken. Stel je voor dat je na een storing herstelt naar 10:00. Een provider accepteerde verzoeken tot 10:07, maar de herstelde database bevat hun records niet meer. Agenten die «ontbrekende» rijen zien, kunnen al het werk van die zeven minuten opnieuw maken. Herstel heeft daarom een fase voor externe afstemming nodig voordat workers hervatten.

Een outboxpatroon verkleint één gevaarlijke kloof. De applicatie legt de zakelijke wijziging en een effectintentie vast in dezelfde lokale transactie:

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;

Een worker claimt later eff_7f31, roept de provider aan met een stabiele idempotentiewaarde en legt het resultaat vast. De outbox maakt de externe oproep niet atomair. Hij geeft het systeem duurzaam bewijs dat werk was bedoeld, zodat opnieuw proberen en afstemming mogelijk worden.

Externe acties hebben compensaties nodig, en sommige hebben die niet

Een extern neveneffect heeft een providerspecifieke compensatie nodig, of een expliciete uitspraak dat er geen betekenisvolle compensatie bestaat. Elke actie als omkeerbaar behandelen is erger dan erkennen dat sommige acties goedkeuring vereisen.

E-mail is het eenvoudigste voorbeeld. Voordat de provider het bericht accepteert, kan de applicatie een taak in de wachtrij annuleren. Na acceptatie kan de provider annulering toestaan gedurende een korte interne fase, maar er bestaat geen algemene garantie dat je berichten bij ontvangers en mailsystemen kunt terugroepen. Na bezorging kan een tweede bericht de zaak rechtzetten, maar het eerste niet wissen. Gevoelige gegevens, juridische kennisgevingen en reputatieschade blijven zichtbaar.

Betalingen hebben verschillende toestanden die teams vaak samenvatten als «afgeschreven». Een autorisatie reserveert bestedingsruimte. Een incasso vraagt om geldverplaatsing op basis van die autorisatie. Het ongeldig maken van een nog niet afgewikkelde autorisatie kan die ruimte vrijgeven. Een terugbetaling creëert na incasso een latere financiële boeking die geld terugstuurt. Deze handelingen verschillen in timing, kosten, rechten en gevolgen voor de klant. Een generieke tool undo_payment verbergt informatie die de agent nodig heeft om veilig te handelen.

Andere API's werken nog minder mee. Een verzoek kan voorraad bestellen, infrastructuur inrichten, content publiceren, toegang verlenen, een pakket versturen of iemand ertoe aanzetten te beginnen met werk. Een DELETE-endpoint bewijst geen omkeerbaarheid. Het verwijderen van een resource kan auditlogs, gekopieerde gegevens, meldingen, afhankelijke resources of fysieke gevolgen achterlaten.

Deel compensatie in op basis van wat die eerlijk kan bereiken:

• Een exacte lokale tegenactie brengt gecontroleerde toestand terug naar de vorige waarde.
• Annulering door de provider stopt werk dat nog niet klaar is.
• Financiële compensatie creëert een terugbetaling of tegoed.
• Corrigerende communicatie erkent dat het eerste bericht zichtbaar blijft.
• Handmatig herstel pakt effecten aan waarvan de context niet in een veilige geautomatiseerde regel past.

Compensatie kan ook mislukken. Het endpoint voor terugbetalingen kan een time-out geven. Het annuleringsvenster kan sluiten. Het adres van de ontvanger kan de correctie weigeren. Het account dat de agent gebruikt kan onvoldoende rechten hebben. Daarom moet het systeem compensatie volgen als een eigen handeling met een eigen intentie-ID, status, pogingen, bewijsmateriaal en goedkeuringsbeleid.

Bouw geen recursieve functie «de rollback van de rollback». Modelleer de geschiedenis als een grootboek van acties. Veroorzaakt een compensatie een nieuwe fout, voer dan na beoordeling van de actuele toestand nog een expliciete actie uit. Die geschiedenis is langer, maar blijft tijdens een incident begrijpelijk.

Idempotentie voorkomt herhaling maar draait succes niet terug

Idempotentie beschermt pogingen tot herhalen tegen dubbele bedoelde effecten. Ze maakt het eerste geslaagde effect niet ongedaan. Teams halen die twee ideeën vaak door elkaar en ontdekken het verschil pas na een time-out.

RFC 9110 definieert een idempotente aanvraagmethode aan de hand van het bedoelde effect: meerdere identieke aanvragen hebben hetzelfde bedoelde effect als één zo'n aanvraag. PUT, DELETE en veilige methoden zijn volgens de protocolsemantiek idempotent. POST is over het algemeen niet idempotent, al kan een API via een eigen contract idempotent gedrag toevoegen.

Die nuance is belangrijk. Een idempotente DELETE kan elke keer nog steeds een nieuw logitem, meetpunt of antwoord opleveren. De idempotentie-implementatie van een provider kan records ook laten verlopen, ID's beperken tot één account, gewijzigde parameters weigeren of alleen geselecteerde uitkomsten cachen. Lees het contract van de provider in plaats van garanties af te leiden uit een HTTP-werkwoord.

Elke effectintentie moet vóór de eerste poging één stabiele idempotentiewaarde krijgen. Pogingen voor diezelfde intentie gebruiken die opnieuw. Een nieuwe zakelijke intentie krijgt een nieuwe waarde. Leid die nooit uitsluitend af van veranderlijke parameters zoals klant, bedrag en datum, want twee legitieme aankopen kunnen dezelfde waarden hebben.

Een time-out creëert een onbekende uitkomst, geen mislukking. Gebruik deze volgorde:

1. Markeer de poging als outcome_unknown; maak geen vervangende intentie.
2. Vraag de provider op met de idempotentiewaarde of operatiereferentie.
3. Bevestigt de provider succes, leg dat succes dan lokaal vast.
4. Bevestigt hij dat er geen handeling is, probeer dan opnieuw met dezelfde waarde.
5. Kan hij geen antwoord geven, houd de handeling dan vast voor afstemming of menselijke beoordeling.

Deze antwoordvorm geeft de agent genoeg informatie om acceptatie van transportonzekerheid te onderscheiden:

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

Een idempotentiewaarde moet door logs, wachtrijberichten, API-headers en metagegevens van de provider lopen waar die dat ondersteunt. Kunnen beheerders er niet aan beide kanten van de grens op zoeken, dan moeten ze tijdens herstel gissen.

Goedkeuring hoort bij de effectgrens

Goedkeuring moet plaatsvinden nadat de agent de exacte externe actie heeft gevormd en voordat het eerste onomkeerbare verzoek het systeem verlaat. Goedkeuring aan het begin van een brede taak geeft de agent te veel ruimte om later ontvangers, bedragen, reikwijdte of tools te veranderen.

«Behandel de account van deze klant» is geen toereikende goedkeuring om een kaart te belasten of elke gebruiker te e-mailen. Een geldige goedkeuring beschrijft de concrete handeling: ontvanger, bedrag en valuta, bericht of samenvatting van de payload, doelaccount, tool, vervaltijd en toegestaan aantal pogingen. Verandert een goedgekeurd veld, dan past de goedkeuring niet meer.

Een bruikbaar beleid sorteert effecten op gevolg, niet op de agent of het model dat ze aanvroeg. Leestoegang kan nog steeds privégegevens blootleggen, maar heeft niet hetzelfde herstelprobleem als een uitgaande actie. Een e-mail opstellen is lokaal en omkeerbaar. Hem versturen overschrijdt de grens. Een betaalvoorstel maken is lokaal. Geld innen overschrijdt de grens.

Vereis expliciete goedkeuring voor acties die:

• Geld verplaatsen of een financiële verplichting creëren
• Informatie naar een persoon of externe organisatie sturen
• Gegevens buiten gecontroleerde opslag publiceren, verwijderen of bekendmaken
• Identiteit, toegang, eigendom of beveiligingsinstellingen wijzigen
• Fysiek werk of een ander proces starten dat niet betrouwbaar kan worden teruggeroepen

Herhaalde acties met beperkte gevolgen kunnen een begrensde doorlopende goedkeuring gebruiken. De grens moet een maximumbedrag, set van ontvangers, toegestane tool, vervaltijd, snelheid en totaal aantal handelingen noemen. «Goedgekeurd voor facturering» heeft geen afdwingbare grens.

Goedkeuring heeft ook bescherming tegen hergebruik nodig. Koppel haar aan een onveranderlijke samenvatting van de handeling en markeer haar als verbruikt wanneer het beleid slechts één uitvoering toestaat. Geeft uitvoering een onbekende uitkomst terug, vraag dan niet om nieuwe goedkeuring en maak geen tweede intentie. Stem eerst de goedgekeurde intentie af.

Het goedkeuringsscherm moet de waarheid over herstel in gewone taal zeggen. «Dit bericht kan na bezorging niet worden teruggeroepen» is nuttig. «Deze handeling is omkeerbaar» is misleidend wanneer het werkelijke herstel een terugbetaling is die tijd kan kosten en op financiële overzichten blijft staan.

Toolcontracten moeten de volledige levenscyclus van een effect tonen

Een toolcontract voor een agent moet intentie, uitvoering, observatie en compensatie beschrijven als afzonderlijke handelingen. Eén functie die een effect uitvoert en success: true teruggeeft, laat te weinig bewijs achter voor opnieuw proberen, goedkeuringen of incidentrespons.

Het volgende beleidsfragment is klein genoeg om af te dwingen en specifiek genoeg om te beoordelen:

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 vertelt de planner welke herstelklasse geldt. approval blokkeert uitvoering totdat de exacte argumenten zijn geautoriseerd. Het idempotentieveld zorgt dat pogingen tot herhalen één identiteit gebruiken. Het bewijsveld vertelt beheerders wat bewaard moet blijven. Het compensatieveld verwijst naar een afzonderlijke tool in plaats van te doen alsof de oorspronkelijke oproep achteruit kan draaien.

Uitvoering moet een onveranderlijke envelop accepteren:

{
  "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"
  }
}

De uitvoerder berekent de samenvatting van de handeling, vergelijkt die met scope_hash, controleert de vervaltijd, reserveert de intentie en neemt pas dan contact op met de provider. Hij bewaart de metagegevens van het verzoek vóór de oproep en de reactie erna. Crasht hij tussen die schrijfacties, dan blijft de duurzame intentie beschikbaar voor afstemming.

De uitvoerder moet vier voorwaarden afwijzen zonder te improviseren: gewijzigde argumenten, verlopen goedkeuring, hergebruik van een intentie voor een andere handeling en een poging om een effect te compenseren waarvan succesvolle voltooiing niet is bevestigd. Agenten zijn goed in het vinden van aannemelijke vervolgstappen. Financiële en communicatieve controles moeten een zichtbare stop verkiezen boven een aannemelijke gok.

Geef observatie een eigen tool, zoals get_payment_status(intent_id). Observatie mag geen effect creëren. Door haar apart te houden kan de agent dubbelzinnige uitkomsten oplossen zonder toestemming te krijgen om de oorspronkelijke actie opnieuw te proberen.

Eén mislukte run kan elke herstelgrens overschrijden

Eén agentrun kan code, databaserecords en externe systemen op verschillende tijdstippen achterlaten. Deze fout vóór de lancering doorlopen legt gaten bloot die een generieke rollbackknop verbergt.

Neem aan dat een agent een lidmaatschapsapplicatie bouwt, een wijziging implementeert, een klantenlijst importeert, jaarlijkse kosten int en welkomstmails verstuurt. De taak klinkt als één geheel, maar overschrijdt minstens vier herstelgrenzen.

Om 14:00 implementeert de agent code die de jaarlijkse kosten uit de verkeerde kolom berekent. Om 14:02 schrijft hij 40 betaalintenties en e-mailconcepten naar de database. Om 14:03 incasseert een worker verschillende betalingen. Om 14:04 accepteert de mailprovider welkomstberichten met het onjuiste bedrag. Om 14:05 stopt monitoring de worker. Sommige betaaloproepen gaven een time-out nadat ze de verwerker bereikten, waardoor de lokale status niet laat zien of ze zijn geslaagd.

De codesnapshot van 13:59 herstellen stopt de foute berekening in toekomstige runs. Het wijzigt het bedrag niet dat al naar bestaande intenties is gekopieerd. De Git-commit terugdraaien documenteert de correctie van de broncode, maar heeft dezelfde beperking.

De database herstellen naar 13:59 zou de lokale intentierecords met providerreferenties en idempotentiewaarden verwijderen. Dat maakt de externe afwijking groter. De betere databaseactie is een logische correctie: behoud de intenties, markeer onzekere handelingen voor afstemming en corrigeer rijen pas nadat ze overeenkomen met de toestand bij de provider.

Het responsteam moet vervolgens per effectklasse handelen. Het vraagt elke onzekere betaling op met de stabiele operatie-identiteit. Bevestigde incasso's gaan naar beoordeling voor terugbetaling, mislukte pogingen worden zonder herhaling gesloten en onopgeloste pogingen blijven geblokkeerd. Afgeleverde e-mails krijgen een zorgvuldig goedgekeurde correctie. Berichten in de wachtrij die de provider nog niet bereikten, worden geannuleerd. Elke compensatie krijgt een nieuwe intentie die aan de oorspronkelijke is gekoppeld.

Dit voorbeeld laat ook zien waarom automatische compensatie gevaarlijk kan zijn. Betaalt het systeem onmiddellijk elk lokaal record payment_unknown terug, dan kan het geld teruggeven voor afschrijvingen die nooit bestonden of een endpoint voor terugbetaling met de verkeerde referentie aanroepen. Verstuurt het na databaseherstel elke ontbrekende e-mail opnieuw, dan kunnen ontvangers duplicaten krijgen. Afstemming moet aan compensatie voorafgaan wanneer de lokale toestand en die van de provider verschillen.

De run is pas klaar wanneer elke intentie een eindtoestand bereikt, zoals succeeded, confirmed_failed, compensated of manual_exception. «De applicatie is teruggedraaid» beschrijft slechts het eerste deel van het incident.

Herstel werkt alleen als het bewijsmateriaal blijft bestaan

Herstelmaatregelen falen wanneer rollback de records verwijdert die nodig zijn om vast te stellen wat er is gebeurd. Bewaar een alleen-toevoegen-effectgrootboek buiten de applicatietoestand die gewone snapshots of restores kunnen vervangen, en bewaar genoeg bewijsmateriaal van de provider om elke handeling af te stemmen.

Het grootboek moet het maken van de intentie, de samenvatting van argumenten, goedkeuring, uitvoeringslease, poging, transportresultaat, providerreferentie, waargenomen providerstatus en compensatiekoppelingen vastleggen. Beperk wijzigingen tot toestandsovergangen in plaats van agenten oude vermeldingen te laten overschrijven. Correcties moeten gebeurtenissen toevoegen in plaats van geschiedenis te bewerken.

Bewaak onopgeloste toestanden, niet alleen expliciete fouten. outcome_unknown dat tien minuten blijft staan kan gevaarlijker zijn dan een duidelijke afwijzing, omdat een beheerder het handmatig opnieuw kan proberen. Waarschuw ook wanneer een goedkeuring tijdens uitvoering verloopt, een idempotentiewaarde met een andere samenvatting van argumenten verschijnt of een compensatie mislukt.

Oefen herstel met bewust lastige foutmomenten. Stop een worker nadat de provider een verzoek accepteert maar vóór de lokale succesregistratie. Herstel applicatiegegevens vanaf een eerdere snapshot terwijl je het effectgrootboek behoudt. Laat goedkeuring verlopen tussen planning en uitvoering. Maak de observatie-API onbereikbaar. De oefening slaagt wanneer het systeem stopt, afstemt en de onopgeloste beslissing toont zonder het effect te dupliceren.

Gebruik je Koder.ai, behandel dan de snapshots en rollback als de herstel-laag voor de applicatie en ontwerp afzonderlijke controles voor databasegeschiedenis en elke externe actie die de applicatie kan starten. Broncode-export, implementatiecontroles en rollback helpen software herstellen, terwijl de toolcontracten van de applicatie nog steeds goedkeuringen en compensatie beheren.

Een rollbackknop moet naast de knop zijn grens noemen: code, configuratie, beheerde gegevens of externe effecten. Kan de interface die zin niet precies maken, dan moet ze geen rollback beloven. De eerlijke controle oogt misschien minder magisch, maar geeft het incidentteam wat het om twee uur 's nachts nodig heeft: een betrouwbaar overzicht van wat veranderde, wat ontsnapte en welke volgende actie veilig is.