Automatiserad återställning av agenters bieffekter

En agentåterställning kan återställa kod, konfiguration eller utvalda applikationsdata. Den kan inte få en annan organisation att glömma en begäran, hämta tillbaka ett levererat e-postmeddelande från en inkorg eller låtsas att en kortdebitering aldrig nådde en betalleverantör. Team som kallar alla dessa åtgärder för "återställning" bygger en betryggande kontroll som fallerar just när konsekvenserna spelar roll.

En säker utformning skiljer mellan fyra mekanismer: applikationsögonblicksbilder, Git-återställningar, databasåterställning och kompenserande åtgärder. Var och en ansvarar för sin egen gräns. Varje åtgärd som passerar applikationsgränsen behöver eget godkännande, underlag, regel för nya försök och återställningsväg innan agenten kör den. Om ingen kan formulera den vägen i en mening är åtgärden inte redo att köras utan tillsyn.

Återställning har fyra skilda betydelser

Återställning är användbart först när teamet namnger vilket tillstånd den ska återställa och vilket den inte kan påverka. Ordet döljer ofta fyra mekanismer med mycket olika garantier.

En ögonblicksbild återställer en sparad version av en applikation eller arbetsyta. Beroende på produkt kan den omfatta genererad kod, konfiguration och utvalt hanterat tillstånd. Den säger inget om externa tjänster om inte avtalet för ögonblicksbilden uttryckligen omfattar dem.

En Git-återställning registrerar en ny commit vars ändringar vänder en tidigare commit. Den reparerar källhistoriken utan att radera den. Den kontaktar inte de tjänster som den gamla koden anropade medan den kördes.

Databasåterställning ändrar poster som databasen har. En transaktionsåterställning kasserar obekräftade skrivningar i en transaktion. Att återställa en säkerhetskopia eller använda återställning till en specifik tidpunkt är en mycket större åtgärd som för ett databaskluster mot ett tidigare tillstånd. Ingen av åtgärderna stämmer automatiskt av system utanför databasen.

En kompenserande åtgärd skapar en ny effekt som ska väga upp en gammal. En återbetalning kompenserar för en genomförd betalning. En avbokningsbegäran kompenserar för en beställning. Ett korrigerande e-postmeddelande kan mildra ett felaktigt utskick, men det kan inte ta bort det första meddelandet. Kompensation bevarar den obekväma sanningen att den ursprungliga åtgärden hände.

Jag använder en tabell över effektansvar vid designgranskningar eftersom den tvingar fram precisa svar:

Den sista kolumnen är viktigast. En omvänd åtgärd är inte bevis på att originalet försvann. Revisionsposter, mottagarkopior, bokföringsposter, webhooks och fysiskt arbete kan finnas kvar.

En kodåterställning ändrar programmet, inte det förflutna

En kodåterställning förhindrar eller ändrar framtida beteende, den vänder inte beteende som den gamla versionen redan har orsakat. Det gäller oavsett om teamet använder Git, en plattformsögonblicksbild eller en driftsättningsåterställning.

Git-dokumentationen beskriver git revert som att den registrerar commits som vänder ändringar från tidigare commits. Formuleringen är exakt: Git tillämpar en omvänd patch på innehållet i lagringsplatsen. Git känner inte till e-postmeddelanden, betalningar, molnresurser, supportärenden eller partner-API:er som skapades när den återställda committen kördes.

Anta att en agent ändrar en faktureringsfunktion, driftsätter den och anropar den två gånger innan övervakningen upptäcker felet. Att återställa committen kan hindra den felaktiga funktionen från att köras igen. Två betalningsförsök finns ändå kvar hos betalleverantören. Om den lokala databasen bara registrerade ett försök kan återställningen till och med försvåra utredningen genom att ta bort kodvägen som förstod det andra svaret.

En driftsättningsåterställning har samma gräns. När trafik flyttas tillbaka till en tidigare version återställs körbart beteende. Begäranden som den ersatta versionen redan har accepterat behåller sina konsekvenser. Köade jobb kan också överleva driftsättningen och köra gamla antaganden mot den återställda versionen.

Spara det operativa underlag som den gamla versionen skapade innan du återställer:

• Driftsättningsidentifierare och källcommit
• Identifierare för agentkörning och avsikt
• Identifierare för kömeddelanden och status för leasing
• Identifierare för externa begäranden
• Leverantörssvar och tidsstämplar

