🌌 SAGAOPS Enterprise Autonomous Agent OS · PyPI v2.2.0 Century-Grade Release
Give any LLM the Rollback-Proving Engine & Safety Fleet OS.
agent-saga v2.2.0 (SAGAOPS) provides century-grade, bulletproof computer science foundations unifying Omnipresent Autonomous Reality Engine, Zero-Entropy Self-Healing Cortex, and Zero-Knowledge Action Certificates.
Your agent will fail at step 4 of 5 — and one day it will fail by dying. A try/except keeps its cleanup in memory and dies with it. A checkpoint restores your agent's state; it cannot un-send a wire transfer. agent-saga writes the intent to a hash-chained log before the effect fires, so a separate process can finish the rollback the dead one couldn't.
Don't take our word for it — watch it happen in 5 seconds. No API keys, no network, no configuration.
pip install agent-saga && agent-saga demo
The undo runs backwards.
Step 4 fails. Steps 3, 2, 1 come apart in reverse, one at a time.
Both figures below were rendered by agent-saga animate from
the write-ahead log of an actual run — same reconstruction the static
agent-saga graph export uses, so a picture and a diagram of
one log cannot disagree.
COMPENSABLE and shipped no
inverse. Engine verdict:
clean = False.
The right-hand one is the reason to trust the left-hand one. A tool that drew every rollback green would be telling you nothing.
What agent-saga made, precisely.
Five figures on this site — the two above, plus the fleet timeline,
hash chain and outcome matrix on the other tabs — are rendered by
agent-saga animate and agent-saga viz from
write-ahead logs of real runs, rebuilt by
python site/build_assets.py. The layout, the hero shader
and the motion are hand-written: agent-saga is a transactional-safety
library, not a web framework, and it would be a worse library if it
pretended otherwise. The point of generating them isn't convenience —
it's that CI fails if these pictures stop matching what the engine
does.
pytest -q
verify_rollback_invariants()
The 5-second proof
Three acts. Nothing simulated.
agent-saga demo runs the real engine against a real
write-ahead log, with a real gate, real compensations, and a real killed
process. No network, no API keys, no configuration. The "world" is a JSON
file, so damage caused by a process that dies is still there for the next
process to find.
Act I · No transaction
An ordinary agent charges a card, launches a server, then step 3 fails.
Left behind: charges: ['ch_1'], servers: ['i-1'].
Money taken, server running, and nobody is coming to clean it up —
someone has to find it by hand, and first they have to know it happened.
Act II · The same calls, in a saga
Identical tools, wrapped rather than rewritten. Step 3 fails exactly as before.
Left behind: nothing. The boundary unwinds LIFO and reports
clean — a value read from RollbackReport,
so it can never say clean when the engine says partial.
Act III · The process is killed
The saga charges $99, fsyncs the intent, then calls os._exit()
— skipping finally, atexit, and loop shutdown.
Nothing gets a chance to roll back.
Then a different process reads the log and refunds it. This is the
case a try/except cannot answer: its cleanup lived in the memory
that just died.
Two details in Act III are worth pausing on. The intent is durable before the effect fires, so recovery never depends on the process that caused the mess still being alive. And the recovery daemon waits for the dead worker's lease to expire rather than checking a PID — PIDs are reused within minutes, and only an expired lease actually proves an owner is gone.
Afterwards, draw what you watched:
agent-saga graph --wal ./agent-saga.wal renders the forward path and
the rollback fork as Mermaid, where compensated,
COMPENSATION FAILED, and ORPHANED are three visually
distinct outcomes. A partial rollback can never be drawn as a clean one.
Proof, not adjectives
321 failure interleavings. Seven invariants. Zero violations.
Every claim on this page maps to a command you can run. This one takes under a second:
from agent_saga import verify_rollback_invariants
report = await verify_rollback_invariants(max_steps=6)
print(report.format_text())
# 321 interleavings executed · 7 invariants · VERIFIEDverify_rollback_invariants() enumerates every
failure shape up to N steps — which step's forward call raises, which subset of
inverses then refuse, whether a committed step has no inverse at all — and runs
each against the real engine rather than a model of it. LIFO order, no double
compensation, bounded retries, one outcome bucket per step, clean never
claimed over an incomplete rollback, orphans reported rather than dropped.
And it states its bound: bounded model checking, not a proof for unbounded N and not a claim about concurrency. "Verified" with no bound attached is the kind of claim this project exists to avoid.
📈 Benchmarks with methodology
Fast path ~17µs, durable path ~7.9ms — reported
separately and never blended, because one is a deque push and the other is an
fsync. The WAL is measured against your device's own fsync floor, so
the figure that travels between machines is agent-saga's marginal cost:
0.97ms, 27%.
🧪 Prove YOUR rollback works
prove_rollback() breaks your workflow at every step, in both
failure shapes, and compares the world to its starting state. It catches the case
nothing else does: a compensation that runs, returns success, and undoes
nothing.
🔗 Zero-config observability
Spans carry OpenTelemetry GenAI semantic conventions, so Langfuse, Arize Phoenix, Datadog, Grafana and Honeycomb render agent-saga traces in panels already built for them. Prompt capture is off by default — a tracing backend is usually a third party.
What only this log makes possible
Every framework logs. Ours records whether the effect had to be undone.
That single fact is ground truth nobody else collects — and six capabilities fall straight out of it.
🎓 Training data labelled by reality
build_corpus() labels every action by whether the world kept it.
The hard part is blame: when step 5 fails, steps 1–4 roll back and they
were correct. Labelling them negative teaches a model to avoid the calls that
worked — so they are COLLATERAL and excluded. DPO-shaped
preference pairs, matched within a tool.
⏲ Try a cheaper model on real history
counterfactual_replay() turns the log into a simulator of that
afternoon's world. Nothing executes — the replay never invokes a
forward callable at all. When the candidate diverges the answer is
UNKNOWABLE, not a guess.
🎭 Share traffic, not customers
WALProfile.fit() keeps shapes and ranges, never a value a person
typed — so the profile itself is shareable. Fifty real sagas become
fifty thousand synthetic ones. Every record is marked __synthetic__:
a log indistinguishable from a real one is an instrument for fabricating evidence,
not a fixture.
🔮 A gate that improves as you run
FailureModel.fit() learns which call shapes had to be undone, and
reports lift over the base rate — "9 of 12 failed" is meaningless when
three quarters of everything fails. Below its support threshold it produces no
number and says silence is not a clean bill of health.
🛡 No side effect on an invented number
ProvenancePolicy classifies every argument: SOURCED > USER >
DERIVED > MODEL. Untagged means MODEL, and SOURCED is verified against the
document, not accepted on the label. An agent may not move money on a figure
it made up.
🌐 13 framework adapters
LangGraph, CrewAI, AutoGen, LlamaIndex, OpenAI Agents, Semantic Kernel, Vertex AI, Temporal, Camunda, SQLAlchemy, Supabase. One saga spans all of them — the boundary is a contextvar, so a wrapped tool joins whatever saga is open, whichever framework called it.
Plus agent-saga adopt to wire
an existing project up mechanically (it will not decide your semantics — the
generated module refuses to import until a human classifies each side effect),
cascade() for verification-gated escalation across model tiers, and
RepairSession to fix one failed step and resume instead of unwinding
everything.
Concurrency is a shape, and a terminal can't draw it.
Nine orders ran at once. Three failed and rolled back. Scrolled past in a
console those are 60-odd interleaved lines; on a time axis you can see which
overlapped, how long the unwinds took, and that the failures cluster rather
than scatter. This is agent-saga viz --kind fleet over the
write-ahead log of that run — the red bars are sagas the engine actually
aborted, not a colour picked for drama.
AgentKit SDK
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 →Core Design Philosophy
The 5 Fundamental Principles of agent-saga.
The core contract that separates true transactional safety from post-disaster cleanup scripts.
🎯 Auditable Consistency is the Contract
“A bank does not buy a post-disaster cleanup script — it buys a control that refuses to enter an uncompensable boundary without a human on the hook.”
⚡ Runtime-Derived Compensations
AI agents choose forward tools dynamically at runtime. The inverse action can only be derived after the forward step executes and returns concrete state parameters (e.g., charge IDs, row IDs).
🔍 Honest Rollbacks (clean vs. partial)
Swallowing partial failures is a critical vulnerability. Operators must always distinguish a 100% clean rollback from a partial failure requiring human intervention (RollbackReport.clean).
🛑 Pre-Flight Gates over Post-Cleanup
High-risk or non-compensable actions trigger policy gates before any side-effect is modified — the only point at which refusal is completely free.
💥 Fail Loud, Never Silent
Write-Ahead Logs must never silently swallow unreadable or corrupted records. If a recovery daemon cannot parse an entry, it halts and alerts immediately.
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.
Which calls the world kept.
Every framework logs that a tool was called. This log records whether the effect had to be taken back — and that single extra fact is what turns a trace into training data, a risk model, and the matrix below.
Note what it refuses to do: below five observations a cell shows its raw count and goes grey. "100% orphaned" over one call is a number that means nothing and reads as though it means everything.
agent-saga viz --kind outcomes --wal ./prod.walInteractive 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).
Each record names the one before it.
Every WAL record carries the SHA-256 of its predecessor. Edit a record, delete one, reorder two, and the links stop matching — there is no way to revise history without leaving the seam visible.
The picture below is not a diagram of the idea. chain_ribbon()
walks the chain while rendering it: a link whose recorded parent
isn't the record that precedes it is drawn red and labelled BROKEN, the
header reports the count, and when a log is cropped to fit, every break is
kept. A tamper-evidence graphic that drew a doctored log as intact would
not be a flawed graphic — it would be a forgery aid.
agent-saga verify --wal ./agent-saga.walCore 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 2,103 tests green.
🧾 Grounded Answers
A hallucination cannot pose as a sourced fact. Every claim in an answer is VERIFIED against live SHA-256 receipts — or wears a label: UNCITED, BROKEN_CITATION, BROKEN_QUOTE. Your policy decides what unlabeled claims may touch.
✅ 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.
1. Installation
2. 30-second quickstart — the AgentKit SDK
3. Prove it in CI — rollback-safety gate
4. OpenTelemetry & LangSmith Tracing Setup
5. GitHub & Cloud Connector Safety
Tell us what broke, what worked, and what's missing
Enterprise inquiry, integration requirement, bug report, or a review of how it went in production — all of it is wanted, especially the unflattering kind.
How this form works, stated plainly. This page is static. The form below saves your message
in your own browser — unless you are running the local inquiry backend
(python site/server.py, readable with agent-saga inquiries), it does not
reach anyone, and it will tell you so instead of showing a green tick. To actually reach a human,
use one of these:
Your message is sitting in this browser and nowhere else. Take it somewhere it will be read: