AI AGENT EXECUTION SAFETY / MCP IDEMPOTENCY

THE SAME ACTION
SHOULD HAPPEN
ONCE.

Once is AI agent execution-safety infrastructure for MCP tools and applications that need safe retries after ambiguous outcomes. Stable identity. Durable state. Provider reconciliation. Protect supported refunds, bookings, payments and other consequential writes from unsafe duplicate execution after timeouts, lost responses and retries.

Test Once at your scale Open live proof
MCP / AGENT INSTALL npx -y @once-agent/mcp
ONCE / EXECUTION CORE LIVE
OPERATION op_8F21
ATTEMPTS 02
SIDE EFFECTS 01
LEDGER STATE CONFIRMED
REPRODUCIBLE EVIDENCE

Different framework. Different retry machinery.
Same recovery protocol.

The same frozen Once V4 recovery core has been exercised under hard process termination across independent execution models. The control duplicates the external effect; the protected paths reconcile or fail closed instead of blindly executing again.

CONTROL / NAIVE RETRY DUPLICATED
2 external effects Fresh-process replay without an execution-safety boundary.
LANGGRAPH LAB CONFIRMED
1 external effect Real StateGraph + SqliteSaver crash/resume path with reconciliation.
CREWAI LAB CONFIRMED
1 external effect Native BaseTool boundary + explicit fresh-process redispatch.
UNKNOWN OUTCOME BLOCKED → CONFIRMED
1 effect, zero blind replay Provider truth unavailable → fail closed → reconcile when truth returns.
Audit the architecture yourself.

Install Once in a project or inspect the hard-crash labs line by line.

Run 60s quickstart View evidence labs ↗

Scope: reproducible framework-level evidence using simulated provider ledgers and the SQLite reference backend. This is not a claim of universal exactly-once execution.

01 · FAILURE

The provider succeeded.
The agent doesn't know.

The dangerous case is not an obvious failure. The external action happens, but the response disappears. From the agent's point of view, success and failure can now look identical.

01 AGENT Send action
→
02 PROVIDER Effect executed
×
03 RESPONSE Lost / timeout
→
04 RETRY Duplicate risk
FAILURE MODE A timeout does not prove the action failed.
02 · IDENTITY

Attempts change.
The operation does not.

Once identifies the real-world operation, not the individual request. Every retry of the same logical action carries the same stable operation ID.

ATTEMPT 01
ATTEMPT 02
ATTEMPT 03
STABLE OPERATION refund:order_123 op_8F21
→
EXTERNAL EFFECT 01 NOT 03
EXTERNAL EVIDENCE / 01
IETF / RFC 9110 / §9.2.2

RETRY ≠ SAFE

HTTP distinguishes idempotent operations because a communication failure can leave the client needing to retry without knowing whether the first request already took effect.

RFC 9110 says a client should not automatically retry a non-idempotent request unless it can know the retry is safe or determine that the original request was never applied.

READ THE STANDARD ↗
03 · ONCE

The retry gets a decision.
Not another blind execution.

Once places durable execution state between the retrying agent and the provider performing the consequential operation.

01
ID

Stable identity

One deterministic identity for the logical operation.

→
02
DB

Durable state

Execution history survives requests, processes and retries.

→
03
?

Provider truth

Reconcile what can actually be established.

→
04
1×

Safe decision

Suppress the duplicate or fail closed.

EXTERNAL EVIDENCE / 02
STRIPE / IDEMPOTENT REQUESTS
24+ HOURS

Stripe supports idempotency so a request can be safely repeated after a connection error without accidentally performing the same operation twice.

Stripe also documents that idempotency keys may be removed automatically once they are at least 24 hours old.

STRIPE API REFERENCE ↗
04 · PROOF

Two attempts.
One external effect.

A Customer Zero regression sends the same supported consequential operation twice using one stable operation ID, then checks authenticated provider truth.

CUSTOMER ZERO / PROVIDER TRUTH VERIFIED
attempts 2
ledger_state CONFIRMED
side_effects 1
provider_executed true
02 ATTEMPTS
01 EXTERNAL EFFECT
EXTERNAL EVIDENCE / 03
AWS CLI V2 / STANDARD RETRY MODE