Stoppa sedan ny körning, stäm av ofullständiga åtgärder och återställ koden. Att återställa först och ställa frågor senare förstör ofta den enklaste vägen till att förstå vilka effekter som läckte ut.

En ögonblicksbild kan vara bredare än en Git-commit, men samma regel gäller. Avtalet för ögonblicksbilden måste tydligt ange exakt vilka resurser den innehåller. Om den innehåller kod och konfiguration, kalla den en mekanism för återställning av kod och konfiguration. Låt inte hoppfull text i gränssnittet förvandla den till ett universellt ångra.

Databasåterställning har ett snävare uppdrag än många tror

Databasåterställning återställer databastillstånd, inte verksamhetsverkligheten hos varje deltagare i en transaktion. En transaktion kan vara atomär i en databas medan den omgivande åtgärden fortfarande är uppdelad mellan flera system.

Tänk på denna följd:

1. Agenten infogar en fakturarad.
2. Den anropar ett betalnings-API.
3. Betalleverantören godkänner debiteringen.
4. Databasens commit misslyckas.

Den lokala återställningen tar bort fakturaraden. Debiteringen finns fortfarande. Om hela åtgärden försöks igen utan avstämning kan kunden debiteras igen. Detta är det klassiska felet med dubbla skrivningar: applikationen försökte göra en verksamhetsåtgärd atomär över system som inte delar en transaktionssamordnare.

Att vända på ordningen löser inte problemet. Om applikationen först bekräftar fakturan och betalningsanropet sedan misslyckas innehåller databasen en obetald faktura. Tillståndet är enklare att granska, men applikationen behöver ändå en tillståndsmaskin som skiljer mellan payment_pending, payment_confirmed, payment_failed och payment_unknown.

PostgreSQL-dokumentationen förklarar återställning till en specifik tidpunkt som att återställa en bassäkerhetskopia och spela upp loggposter för write ahead log till ett valt återställningsmål. Det är en operatörsprocedur för att återställa ett databaskluster. Det är inte ett selektivt ångra för en agentkörning och kan inte be en betalleverantör eller e-posttjänst att återgå till samma tidpunkt.

Att flytta databasen bakåt kan skapa en andra avvikelse. Föreställ dig en återställning till 10:00 efter ett avbrott. En leverantör accepterade begäranden fram till 10:07, men den återställda databasen innehåller inte längre deras poster. Agenter som ser "saknade" rader kan återskapa alla sju minuters arbete. Återställning kräver därför en extern avstämningsfas innan arbetare återupptar körningen.

Ett outbox-mönster minskar ett farligt glapp. Applikationen bekräftar sin verksamhetsändring och en effektavsikt i samma lokala transaktion:

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;

En arbetare gör senare anspråk på eff_7f31, anropar leverantören med ett stabilt idempotensvärde och registrerar resultatet. Outbox gör inte det externa anropet atomärt. Det ger systemet varaktiga bevis på att arbete var avsett, vilket gör nya försök och avstämning möjliga.

Externa åtgärder behöver kompensation, och vissa saknar den

En extern bieffekt behöver en leverantörsspecifik kompensation eller ett uttryckligt konstaterande att meningsfull kompensation saknas. Att behandla varje åtgärd som återställbar är värre än att erkänna att vissa åtgärder kräver godkännande.

E-post är det enklaste exemplet. Innan leverantören har accepterat meddelandet kan applikationen avbryta ett köat jobb. Efter godkännandet kan leverantören tillåta avbokning under ett kort internt skede, men det finns ingen allmän garanti för återkallande hos mottagare och e-postsystem. När meddelandet är levererat kan ett nytt meddelande rätta uppgifterna, inte radera det första. Känsliga uppgifter, juridiska meddelanden och skada på anseendet är fortfarande exponerade.

Betalningar har flera tillstånd som team ofta slår ihop till "debiterad". En auktorisering reserverar betalningsutrymme. En debitering begär att pengar överförs mot den auktoriseringen. En makulering kan frisläppa en auktorisering som inte har reglerats. En återbetalning skapar en senare finansiell post som återför pengar efter debiteringen. Åtgärderna har olika tidsramar, avgifter, behörigheter och kundpåverkan. Ett generellt verktyg som undo_payment döljer information som agenten behöver för att agera säkert.

