Skip to content
sync ai agents

Making agent actions safe to retry

Assume every side-effecting tool call can run twice, and design for it. Send an idempotency key with each write so the receiving service can spot a duplicate. Where the service has no key support, read the current state before writing. Put each side effect in its own checkpointed step, so a resumed run restores finished results and only repeats work that never completed.

Why does an agent tool call run more than once?

A tool call runs twice when the caller cannot tell whether the first attempt did its work. Timeouts, crashes before an acknowledgement, resumed runs and duplicate deliveries from a queue or webhook all create that doubt.

Start with timeouts. AWS's Builders' Library says a timeout or failure doesn't necessarily mean that side effects haven't happened.

Crashes add a second source. Temporal's docs say Activities won't record to the Event History until they return or produce an error, and that if an Activity fails to report to the server at all, it will be retried.

Resumed runs are the third. In LangGraph, a resumed interrupt restarts from the beginning of the node where the interrupt was called, so any code before the interrupt runs again.

What is an idempotency key and where does it go?

An idempotency key is a unique value your agent generates for one intended action and sends with every attempt of that action. The service uses the key to recognize a retry and return the earlier outcome.

Stripe's API reference shows the server side. For API v1, retries with the same key return the saved response, including 500 errors. Stripe suggests using V4 UUIDs or another random string with enough entropy, and keys are up to 255 characters long.

Keys do not last forever. For API v1, Stripe says keys can be removed automatically once they are at least 24 hours old, and a key reused after the original is pruned produces a new request. Plan your retry and resume windows to close well inside that period.

The IETF Internet-Draft for an Idempotency-Key header says the key must not be reused with another request that has a different request payload. Build the key from the intended action, so each retry of that action carries the same value and a different action gets a fresh one.

Who enforces the key, the agent or the service?

The service does. Temporal's docs say idempotency keys are enforced by the service you are calling from your Activity, not by the Activity itself. The calling code's job is to generate a stable key and pass it on every attempt.

For the idempotency key an Activity sends to an outside service, Temporal suggests combining the Workflow Run ID and the Activity ID, since that value is guaranteed to be consistent across retry attempts but unique among Workflow Executions. In an agent runner, the equivalent is a run ID plus a step ID.

Expect the service to push back on misuse. Stripe's v1 idempotency layer compares incoming parameters to those of the original request and errors if they differ. It also does not save a result when the request conflicts with another request that is executing concurrently, and says you can retry those requests.

What if the tool has no idempotency key support?

Read the current state first, and write only if the change is not already there. LangGraph's Functional API docs list it as one option for a task that may run again, saying to use idempotency keys or check existing results before writing.

Check-then-act has a gap. Two attempts can both read "not done" before either writes. It holds up when one agent owns the action and attempts run one after another. When parallel agents can touch the same record, prefer a tool that accepts a key or supports a conditional write.

AWS draws a line on which calls need this at all. Its view is that APIs with side effects aren't safe to retry unless they provide idempotency, and that read-only APIs are typically idempotent while resource creation APIs may not be. Spend your effort on the calls that create or send something.

How does a checkpoint stop a resumed run from repeating work?

Record each completed step in a durable checkpoint, so resume restores the result instead of calling the tool again. This only covers steps that finished. A step that was in flight when the process died has no recorded result and needs a key or a check.

On resume, LangGraph restores completed task results, while a task that started but did not finish may run again. Its guidance is to give each side effect its own task so resume restores outputs instead of re-running them.

Keep steps small. Temporal describes Activities as an atomic unit of execution that either complete successfully or not, so a step that bundles a lookup, a call and a write repeats all of them on retry. One side effect per step limits a retry to that one effect.

Check where the checkpoint lives. LangGraph's persistence docs say MemorySaver and InMemorySaver store checkpoints in RAM, so a process restart loses them. For production they point to a persistent checkpointer such as PostgresSaver, and describe SqliteSaver as local file-based storage for development.

CrewAI follows the same idea. Its checkpointing docs say that on restore completed tasks are skipped, and that the default on_events value of ["task_completed"] writes one checkpoint per finished task.

Microsoft Agent Framework workflows checkpoint by superstep. Its docs say checkpoints are created at the end of each superstep, after all executors in that superstep have completed.

Does a checkpoint make a tool call exactly-once?

No. A checkpoint narrows the window between the tool succeeding and the result being recorded, but the window remains. Plan for at-least-once execution with idempotent effects. Related terms are collected in the site glossary.

Temporal states the split plainly. For an Activity with a Retry Policy that allows retries, Temporal guarantees the Activity will be observed as completed exactly once, yet it may be executed multiple times and may even partially complete more than once.

The checkpoint write can fail too. CrewAI says auto-checkpoint writes are best-effort, and a failed write is logged while the run continues. Pydantic AI's Temporal integration notes that an event stream handler may run more than once if an activity retries, so its side effects should be idempotent.

How do I keep retries from multiplying across layers?

Retry in one layer only. AWS's best practice for low-cost operations is to retry at a single point in the stack, because the retries at each layer multiply. In an agent system, pick one of the model client, the tool wrapper or the orchestrator to own retries. For repetition at the reasoning level, see preventing agent loops.

If your runtime already retries, leave the step code alone. Temporal advises that you should typically not write retry logic manually within your Activity Definition.

Which sources does this page use?

What do people ask about idempotent agent actions?

  • Should the model generate the idempotency key?

    Prefer the runtime. A model can produce a different string on each attempt, which defeats the key. Derive it in code from the run ID and step ID, as in the Temporal approach above.

  • Does a human approval pause create duplicate calls?

    It can. LangGraph's interrupt rules state that side effects called before interrupt must be idempotent. See human-in-the-loop approvals for where to place the pause.

  • How do I find out which calls were duplicated?

    Log the idempotency key, the attempt number and the outcome on every call. With those fields you can see which keys arrived twice. The debugging guide covers tracing across agents.

Updated November 2026

Not sure which pattern fits?

Six questions, about a minute. You'll get a pattern, a shortlist and the tradeoffs.

Take the finder

Which related questions can you explore next?