Skip to content

Transactions & Rollback

CertusOrdo's Key Differentiator

Transaction rollback is what separates CertusOrdo from competitors. While others solve "Can this agent do this?", we solve "What happens when an authenticated agent does something wrong?"

Why Transaction Safety Matters

80% of IT professionals report their AI agents have taken unintended actions. Gartner predicts 25% of enterprise breaches will come from AI agents by 2028.

For regulated industries, the ability to reverse agent actions isn't optional—it's mandatory.

The Transaction Lifecycle

┌─────────────────────────────────────────────────────────────┐
│                   TRANSACTION LIFECYCLE                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌────────┐ │
│   │  BEGIN  │───>│ EXECUTE │───>│ COMMIT  │ OR │ROLLBACK│ │
│   │         │    │         │    │         │    │        │ │
│   │pre_state│    │ Agent   │    │post_state│    │Restore │ │
│   │captured │    │ acts    │    │captured │    │pre_state│ │
│   └─────────┘    └─────────┘    └─────────┘    └────────┘ │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Basic Usage

Step 1: Begin Transaction

Capture the state before your agent acts:

from certusrodo import CertusOrdoClient

client = CertusOrdoClient(api_key="aa_your_key")
tokens = client.auth.get_token(agent_id="...", secret="...")

# Capture pre-state
txn = client.transactions.begin(
    pre_state={
        "account_id": "ACC001",
        "balance": 1000.00,
        "last_transaction": "2025-01-15T10:00:00Z"
    },
    action_type="transfer_funds"
)

print(f"Transaction started: {txn.id}")
print(f"Status: {txn.status}")  # "pending"

Step 2: Execute Action

Your agent performs the actual work:

# Your agent does its work here
# This is YOUR code - CertusOrdo doesn't execute it
result = transfer_money(from_account="ACC001", to_account="ACC002", amount=250.00)

Step 3a: Commit on Success

If everything worked, record the new state:

completed = client.transactions.commit(
    txn.id,
    post_state={
        "account_id": "ACC001",
        "balance": 750.00,  # Balance reduced
        "last_transaction": "2025-01-16T14:30:00Z"
    }
)

print(f"Transaction committed: {completed.status}")  # "completed"

Step 3b: Rollback on Failure

If something went wrong, get the original state back:

rollback = client.transactions.rollback(
    txn.id,
    reason="Transfer failed - destination account frozen"
)

# Use pre_state_snapshot to restore your system
original_state = rollback.pre_state_snapshot
print(f"Original balance: {original_state['balance']}")  # 1000.00

# YOUR CODE restores the state
restore_account(original_state)

Complete Example with Error Handling

from certusrodo import CertusOrdoClient, TransactionError

client = CertusOrdoClient(api_key="aa_your_key")
tokens = client.auth.get_token(agent_id=agent.id, secret=agent.secret)

def process_payment(order_id: str, amount: float):
    # Get current state
    current_balance = get_account_balance()

    # Begin transaction with pre-state
    txn = client.transactions.begin(
        pre_state={
            "order_id": order_id,
            "balance": current_balance,
            "status": "pending"
        },
        action_type="payment",
        rollback_confidence="guaranteed"
    )

    try:
        # Attempt the payment
        result = charge_credit_card(order_id, amount)

        if result.success:
            # Commit with post-state
            client.transactions.commit(
                txn.id,
                post_state={
                    "order_id": order_id,
                    "balance": current_balance - amount,
                    "status": "completed",
                    "charge_id": result.charge_id
                }
            )
            return {"success": True, "charge_id": result.charge_id}
        else:
            raise Exception(f"Payment failed: {result.error}")

    except Exception as e:
        # Rollback on any failure
        rollback = client.transactions.rollback(
            txn.id,
            reason=str(e)
        )

        # Restore original state
        restore_order_state(rollback.pre_state_snapshot)

        return {"success": False, "error": str(e)}

Rollback Confidence Levels

Not all actions can be reversed equally. CertusOrdo tracks rollback confidence:

Level Meaning Example
guaranteed 100% reversible Database transaction
high Very likely reversible API with undo endpoint
medium Probably reversible Email (can recall)
low Uncertain External system
irreversible Cannot be undone Sent SMS, printed document 
txn = client.transactions.begin(
    pre_state={"message": "draft"},
    action_type="send_email",
    rollback_confidence="medium"  # Email can sometimes be recalled
)

Finding Rollbackable Transactions

# Get all transactions that can still be rolled back
rollbackable = client.transactions.list_rollbackable()

for txn in rollbackable:
    print(f"{txn.id}: {txn.action_type} - confidence: {txn.rollback_confidence}")

Querying Transaction History

# List all transactions
all_txns = client.transactions.list()

# Filter by status
completed = client.transactions.list(status="completed")
rolled_back = client.transactions.list(status="rolled_back")

# Get specific transaction
txn = client.transactions.get("txn-id-here")
print(f"Pre-state: {txn.pre_state_snapshot}")
print(f"Post-state: {txn.post_state_snapshot}")

Best Practices

1. Capture Comprehensive State

Include everything needed to restore:

# ❌ Bad - incomplete state
pre_state = {"balance": 1000}

# ✅ Good - comprehensive state
pre_state = {
    "account_id": "ACC001",
    "balance": 1000.00,
    "currency": "USD",
    "last_modified": "2025-01-16T10:00:00Z",
    "related_records": ["TXN001", "TXN002"]
}

2. Use Meaningful Action Types

# ❌ Bad
action_type="action"

# ✅ Good
action_type="payment.process"
action_type="user.update_profile"
action_type="document.sign"

3. Always Include Rollback Reason

# ❌ Bad
client.transactions.rollback(txn.id)

# ✅ Good
client.transactions.rollback(
    txn.id,
    reason="Payment gateway timeout after 30s"
)

4. Set Appropriate Confidence Levels

Be honest about reversibility:

# Database transaction - fully reversible
rollback_confidence="guaranteed"

# Third-party API - depends on their support
rollback_confidence="medium"

# Physical action (print, ship) - cannot undo
rollback_confidence="irreversible"

Integration with Sessions

Transactions typically occur within sessions:

# Create a bounded session
session = client.sessions.create(
    agent_id=agent.id,
    max_actions=50,
    max_value_usd=5000.00
)

# Transaction within session
txn = client.transactions.begin(
    session_id=session.id,
    pre_state={"balance": 1000},
    action_type="transfer"
)

Compliance Benefits

Regulation Requirement How CertusOrdo Helps
SOC 2 Audit trail Every transaction logged
HIPAA Data integrity Pre/post state snapshots
SEC 17a-4 Record retention 7-year audit log
GDPR Right to erasure Rollback capability

Next Steps