“Retry” sounds like a simple instruction. In an agent system, it is a question.
Retry what?
- The user’s request?
- The durable record that accepted it?
- The model call that was interrupted?
- The shell command that timed out?
- The external write that may already have happened?
Those are not the same operation. Treating them as if they were is how an agent sends two messages, creates two tickets, reruns a destructive migration, or tells a user that work failed when the effect actually completed.
A safe retry begins by naming the identity of the thing being retried.
HTTP systems already face a version of this problem. The IETF Datatracker status page records revision -07 of the Idempotency-Key proposal as expired and archived. It was a work-in-progress Internet-Draft, not an RFC. The draft described a client-generated value that could help a resource server recognize a later retry of the same non-idempotent request; that is useful design precedent, but it is not a current standard for agent recovery.
The design challenge is to preserve user intent without pretending that every model attempt or external effect is safely replayable.
A proposed three-identity retry model
Virillio Code Editorial proposes three identities with different lifetimes and guarantees. This taxonomy is an editorial design model, not terminology defined by the IETF or an established industry standard.
- Identity: Intent identity — Answers: “Which human goal is this?” — Should be stable across: Clarifications, planning, and many execution attempts — Must not imply: That every operational step is equivalent
- Identity: Admission identity — Answers: “Which exact input was durably accepted?” — Should be stable across: Exact delivery retries of the same input — Must not imply: That the input’s effects are complete
- Identity: Effect identity — Answers: “Which external state transition is this?” — Should be stable across: Safe replays of the same semantic write — Must not imply: That a new intent should reuse an old side effect
The model’s individual provider call, tool invocation, or worker process can have its own attempt identifier as well. That is useful for diagnostics, but it should not be mistaken for a durable business identity.
This separation turns “retry” from a blunt instrument into a set of explicit recovery decisions.
1. Intent identity: preserve the user’s goal
An intent identity answers the broadest question: what is the user trying to accomplish?
For a coding agent, the intent may be “fix the pagination behavior described in this issue.” For an operations agent, it may be “prepare the report and ask before sending it.” For a research agent, it may be “compare these options using primary sources.”
The intent persists through normal work:
- the model asks a clarification,
- a tool result requires a new plan,
- a context window resets,
- a worker fails and another resumes,
- a human corrects an assumption without changing the goal.
But intent is too broad to deduplicate every action. “Prepare the report” may lead to several reads, drafts, revisions, and eventually one authorized delivery. Reusing one identifier for all of those hides the difference between safe observation and consequential effect.
Intent is the thread that holds work together. It is not the key that makes every operation idempotent.
2. Admission identity: deduplicate exact input delivery
An admission identity belongs to a specific, durable user input. It records that the system accepted this request with this content and delivery semantics.
Suppose a client sends “Pause the current work and answer this first,” then loses its connection before receiving a response. Retrying the exact request may be appropriate. The runtime can recognize the same admission identity and return the existing accepted record rather than append a duplicate instruction.
That is a narrower claim than “the agent will not do anything twice.” It means:
- the same user input was accepted once,
- a transport retry should reconcile with that accepted input,
- a different payload or different delivery mode is not silently merged,
- later execution still has its own state and failure semantics.
The distinction matters for active agents. Two textually similar messages can carry different meaning if one is a queued note and the other is an immediate interruption. A retry system should not decide that difference by fuzzy text matching.
3. Effect identity: protect the external world
Effect identity applies where the system changes something outside the agent’s own durable record:
- creating a ticket,
- sending an email,
- publishing a document,
- charging a card,
- deleting a resource,
- changing a deployment setting.
The expired IETF proposal remains relevant as a design reference: a caller supplies a unique key so the resource can recognize a retry of the same non-idempotent request. In an implementation that adopts this pattern, the key should belong to one intended effect and should not be reused for a meaningfully different payload.
For agents, add two constraints:
- The effect key should be derived from a deliberately scoped semantic action, not merely the current model attempt.
- A retry must preserve enough evidence to determine whether the effect is confirmed, rejected, partially complete, or unknown.
An unknown outcome is the important case. If a network timeout occurs after a write may have been accepted, the correct next action is often verification—not a blind replay.
The retry decision table
When an agent failure occurs, classify the failure before retrying.
- What failed?: Client transport before durable admission is confirmed — Safe default: Retry the admission with the same admission identity — Why: The system may need to accept the input once
- What failed?: Client transport after durable admission is confirmed — Safe default: Reconcile with the existing admission — Why: Appending the same instruction again may change agent behavior
- What failed?: Model call before any tool effect — Safe default: Retry or resume from durable state under a bounded policy — Why: The work may be safely recomputed, subject to budget and policy
- What failed?: Read-only tool call — Safe default: Retry if freshness and rate limits allow — Why: Repetition usually has no external effect, but the data may change
- What failed?: Deterministic local command — Safe default: Retry only if the command’s own outputs and workspace state permit it — Why: A local command can still leave partial files or locks
- What failed?: External write with a confirmed idempotency mechanism — Safe default: Retry using the same effect identity — Why: The target system can recognize the semantic duplicate
- What failed?: External write with unknown outcome — Safe default: Verify the target state before deciding to replay — Why: A second write may duplicate or compound the effect
- What failed?: Non-idempotent destructive action — Safe default: Stop or require explicit recovery policy — Why: Automation should not invent permission to repeat irreversible work
The table should live near the tool and integration design, not only in an incident runbook. A model cannot make a safe recovery decision if the runtime has not made the operation’s retry class available.
Retries need truthful states
Many systems collapse a complicated outcome into success or failure. Agent recovery needs more honesty:
- State: Confirmed success — Meaning: The intended state transition is known to have happened — What the agent should do: Continue and report the evidence
- State: Confirmed failure — Meaning: The effect did not happen — What the agent should do: Correct the cause or ask for direction
- State: Partial success — Meaning: Some scoped work happened, some did not — What the agent should do: Continue from durable evidence; do not restart the whole workflow blindly
- State: Unknown outcome — Meaning: The system cannot tell whether the effect happened — What the agent should do: Verify against the authoritative target before replaying
- State: Blocked by policy — Meaning: The effect needs approval or authority — What the agent should do: Preserve intent and request the specific next permission
The unknown outcome state is not an implementation embarrassment. It is an accurate representation of a distributed system. Hiding it from the agent produces unsafe confidence.
The handoff artifact for a retry
Long-running work often crosses context windows or worker processes. Anthropic’s long-running-harness work describes structured artifacts as a way to carry progress between sessions. Persistence mechanisms such as LangGraph checkpoints can preserve state across recovery, but a checkpoint alone does not establish whether an external effect happened. The same artifact discipline can make retry decisions safer.
A retry handoff should be compact but sufficient:
- intent identity and user goal,
- admitted inputs and delivery state,
- last confirmed durable state,
- open tool operations with effect identities,
- evidence of confirmed, partial, or unknown outcomes,
- current policy boundaries and pending approvals,
- the next safe recovery action.
This is not a full transcript. It is a recovery contract. The next worker should not need to infer whether an external action was already attempted from a large, stale conversation.
Common failure patterns
Using the same key for different meanings
If an effect key is reused after a user materially changes a request, the system can accidentally suppress a legitimate new operation. An idempotency key means “same semantic request,” not “same conversation.”
Treating a model retry as an effect retry
Restarting a model turn may be fine when the only work was planning. It is not automatically safe once the turn triggered a write, started a job, or requested user confirmation.
Deduplicating by text alone
Text equality ignores delivery mode, target scope, authority, and time. A retry record should be tied to explicit identity and semantic metadata, not a hash of natural language.
Claiming success after a timeout
A timeout means the caller lacks a result. It does not prove the effect failed. Make verification a first-class tool or follow-up action.
Retrying forever
Retries spend time, tokens, tool quota, and user trust. Bound them by operation class, error type, and deadline. After the limit, surface the durable state and the next decision to the user.
A practical implementation checklist
Before adding a retry to an agent workflow, answer:
- What is the user’s durable intent identity?
- What exact input admission must be deduplicated?
- Does any tool create an external effect?
- Which effect identities are accepted by the external system?
- How do we verify an unknown outcome?
- What evidence survives a process restart?
- When must the system stop and ask for approval instead of retrying?
If the workflow cannot answer these questions, its retry policy is probably just an optimistic loop.
What we are learning building Virillio Code
The in-development work at Virillio Code has made one transferable idea especially clear: durable admission and local execution are different lifetimes, and neither one alone tells you whether an external effect happened. Reliable agents preserve all three layers—intent, admitted input, and effect identity—so recovery is a controlled decision rather than a replay gamble.
Sources and further reading
- The Idempotency-Key HTTP Header Field — draft status — Revision -07 described a client-generated key for recognizing a retry of the same non-idempotent HTTP request; it is an expired and archived Internet-Draft, not an RFC.
- LangGraph persistence — Checkpoints and persistent state support recovery, resumption, and long-running workflows.
- Harness design for long-running application development — Structured artifacts preserve coherent progress when long-running coding work crosses sessions.
Editorial disclosure
This article was substantially researched, drafted, and revised with AI through the Virillio Code editorial workflow. Virillio Code publishes the final text under its editorial byline, and the supporting primary sources are linked above.