Context

Multi-step operations across systems that can't use traditional transactions.

Problem

Cross-system operations can't be rolled back atomically; completed steps need explicit undo.

Solution

Implement compensation logic:

• Track completed steps: Know what succeeded
• Define compensating actions: Undo for each step
• Execute in reverse: Compensate in reverse order
• Log everything: Audit trail for debugging

Examples

Python

@tool
def provision_customer(data: CustomerData) -> ProvisionResult:
    """Provision a new customer across systems.

If any step fails, previous steps are compensated.
    """
    completed = []
    try:
        account = create_account(data)
        completed.append(("account", account.id))

billing = setup_billing(account.id)
        completed.append(("billing", billing.id))

access = grant_access(account.id)
        completed.append(("access", access.id))

return ProvisionResult(success=True, account=account)
    except Exception as e:
        compensate(completed)  # Undo in reverse order
        raise

Considerations

• Some actions may not be fully reversible
• Log compensation actions for audit
• Consider async compensation for slow undos

Related Patterns

• Transactional Boundary
• Tool Chain
• Partial Success

More in Tool Execution

• [**Synchronous Execution**
  Immediate request-response execution.](/content/patterns/synchronous-execution/index.html)
• [**Async Job**
  Handle long-running operations with job IDs and polling.](/content/patterns/async-job/index.html)
• [**Idempotent Operation**
  Make operations safe to retry with identical results.](/content/patterns/idempotent-operation/index.html)

Compensation Handler

Undo completed steps when a multi-step operation fails.

Category

Tool Execution

Context

Multi-step operations across systems that can't use traditional transactions.

Problem

Cross-system operations can't be rolled back atomically; completed steps need explicit undo.

Solution

Implement compensation logic:

• Track completed steps: Know what succeeded
• Define compensating actions: Undo for each step
• Execute in reverse: Compensate in reverse order
• Log everything: Audit trail for debugging

Example (Python)

@tool
def provision_customer(data: CustomerData) -> ProvisionResult:
    """Provision a new customer across systems.

If any step fails, previous steps are compensated.
    """
    completed = []
    try:
        account = create_account(data)
        completed.append(("account", account.id))

billing = setup_billing(account.id)
        completed.append(("billing", billing.id))

access = grant_access(account.id)
        completed.append(("access", access.id))

return ProvisionResult(success=True, account=account)
    except Exception as e:
        compensate(completed)  # Undo in reverse order
        raise

Considerations

• Some actions may not be fully reversible
• Log compensation actions for audit
• Consider async compensation for slow undos

Related Patterns

• transactional-boundary
• tool-chain
• partial-success

Source: https://arcade.dev/patterns/compensation-handler