Skip to content
AI Engineer Guide.

concept · concepts · intermediate · concept 14 of 37

Rollback & compensation

0 of 37 complete

Why it matters

Agents act on the world: they create records, send messages, move money, open tickets. When a later step fails or a reviewer rejects the result, the team discovers that the database rolls back but the recipient cannot unread the message. The design work is to classify actions by reversibility before execution and to pair each reversible one with a tested compensation.

Mental model

Rollback is accounting, not time travel: you post a reversing entry rather than deleting the original. The metaphor breaks because a ledger keeps both entries visibly, while a sent message or a deleted file leaves no such symmetry and the compensation can be more visible than the original.

How it works

Verify fails, compensations run in reverse, audit records bothInteractive
transitionfailurerepeat

Event · step 1 of 8

Action committed

The run sends an invoice email, charges the card and reserves inventory. All three external ids are journaled before the tool returns.

In state

  • Action

Next: Verification fails

Effects undone
0
Unrecoverable
0
Step 1/8 · Action committed

Figure. A committed action fails verification. The run releases the reservation and refunds the charge in reverse order, journaling each reversal, then reports the email it cannot recall. The irreversible effect ends at a human rather than a claimed complete rollback.

What to notice. Compensation is a new action, not an inverse function: the refund is a second transaction and the audit keeps both entries. The run releases the reservation, then refunds the charge, then reports the email it cannot recall. Amounts and record ids are illustrative.

Text version

A state machine with seven states. Action goes to Verify on journal. Verify goes to Classify on mismatch, or to Restored on passes. Classify goes to Compensate on reverse. Compensate goes to Audit on undo. Audit loops back to Compensate on next undo, goes to Restored on matched, and exits to Human repair on irreversible. The trace walks Action, Verify, Classify, Compensate the reservation, Audit, Compensate the charge, Audit, then Human repair. Counters show two effects undone and one unrecoverable effect: the sent email.

  1. Classify every tool by reversibility: reversible, compensable or irreversible.
  2. Require explicit approval or a dry run before anything in the irreversible class executes.
  3. Write a compensation for each compensable action and test it as a first-class path.
  4. Record an action journal with arguments, external ids and timestamps so compensation can find its target.
  5. On failure, compensate in reverse order and stop at the first compensation that fails.
  6. Report the resulting state to the user, including what could not be undone.

Trade-offs

ChoiceGood forCostFails when
Checkpoint restore onlyFast and simple for internal stateDoes nothing to external systemsActions leave your boundary
Compensating actionsHandles external effectsEach compensation can fail or be visibleThe effect is a notification or a deletion
Dry run then commitCatches most mistakes cheaplyTwo-phase complexity and drift between phasesThe world changes between preview and commit
No rollback, human repairHonest about irreversibilityManual cost and inconsistent outcomesVolume is high
Trade-off mapInteractive

Good for

Fast and simple for internal state

Cost

Does nothing to external systems

Fails when

Actions leave your boundary

  1. Actions leave your boundary
  2. The effect is a notification or a deletion
  3. The world changes between preview and commit
  4. Volume is high

Figure. Each choice with what it buys, what it costs, and the case where it loses.

What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.

Text version

Four trade-offs: Checkpoint restore only is good for Fast and simple for internal state, costs Does nothing to external systems, and fails when Actions leave your boundary. Compensating actions is good for Handles external effects, costs Each compensation can fail or be visible, and fails when The effect is a notification or a deletion. Dry run then commit is good for Catches most mistakes cheaply, costs Two-phase complexity and drift between phases, and fails when The world changes between preview and commit. No rollback, human repair is good for Honest about irreversibility, costs Manual cost and inconsistent outcomes, and fails when Volume is high

Failure modes

  • Compensation without a target. The undo cannot find the record because the id was never journaled. Debug: assert every committed action writes its external id before returning.
  • Partial rollback. Some steps are undone and others are not, leaving a mixed state. Debug: replay the journal and compare the resulting state with the pre-run snapshot.
  • Assumed reversibility. The team believes an email can be recalled and it cannot. Debug: list actions with no compensation and confirm each has an approval gate.

In production

Track rollback rate, compensation failures and time to restore. Rehearse a failed multi-step run in staging and confirm the journal alone is enough to reconstruct what happened.

Common misconceptions

People think: A checkpoint is a rollback.

Actually: A checkpoint restores your state; rollback must also address every external effect the run produced.

People think: Compensation can always be automated.

Actually: Some effects — a notification, a deleted file, a signed contract — have no safe inverse and need a human decision.

Interview angle

Strong answers classify actions by reversibility before discussing mechanisms, then explain the journal and the reverse-order compensation, including what happens when a compensation fails. Weak answers say the agent can roll back because state is checkpointed, without addressing effects outside the system.

Sources