AI Agent Retry Safety: Prevent Duplicate Side Effects

Why AI agent retries are different

Traditional retry logic works well for reads and naturally idempotent operations. Agent tools are different because many of them create real-world effects: charging a customer, issuing a refund, sending a message, booking a reservation, creating an order, provisioning infrastructure or mutating production state.

The dangerous case is not a clean failure. It is an ambiguous outcome: the external provider may have committed the action, but the caller never received a definitive acknowledgement.

The dangerous retry sequence

1. An agent requests a consequential write.
2. The external provider performs the action.
3. The response is lost, delayed or interrupted.
4. The agent sees a timeout or transport failure.
5. The agent cannot tell whether the action happened.
6. A blind retry risks producing the same side effect again.

This is why a timeout is not proof of failure. At the execution boundary, the correct state may be UNKNOWN, not failed.

The Once decision model

Once tracks the logical real-world operation rather than treating each transport attempt as a new action. Retries of the same logical operation reuse a stable operation identity.

CONFIRMED  → replay or suppress
ABSENT     → execute
UNKNOWN    → block or reconcile

CONFIRMED means supported execution truth shows the operation already succeeded, so the result can be replayed or duplicate execution suppressed. ABSENT means the protected operation is not known to have happened and may proceed. UNKNOWN means the truth cannot yet be established safely, so the system should reconcile or block rather than guess.

When an operation needs retry safety

Evaluate Once when all four conditions are true:

1. The operation can change external state.
2. The same logical operation may be retried.
3. The first attempt can become ambiguous after a timeout, lost response, crash, queue redelivery or similar failure.
4. Blind duplicate execution would be undesirable or costly.

High-signal examples include payments, refunds, payouts, bookings, reservations, orders, account changes, provisioning, production writes, consequential messages and MCP tool calls that mutate external systems.

When you usually do not need it

Pure reads, searches, retrieval, generation-only tasks and operations where repetition cannot create a meaningful duplicate external effect generally do not need an execution-safety layer. Retry safety should be concentrated at consequential write boundaries rather than added indiscriminately to every call.

Stable operation identity is the foundation

If every retry generates a fresh identity, no deduplication layer can know that two attempts represent the same business intent. The operation identity therefore needs to remain stable across retries of the same logical action.

A useful identity is derived from the business operation or workflow intent, not from the transport attempt. For example, a retry of the same refund should preserve the refund operation identity; a genuinely new refund should receive a different one.

Why an idempotency key alone may not be enough

Provider-native idempotency is valuable and should be used when available. But agent workflows often cross multiple systems, some providers do not support native idempotency, and a caller may still need durable knowledge of what happened after an ambiguous response.

Once is designed to complement provider-native mechanisms with stable operation identity, durable Once state, replay and provider-specific reconciliation. Where authoritative execution truth cannot be established, the safety model preserves uncertainty instead of silently treating uncertainty as permission to execute again.

MCP retry safety

MCP tools can expose both harmless reads and consequential writes. Retry policy therefore cannot be based only on the fact that a tool call failed at the protocol or transport layer.

GitHub's MCP Scripts specification states that retry safety for potentially non-idempotent tool invocations is a caller responsibility and recommends idempotency safeguards or explicit side-effect checks before retrying state-changing tools. That is the same execution boundary Once is designed to protect.

Read the Once guide to MCP idempotency →

Industry reliability guidance is converging on the same problem

AWS's Agentic AI Lens identifies retries without idempotency as a source of duplicate side effects and recommends deterministic operation identity, checking for an existing result before execution and propagating idempotency through workflows. GitHub's MCP Scripts specification similarly warns that state-changing tool retries require explicit safeguards.

These recommendations are important because agent reliability is no longer only about getting the model to choose the right tool. Reliability also requires safe execution after the model has already made the correct decision.

Example: refund after a lost acknowledgement

Imagine an agent requests a £50 refund. The payment provider commits the refund, but the network drops before the response reaches the agent. The agent sees a timeout.

Unsafe logic says: the request failed, retry it.

Safe logic says: the outcome is unknown; determine execution truth before issuing another refund.

That distinction is the core of agent retry safety.

Once's role at the execution boundary

Once combines stable operation identity, durable state, replay and provider-specific reconciliation so supported operations can be resolved without blindly repeating an external side effect.

// Conceptual flow
const operationId = stableBusinessOperationId(input)

const truth = await once.truth(operationId)

if (truth === "CONFIRMED") return replay()
if (truth === "ABSENT")    return executeProtectedWrite()
if (truth === "UNKNOWN")   return reconcileOrBlock()

How to start

For agent-assisted discovery and integration, the Once MCP package can assess a project for likely consequential operations:

npx -y @once-agent/mcp

Official MCP Registry identity: io.github.stringsofthemind-oss/once

For the TypeScript SDK:

npm install @once-agent/sdk

The MCP layer helps agents discover, explain and integrate the protection boundary. Production application agents do not need to call MCP before every protected write; the Once Runtime remains the execution-safety boundary.

Frequently asked questions

What is AI agent retry safety?

It is the ability to retry a logical operation without blindly repeating a consequential external side effect when the first attempt may already have succeeded.

Why is UNKNOWN different from failed?

Failed means there is sufficiently authoritative evidence the operation did not complete. UNKNOWN means the caller lacks enough evidence to say either way. Treating UNKNOWN as failed can create duplicates.

Does Once stop agents from retrying?

No. The goal is not to remove retries. The goal is to make retries safe at consequential execution boundaries by replaying confirmed work, allowing absent work to proceed and preserving uncertainty when truth cannot be established.

Does Once guarantee exactly-once execution?

No. Arbitrary external systems cannot generally participate in one atomic transaction with an independent execution ledger. Once therefore uses a narrower model based on stable identity, durable state, replay and reconciliation for supported paths.

Do reads and searches need Once?

Usually not. Reads, search and retrieval are normally safe to repeat because they do not create consequential duplicate external side effects.

Related Once guides

MCP idempotency · Ambiguous timeouts · Duplicate refund timeout · Duplicate booking retry · OpenAI Agents · Vercel AI SDK · LangChain / LangGraph · CrewAI · Claude Code

Primary references

AWS Agentic AI Lens — Implement idempotent task execution patterns

GitHub Agentic Workflows — MCP Scripts Specification, retry policy