Andra API:er samarbetar ännu mindre. En begäran kan beställa lager, etablera infrastruktur, publicera innehåll, ge åtkomst, skicka ett paket eller få en person att börja arbeta. En DELETE-slutpunkt bevisar inte återställbarhet. Att radera en resurs kan lämna kvar revisionsloggar, kopierade data, aviseringar, beroende resurser eller fysiska konsekvenser.

Klassificera kompensation utifrån vad den ärligt kan uppnå:

• En exakt lokal motsats återför kontrollerat tillstånd till dess tidigare värde.
• Leverantörsavbokning stoppar arbete som inte har slutförts.
• Finansiell kompensation skapar en återbetalning eller kredit.
• Korrigerande kommunikation bekräftar att det första meddelandet fortfarande är synligt.
• Manuell åtgärd hanterar effekter vars sammanhang inte ryms i en säker automatiserad regel.

Kompensation kan också misslyckas. Återbetalningsslutpunkten kan få tidsgräns. Avbokningsfönstret kan stängas. Mottagaradressen kan avvisa rättelsen. Kontot som agenten använder kan sakna behörighet. Därför måste systemet spåra kompensationen som ännu en åtgärd med egen avsiktsidentifierare, status, försök, underlag och godkännandepolicy.

Bygg inte en rekursiv funktion för att "återställa återställningen". Modellera historiken som en åtgärdsbok. Om en kompensation orsakar ett nytt fel, utfärda en ny uttrycklig åtgärd efter att det aktuella tillståndet har granskats. Historiken blir längre, men den förblir begriplig under en incident.

Idempotens stoppar upprepningar men vänder inte framgång

Idempotens skyddar nya försök från att skapa dubbla avsedda effekter. Den ångrar inte den första lyckade effekten. Team blandar ofta ihop dessa idéer och upptäcker sedan skillnaden efter en tidsgräns.

RFC 9110 definierar en idempotent begärandemetod genom att den avsedda effekten av flera identiska begäranden är densamma som av en sådan begäran. Den anger PUT, DELETE och säkra metoder som idempotenta på nivån för protokollsemantik. POST är inte generellt idempotent, även om ett API kan lägga till idempotensbeteende genom sitt eget kontrakt.

Förbehållet spelar roll. En idempotent DELETE kan ändå skapa en ny loggpost, mätning eller ett nytt svar varje gång. En leverantörs implementation av idempotens kan också låta poster löpa ut, begränsa identifierare till ett konto, avvisa ändrade parametrar eller bara cachelagra utvalda resultat. Läs leverantörens kontrakt i stället för att härleda garantier från ett HTTP-verb.

Varje effektavsikt bör få ett stabilt idempotensvärde före sitt första försök. Nya försök för samma avsikt återanvänder det. En ny verksamhetsavsikt får ett nytt värde. Härled det aldrig enbart från föränderliga parametrar som kund, belopp och datum, eftersom två legitima köp kan ha samma värden.

En tidsgräns skapar ett okänt utfall, inte ett misslyckande. Följ denna ordning:

1. Markera försöket outcome_unknown, skapa ingen ersättningsavsikt.
2. Fråga leverantören med idempotensvärdet eller operationsreferensen.
3. Om leverantören bekräftar framgång, registrera framgången lokalt.
4. Om den bekräftar att ingen åtgärd finns, försök igen med samma värde.
5. Om den inte kan svara, håll åtgärden för avstämning eller mänsklig granskning.

Den här svarsformen ger agenten tillräcklig information för att skilja godkännande från osäkerhet i transporten:

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

Ett idempotensvärde bör följa med i loggar, kömeddelanden, API-rubriker och leverantörsmetadata där det stöds. Om operatörer inte kan söka på det på båda sidor av gränsen kommer de att gissa under återställning.

Godkännande hör hemma vid effektgränsen

Godkännande måste ske efter att agenten har utformat den exakta externa åtgärden och innan den första oåterkalleliga begäran lämnar systemet. Ett godkännande i början av en bred uppgift ger agenten för mycket utrymme att senare ändra mottagare, belopp, omfattning eller verktyg.

"Hantera den här kundens konto" är inte ett tillräckligt godkännande för att debitera ett kort eller skicka e-post till varje användare. Ett giltigt godkännande beskriver den konkreta åtgärden: mottagare, belopp och valuta, sammandrag av meddelande eller nyttolast, målkonto, verktyg, utgångstid och tillåtet antal försök. Om något godkänt fält ändras passar godkännandet inte längre.

En användbar policy sorterar effekter efter konsekvens i stället för efter vilken agent eller modell som begärde dem. Läsåtkomst kan fortfarande exponera privata data, men skapar inte samma återställningsproblem som en utgående åtgärd. Att skriva ett e-postutkast är lokalt och återställbart. Att skicka det passerar gränsen. Att skapa ett betalningsförslag är lokalt. Att debitera pengar passerar gränsen.

Kräv uttryckligt godkännande för åtgärder som:

• Flyttar pengar eller skapar en finansiell förpliktelse
• Skickar information till en person eller extern organisation
• Publicerar, raderar eller lämnar ut data utanför kontrollerad lagring
• Ändrar identitet, åtkomst, ägarskap eller säkerhetsinställningar
• Startar fysiskt arbete eller en annan process som inte kan återkallas tillförlitligt

Åtgärder med låg konsekvens som upprepas kan omfattas av begränsat stående godkännande. Gränsen bör ange högsta belopp, mottagargrupp, tillåtet verktyg, utgångstid, takt och totalt antal åtgärder. "Godkänd för fakturering" saknar en gräns som går att upprätthålla.

Godkännandet behöver också skydd mot återspelning. Bind det till en oföränderlig sammanfattning av åtgärden och markera det som förbrukat när policyn tillåter en enda körning. Om körningen ger ett okänt utfall, be inte om ett nytt godkännande och skapa inte en andra avsikt. Stäm först av den godkända avsikten.

Godkännandeskärmen bör beskriva återställningsverkligheten på vanligt språk. "Det här meddelandet kan inte återkallas efter leverans" är användbart. "Den här åtgärden är återställbar" är missvisande när den faktiska återställningen är en återbetalning som kan ta tid och finnas kvar på kontoutdrag.

Verktygskontrakt bör visa hela effektlivscykeln

Ett verktygskontrakt för en agent bör beskriva avsikt, körning, observation och kompensation som separata åtgärder. En enda funktion som utför en effekt och returnerar success: true lämnar för lite underlag för nya försök, godkännanden och incidenthantering.

Följande policyfragment är tillräckligt litet för att kunna tillämpas och tillräckligt specifikt för att granskas:

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 talar om för planeraren vilken återställningsklass som gäller. approval blockerar körning tills de exakta argumenten har godkänts. Idempotensfältet gör att nya försök återanvänder en identitet. Underlagsfältet talar om för operatörer vad som måste finnas kvar. Kompensationsfältet pekar på ett separat verktyg i stället för att låtsas att det ursprungliga anropet kan köras baklänges.

Körningen bör acceptera ett oföränderligt kuvert:

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

Exekveraren beräknar åtgärdssammanfattningen, jämför den med scope_hash, kontrollerar utgångstiden, reserverar avsikten och kontaktar först därefter leverantören. Den lagrar begärans metadata före anropet och svaret efteråt. Om den kraschar mellan dessa skrivningar är den varaktiga avsikten fortfarande tillgänglig för avstämning.

Exekveraren bör avvisa fyra villkor utan att improvisera: ändrade argument, utgånget godkännande, återanvändning av en avsikt för en annan åtgärd och ett försök att kompensera för en effekt vars lyckade slutförande inte har bekräftats. Agenter är bra på att hitta trovärdiga fortsättningar. Ekonomiska kontroller och kommunikationskontroller måste föredra ett synligt stopp framför en trovärdig gissning.

Ge observation ett eget verktyg, till exempel get_payment_status(intent_id). Observation bör inte skapa en effekt. Genom att hålla den separat kan agenten lösa tvetydiga utfall utan att få behörighet att försöka igen med den ursprungliga åtgärden.

En misslyckad körning kan passera varje återställningsgräns

En enda agentkörning kan lämna kod, databasposter och externa system vid olika tidpunkter. Att gå igenom det felet före lansering visar luckor som en generell återställningskontroll döljer.

Anta att en agent bygger en medlemsapplikation, driftsätter en ändring, importerar en kundlista, debiterar årsavgifter och skickar välkomstmeddelanden. Uppgiften låter sammanhållen, men den passerar minst fyra återställningsgränser.

Klockan 14:00 driftsätter agenten kod som beräknar årsavgiften från fel kolumn. Klockan 14:02 skriver den 40 betalningsavsikter och e-postutkast till databasen. Klockan 14:03 genomför en arbetare flera betalningar. Klockan 14:04 accepterar e-postleverantören välkomstmeddelanden som innehåller fel avgift. Klockan 14:05 stoppar övervakningen arbetaren. Vissa betalningsanrop fick tidsgräns efter att ha nått betalleverantören, så lokal status visar inte om de lyckades.