3 TOTAL
ATTEMPTS

01 INITIAL REQUEST
↓
02 RETRY
↓
03 RETRY

AWS CLI v2 Standard retry mode has a default maximum of two retry attempts.

Including the original call, that produces three total call attempts by default.

AWS DOCUMENTATION ↗
05 · TESTER / SCALE COMPARISON

Put your own traffic through the model.
See the retry problem at your scale.

Feed the same consequential traffic into both sides. The left models blind retry execution. The right models Once on the confirmed replay path. Use your own call volume — from one action to ten billion.

THE POINT Once doesn't stop your agents retrying. It makes retries safe.
ONCE / CUSTOMER SCALE TESTER Without Once vs With Once
SCALE SIMULATION
TRAFFIC PRESETS
RETRY RATE

This is a client-side scale model. Enter 10B and the browser performs arithmetic — it does not send 10B requests. The live proof environment is linked below.

WITHOUT ONCE Blind retry
RE-EXECUTE
INCOMING ATTEMPTS / MONTH 10,010,000 original calls + retries
PROVIDER EXECUTIONS / MONTH 10,010,000 modeled · if every retry is executed again
RETRY EXECUTION OPPORTUNITIES 10,000 same logical work arrives again
VALUE THROUGH RETRY AMBIGUITY £750,000 not a savings claim
DECISION Retry the call and hope the first attempt did not already take effect.
WITH ONCE Safe retry path
REPLAY / BLOCK
INCOMING ATTEMPTS / MONTH 10,010,000 same traffic, same retry pressure
PROVIDER EXECUTIONS / MONTH 10,000,000 modeled · confirmed replay path
RETRIES INTERCEPTED 10,000 replay instead of execute again
BLIND RE-EXECUTIONS 0 on confirmed replay path
DECISION CONFIRMED → replay. ABSENT → execute. UNKNOWN → block rather than guess.
AT YOUR SCALE 10,000 modeled blind retry executions removed. £750,000 of payment value passes through those retry events. This is exposure context, not a claim that every retry becomes a duplicate charge. Annualized exposure context: 120,000 retry events; £9,000,000 of payment value passes through retry-exposed operations.
OPEN LIVE PROOF ↗
What the left side means: it deliberately models the dangerous baseline where a retry is blindly sent to a non-idempotent provider and executes again. Real providers may have their own protections.
What the right side means: the execution count reflects Once's confirmed/replay path. Once does not claim generic exactly-once execution; uncertain outcomes are designed to fail closed rather than be blindly retried.
EXTERNAL EVIDENCE / 04
GOOGLE CLOUD / PUB/SUB

AT-LEAST-
ONCE

MESSAGE 8472 DELIVERED
MESSAGE 8472 DELIVERED AGAIN

Pub/Sub provides at-least-once delivery by default.

Google documents that this means a message can be delivered multiple times, including some cases where it was already acknowledged.

GOOGLE CLOUD DOCUMENTATION ↗
06 · PLAYGROUND

Don't take the claim on faith.
Break it yourself.

The live Once Playground deliberately creates the ambiguous retry path: the provider performs the action, the response becomes uncertain, and the same stable operation is retried.

LIVE ONCE PLAYGROUND Verified retry environment
LIVE
ONCE STATE CONFIRMED
EXECUTION ATTEMPTS 2
ACTUAL SIDE EFFECTS 1
FAILURE MODEL AMBIGUOUS RETRY
Open Live Playground Stripe test mode · no real charge
07 · DEVELOPERS

Go from project
to protected operation.

Using Once through an MCP client or AI agent? Use the MCP install below. Embedding Once directly in an application? Use the SDK terminal below, inspect consequential operations locally, review the proposed protection, then apply supported transformations.

MCP / AGENT INSTALL npx -y @once-agent/mcp
APPLICATION / SDK INSTALL npm install @once-agent/sdk
Terminal @once-agent/sdk 0.1.5
$ npx once setup .
$ npx once scan .
$ npx once protect .
$ npx once protect . --apply
$ npx once doctor
ONCE / 1×

Your agents will retry.
Their side effects don't have to.

Execution safety for consequential AI-agent operations.

Install SDK View GitHub AI / Agent Guide