Now listed in the official MCP registry — io.github.azender1/safeagent

# AI agents retry.
Retries kill you.
SafeAgent doesn't.

An execution guard that sits between your agent and any irreversible action. Same request_id returns the original receipt — side effect never fires twice. Built from a real financial system. Proven in production.

Install from PyPI View on GitHub Live demo
pip install safeagent-exec-guard
Python 3.10+ Apache-2.0 v0.1.14
01 — The problem

## Without a guard, every retry is a loaded gun.

AGENT
Decides to act
call tool
→
NETWORK
Times out
no confirmation
→
AGENT
Retries
same call again
→
RESULT
Fires twice
$$$, email, trade

Agent frameworks handle retries at the transport layer. None of them know whether the side effect already happened. That gap — between the agent decision and the irreversible action — is where SafeAgent lives.

02 — Origin

## Discovered building a patented financial system.

Real stakes. Real discovery.

While designing PeerPlay — a patented P2P wagering exchange for skill-based tournaments — a critical reliability failure appeared in the settlement layer. When a verification agent timed out and retried, the payout engine fired twice. One tournament, one result, two prize transfers. The patent protected the architecture. Nothing protected the execution boundary.

SafeAgent is the fix, extracted as a standalone primitive. The same problem exists in every AI agent that touches a real system.

USPTO Provisional Patent: 63/914,036
Entity: Zender Gaming Technologies LLC
MCP Registry: io.github.azender1/safeagent
03 — How it works

## Four layers. Exactly-once semantics.

01
Request-ID deduplication
Every tool call gets a deterministic request_id before execution. Same id on retry → return cached receipt, no re-execution.
02
Finality gating
Ambiguous agent signals block execution. Side effects only run when the outcome is confirmed final — not just probable.
03
Durable receipts
SQLite-backed by default. Every execution stored with payload and outcome. Survives process restarts. Full audit trail.
04
State machine enforcement
OPEN → RESOLVED → IN_RECONCILIATION → FINAL → SETTLED. Execution only permitted from FINAL. Replays at any state return the stored receipt.
# First call — side effect runs once receipt = registry.execute( request_id="payment:invoice-C123", action="send_invoice", payload={"to": "client@example.com", "amount": 4500}, execute_fn=send_invoice, ) # Retry with same request_id — original receipt returned, zero re-execution receipt = registry.execute( request_id="payment:invoice-C123", # same id action="send_invoice", payload={"to": "client@example.com", "amount": 4500}, execute_fn=send_invoice, ) # ^ invoice was NOT sent twice
Works with any framework
Claude / MCP
OpenAI tool calls
LangChain
CrewAI
n8n
Any Python function
Official MCP Registry
io.github.azender1/safeagent
Listed April 26, 2026 · v0.1.14 · PyPI verified · registry.modelcontextprotocol.io
04 — Production proof

## Built alongside a live QQQ/TQQQ trading bot.

Real money. Real retries. Real problem.

The rv_qqq bot trades QQQ signals into leveraged TQQQ/SQQQ positions via Alpaca Markets. It has retry logic built in — EXIT_RETRY_COUNT=3, EXECUTION_LOCK_SEC=15 — because broker ACK timeouts are real. When a market order times out but actually filled, the retry fires a second order. On a leveraged ETF, that's a doubled position you didn't intend.

The bot already has a manual execution lock and state machine. SafeAgent replaces that hand-rolled logic with a formal, durable, tested guard. Same guarantee. Zero custom code.

# Without SafeAgent — hand-rolled retry guard (rv_qqq_v14_1 pattern) def place_order_with_retry(symbol, qty, side): last_err = None for attempt in range(1, EXIT_RETRY_COUNT + 1): try: return place_order(symbol, qty, side) # ← fires twice if first timed out but filled except Exception as e: last_err = e time.sleep(EXIT_RETRY_SLEEP_SEC) raise last_err # With SafeAgent — exactly-once guarantee, zero custom state machine def place_order_safe(symbol, qty, side, request_id): return registry.execute( request_id=request_id, # e.g. "trade:TQQQ:buy:2026-04-26T09:47:00" action=f"order_{side}_{symbol}", payload={"symbol": symbol, "qty": qty, "side": side}, execute_fn=lambda: place_order(symbol, qty, side), ) # ↑ retry with same request_id → returns original order receipt, never re-submits
Use cases
[$]
Trading bots
Without guard → doubled position on broker timeout
Broker ACK timeout on a leveraged ETF order. Retry fires. Position is doubled. SafeAgent makes the order call idempotent at the execution level.
[~]
Tournament settlement
Without guard → prize payout fires twice
Verification agent times out, retries, payout executes twice. The original failure mode that triggered SafeAgent's creation inside PeerPlay.
[@]
Payments & notifications
Without guard → duplicate charge, double email
Stripe charge on retry. SMTP duplicate send. Any agent-triggered irreversible action where exactly-once is not optional.
[>]
MCP tool execution
Without guard → tool fires before state confirmed
Claude or any MCP host retrying a tool call. SafeAgent sits above the tool layer — officially listed in the MCP registry as of April 26, 2026.
05 — Get help
Duplicate Execution Risk Audit — $499

## Find every place your system executes twice.

A focused audit of your agent architecture. Every retry path, every side effect boundary, every gap. Delivered as a written report with SafeAgent integration recommendations.

Request audit →