Att återställa kodögonblicksbilden från 13:59 stoppar den felaktiga beräkningen i framtida körningar. Det ändrar inte avgiften som har kopierats till befintliga avsikter. Att återställa Git-committen dokumenterar källrättelsen men har samma begränsning.

Att återställa databasen till 13:59 skulle ta bort de lokala avsiktsposter som innehåller leverantörsreferenser och idempotensvärden. Det förvärrar den externa avvikelsen. Den bättre databasåtgärden är en logisk rättelse: bevara avsikterna, markera osäkra åtgärder för avstämning och rätta rader först efter matchning mot leverantörens tillstånd.

Insatsteamet bör sedan fortsätta utifrån effektklass. Det frågar om varje osäker betalning med dess stabila operationsidentitet. Bekräftade debiteringar går vidare till granskning för återbetalning, misslyckade försök avslutas utan nya försök och olösta försök förblir blockerade. Levererade e-postmeddelanden får en noggrant godkänd rättelse. Köade meddelanden som inte har nått leverantören avbryts. Varje kompensation får en ny avsikt som länkas till originalet.

Exemplet visar också varför automatisk kompensation kan vara farlig. Om systemet omedelbart återbetalar varje lokal post med payment_unknown kan det utfärda återbetalningar för debiteringar som aldrig fanns eller anropa en återbetalningsslutpunkt med fel referens. Om det skickar om varje saknat e-postmeddelande efter databasåterställning kan mottagare få dubbletter. Avstämning måste föregå kompensation när lokalt och leverantörens tillstånd skiljer sig åt.

Körningen är klar först när varje avsikt når ett slutligt tillstånd som succeeded, confirmed_failed, compensated eller manual_exception. "Applikationen återställdes" beskriver bara den första delen av incidenten.

Återställning fungerar bara när underlaget överlever

Återställningskontroller misslyckas när återställningen raderar de poster som behövs för att avgöra vad som hände. Spara en skrivskyddad effektbok utanför applikationstillståndet som vanliga ögonblicksbilder eller återställningar kan ersätta, och behåll tillräckligt med leverantörsunderlag för att stämma av varje åtgärd.

Boken bör registrera skapande av avsikt, argumentsammanfattning, godkännande, körningsleasing, försök, transportresultat, leverantörsreferens, observerat leverantörstillstånd och kompensationslänkar. Begränsa ändringar till tillståndsövergångar i stället för att låta agenter skriva över gamla poster. Rättelser bör lägga till händelser i stället för att redigera historiken.

Övervaka olösta tillstånd, inte bara uttryckliga fel. outcome_unknown som ligger kvar i tio minuter kan vara farligare än ett tydligt avslag eftersom en operatör kan försöka igen manuellt. Larma också när ett godkännande löper ut under körning, ett idempotensvärde visas med en annan argumentsammanfattning eller en kompensation misslyckas.

Genomför återställningsövningar med medvetet besvärliga felpunkter. Avsluta en arbetare efter att leverantören har accepterat en begäran men före den lokala skrivningen om framgång. Återställ applikationsdata från en tidigare ögonblicksbild samtidigt som effektboken bevaras. Låt godkännandet löpa ut mellan planering och körning. Gör observations-API:t otillgängligt. Övningen är godkänd när systemet stoppar, stämmer av och visar det olösta beslutet utan att skapa en dubbletteffekt.

När du använder Koder.ai ska du behandla dess ögonblicksbilder och återställning som applikationsåterställningslagret och sedan utforma separata kontroller för databashistorik och varje extern åtgärd som applikationen kan utlösa. Källexport, driftsättningskontroller och återställning hjälper till att återställa programvaran, medan applikationens verktygskontrakt fortfarande ansvarar för godkännanden och kompensation.

En återställningsknapp bör ange sin gräns bredvid knappen: kod, konfiguration, hanterade data eller externa effekter. Om gränssnittet inte kan göra den meningen precis bör det inte lova återställning. Den ärliga kontrollen kan se mindre magisk ut, men den ger insatsteamet det enda de behöver klockan två på natten: en tillförlitlig redogörelse för vad som ändrades, vad som läckte ut och vilken åtgärd som är säker härnäst.