safeagent-exec-guard 0.1.7

Deterministic execution guard for AI agents: request-id dedup + finality gating + durable state.

SafeAgent

Deterministic execution guard for AI agents.

pip install safeagent-exec-guard

SafeAgent prevents duplicate, replayed, or premature irreversible actions triggered by LLM-based agents.

It enforces:

• request-id (nonce) deduplication
• deterministic state transitions
• exactly-once execution semantics
• durable state persistence (SQLite)

This repository demonstrates a control-plane pattern for safe AI agent execution, not a hosted service.

---

Install

pip install safeagent-exec-guard

Requires Python 3.10+

---

Exactly-once Tool Execution

from settlement.settlement_requests import SettlementRequestRegistry

registry = SettlementRequestRegistry()

def send_email(payload: dict):
    print(f"SENDING EMAIL to {payload['to']}")

receipt = registry.execute(
    request_id="email:C123:invoice",
    action="send_email",
    payload={"to": "[e-mail]", "template": "invoice"},
    execute_fn=send_email,
)

print(receipt)

If the same request_id is replayed, SafeAgent returns the original receipt instead of executing the side effect again.

---

Why SafeAgent?

AI agents frequently retry tool calls when:

• APIs time out
• orchestration layers restart
• network calls fail
• workflows replay events

Without protection, this causes duplicate side effects:

• duplicate emails
• duplicate payouts
• duplicate support tickets
• duplicate trades

SafeAgent sits between the agent decision and the irreversible action.

---

Without SafeAgent

create_support_ticket(customer_id="C123")
create_support_ticket(customer_id="C123")  # duplicate ticket

---

With SafeAgent

from settlement.settlement_requests import SettlementRequestRegistry

registry = SettlementRequestRegistry()

receipt = registry.execute(
    request_id="agent_action_123",
    action="create_support_ticket",
    payload={"customer_id": "C123"}
)

print(receipt)

Replaying the same request_id returns the same receipt.

---

OpenAI-style Tool Example

AI agents commonly call tools through structured payloads.

SafeAgent ensures tool calls execute exactly once.

from settlement.settlement_requests import SettlementRequestRegistry

registry = SettlementRequestRegistry()

def send_email(payload: dict) -> dict:
    print(f"REAL SIDE EFFECT: sending email to {payload['to']}")
    return {
        "status": "sent",
        "to": payload["to"],
        "template": payload.get("template", "default"),
    }

receipt = registry.execute(
    request_id="email:user123:invoice",
    action="send_email",
    payload={
        "to": "[e-mail]",
        "template": "invoice_reminder",
    },
    execute_fn=send_email,
)

print(receipt)

Example Output

FIRST CALL
REAL SIDE EFFECT: sending email to [e-mail]

SECOND CALL WITH SAME request_id
dedup_same_request_id
same execution_id returned

---

What Problem Does This Solve?

Production AI agents frequently:

• retry tool calls
• replay webhook events
• loop under uncertainty
• trigger the same action twice

When those actions touch real systems, duplicates are costly.

Examples:

• sending emails twice
• charging customers twice
• placing duplicate trades
• creating duplicate tickets

SafeAgent ensures irreversible actions run only once.

---

High-Level Flow

Agent Decision → Reconciliation / Consensus → Finality Gate → Execution (exactly once) → Receipt / Audit

---

State Machine

OPEN
 → RESOLVED_PROVISIONAL
 → IN_RECONCILIATION
 → FINAL
 → SETTLED

Properties:

• ambiguous signals enter reconciliation
• execution only allowed in FINAL
• replay-safe execution
• late signals ignored after finality

---

Key Features

Durable Persistence

SQLiteStore allows:

• durable state storage
• restart safety
• ACID guarantees

Request-ID Deduplication

Each execution requires a unique request_id.

If the same request replays:

same request_id → same execution result

This prevents duplicate side effects.

---

Demos

Duplicate Execution Prevention

python examples/safe_agent_demo.py

AI Outcome Simulation

python examples/simulate_ai.py

Persistence Demo

Run twice:

python examples/persist_demo.py
python examples/persist_demo.py

---

Project Structure

models.py
state_machine.py
reconciliation.py
gate.py
store.py
policy.py

settlement_requests.py

examples/
    safe_agent_demo.py
    simulate_ai.py
    persist_demo.py
    nonce_demo.py

---

Production Usage

If you are implementing SafeAgent in a production AI system and need help adapting the reconciliation rules or execution model, see:

LICENSING.md

---

License

Apache-2.0