⚡ Transactional Safety for AI Agents · PyPI v0.3.0
Give your agent a transaction it can reason about.
agent-saga v0.3.0 wraps an AI agent's real-world actions in a transaction: a pre-flight gate stops the dangerous call before it runs, every intent is written to a hash-chained tamper-evident log, and any failure rolls the committed steps back in reverse order. New in 0.3.0 — the AgentKit one-call SDK the agent uses to wrap a tool and read exactly what it is guaranteed.
pip install agent-saga
New in v0.3.0 · AgentKit
One object. Three verbs. A safety net an agent can read.
The whole engine — the gate, typed compensation, the tamper-evident log, the audit proofs — behind one import. An agent wraps a tool once, runs work inside a transaction, and (the genuinely new part) can ask the system what it is guaranteed and whether it is safe to act right now.
📜 guarantees() — a manifest it can trust
A versioned, JSON-serialisable statement of exactly what is enforced before an effect and guaranteed after — including an explicit not_claimed clause. A safety surface that hides its limits is a liability; this one states them.
🚦 status() — fail-closed live posture
Before a burst of effectful work, an agent asks kit.status(). If a global kill-switch is halting effects — or if that signal simply can't be read — it reports not ready. Never a confident green when the truth is unknown.
🔌 Zero-ceremony pass-through
The same wrapped tool runs untouched outside a transaction — so it works identically in a script, a notebook, or a test with no saga boundary and no special-casing.
Click to inspect code →Universal Spectrum Coverage
From Hobby Makers & Coders to High-Precision Aerospace.
Whether building an indie side project, auto-refactoring code, executing $10M banking transfers, or diagnosing patient treatments, agent-saga powers mission-critical reliability everywhere.
IoT & Hardware Robotics
Enforces hardware actuator angle limits and battery voltage bounds, preventing physical servo burnout or runaway robot motor commands.
GitHub & Cloud Infrastructure
Plug-and-play GitHub/GitLab PR auto-reverts and AWS/GCP/K8s infrastructure auto-cleanup if deployment or coding agent tasks fail.
High-Value Wire & Billing
Enforces 3/3 Triple Redundant Consensus before executing multi-million dollar transfers, preventing hallucinated refunds or duplicated wire charges.
Prescription & Diagnosis Safety
Intersects LLM treatment recommendations against strict clinical boundary range rules (0.1mg - 50mg), blocking lethal medication overdose attempts pre-flight.
LangSmith, Phoenix & OTEL
Stamps Saga UUID and prompt context into OpenTelemetry spans and LLM trace providers, linking hallucinated prompts directly to rollback causes.
Interactive Web UI & Replay
Clean Web UI (agent-saga ui) and CLI Time-Travel Replay (agent-saga replay <id>) for risk teams to inspect, approve, or debug failed sagas.
Interactive Practical Playground
Practically test your own input data: Before vs. After agent-saga.
Type custom input parameters below. Use the prominent toggle switch to compare how raw AI models crash and corrupt data (BEFORE) versus how agent-saga verifies and auto-restores state (AFTER).
Core Capabilities
Click any capability to inspect its real code & architecture.
Every card below maps to shipping, tested code in the package — not a roadmap. The suite is 2007 tests green.
✅ Rollback-Safety Certificates
Machine-checkable proof that every committed effect was accounted for. agent-saga certify returns non-zero in CI, so a release that could strand an uncompensated charge can't ship.
🌳 Selective-Disclosure Audit Proofs
Prove one saga to an auditor without revealing any other. A Merkle tree with domain-separated leaves yields a compact inclusion proof under a published root.
Click to inspect code →⚡ Predictive Pre-Execution
Speculatively run REVERSIBLE-only steps ahead of confirmation behind an HMAC lease bound to (intent, tool, expiry). Stale, forged, or cross-intent speculations can never be redeemed.
Click to inspect code →🔐 Passkey / Hardware Approvals
An IRREVERSIBLE step can demand a hardware-bound Ed25519 signature over a digest of the exact action — so an approval can't be replayed onto a different call.
Click to inspect code →🕸️ Offline Mesh Sagas (CRDT)
Agents acting offline on separate devices keep local WALs that merge with a commutative, idempotent, associative G-Set CRDT — any sync order converges to the same history.
Click to inspect code →🛰️ Edge / Async Storage Sink
The engine is separable from disk: point the WAL at any async store (proven, not asserted) to run the same guarantees at the edge or in a WASM sandbox.
Click to inspect code →☁️ Self-Hosted Control Plane (cloud-server)
Run your own control plane backend (agent-saga cloud-server) matching the sagaops.dev SaaS REST API for audit ingest, approvals, and fleet budget sync.
📐 BPMN 2.0 Visual Workflow Designer
Interactive web canvas tab on the dashboard to visually design agent compensation flows and export typed @saga_scope Python code in 1 click.
🧪 Standalone pytest-agent-saga Package
Dedicated Pytest companion package (pip install pytest-agent-saga) providing isolated WAL fixtures, multi-point chaos runners, and deterministic replay assertions.
🛡️ Array & Dotted Redaction (redact_path)
Surgically mask nested fields including list indices (e.g. redact_path(records, "kwargs.items.0.cvv")) without writing custom lambda functions.
🔄 Multi-Turn Agent Self-Healing Loop
Bounded correction loop (SelfHealingLoop) that feeds gate refusal reasons back to the agent with exponential backoff and human escalation fallback.
🧠 Zero-Config Embedding Risk Scorer
Dynamic anomaly risk scoring against known-bad tool calls (EmbeddingRiskScorer) with zero external dependencies and offline execution.
💬 Slack OAuth & Slash Command Integration
Interactive Slack Block Kit app with OAuth URL construction (build_oauth_install_url) and /saga-approve slash command handling.
📊 OpenTelemetry & LangSmith Tracing
Binds Saga UUIDs to OpenTelemetry spans, LangChain callbacks, and Phoenix traces, identifying the exact prompt context that caused a rollback.
Click to inspect code →💻 Protected Web Dashboard (agent-saga ui)
Web UI dashboard serving visual approval queues, SSE live WAL streaming, spend limit gauges, and token authentication.
Click to inspect code →Developer Documentation
Quickstart & Integration Reference.
Get started in 30 seconds. Wrap your agent loops in a single decorator or context manager.