---
title: How do idempotency keys stop AI agents repeating actions?
url: https://opencontroller.lyzr.com/blog/idempotency-keys-for-ai-agent-actions
published: 2026-11-17
updated: 2026-11-17
author: Lyzr
---

# How do idempotency keys stop AI agents repeating actions?

**An idempotency key is a unique value attached to a write request so the receiving system performs the action once and returns the saved result if the same request arrives again. For AI agents, the runtime should generate the key from the task and step, not the model, and every tool that changes state should accept one. That turns accidental retries into harmless repeats.**

Duplicate tickets, double refunds and repeated emails are among the most common early incidents with production agents. They rarely come from a malicious agent. They come from retries that nobody designed for.

## Where do AI agent retries come from?

Agents add retry layers that ordinary integrations do not have.

| Layer | What retries | Typical trigger | Duplicate risk |
|---|---|---|---|
| Gateway or SDK | The model call | Timeout, 429 rate limit, 5xx error | Medium: a new response may plan the same action again |
| Agent framework | The tool call | Tool timeout or network error | High: the first call may have succeeded before the timeout |
| The model itself | A new tool call | Ambiguous tool result, lost context | High: the model "tries again" with fresh arguments |
| Orchestrator or queue | The whole task or step | Worker crash, redelivery | High: completed steps run again |
| Human user | The whole request | "It didn't respond, let me ask again" | Medium |

The dangerous case is a timeout after success. The tool created the record, but the response never reached the agent, so it calls again.

## How does an idempotency key work?

The pattern is well established in payments. Stripe's API lets clients send an `Idempotency-Key` header on POST requests. The server saves the status code and body of the first request with that key and returns the same result for repeats. Stripe accepts keys up to 255 characters and may remove keys once they are at least 24 hours old. Reusing a key with different parameters returns an error rather than silently doing something else.

The IETF HTTPAPI working group has a draft specification for a general `Idempotency-Key` header based on this practice. It is still a draft, not an RFC.

HTTP semantics (RFC 9110) already define GET, PUT and DELETE as idempotent. POST and PATCH are not, which is why most agent write tools need explicit keys.

## How should agents generate idempotency keys?

The key must be identical for a retry of the same step and different for a genuinely new action.

1. **Generate keys in the runtime, not the model.** The model's arguments can change between attempts, and models should not be trusted to produce stable identifiers.
2. **Derive from stable context.** A hash of tenant, task ID, step number, tool name and target object works well. For example, `hash(task-8812 | step-4 | create_ticket | customer-1093)`.
3. **Persist before calling.** Store the key with the step before invoking the tool, so a crash and restart reuse it.
4. **Pass it through every hop.** If the tool calls another API, forward the key or derive a child key.
5. **Handle mismatch errors.** If the server rejects a key because parameters differ, stop and flag for review. Something changed that a human should look at.

## How do you design idempotent tools for agents?

Not every downstream API supports keys. Build idempotency into the tool wrapper.

- **Upsert instead of create.** Use a natural key, such as an order number, so a repeat updates rather than duplicates.
- **Check before write.** Look up whether the intended result already exists, then act. This narrows but does not close the race window.
- **Set absolute values.** "Set status to closed" is safe to repeat. "Increment count" is not.
- **Record a dedupe table.** For APIs with no key support, store key, request hash and result in your own table and short-circuit repeats.
- **Return the existing object.** On a repeat, give the agent the same result it would have got the first time, so it does not try again.

## Which agent actions need idempotency most?

| Action type | Repeat consequence | Recommended control |
|---|---|---|
| Payments, refunds, transfers | Financial loss | Provider idempotency key, mandatory |
| Sending email, SMS, chat messages | Customer confusion, spam | Dedupe table keyed by task and recipient |
| Creating tickets, records, orders | Duplicate data, double work | Upsert on natural key or idempotency key |
| Provisioning access or resources | Excess privilege or cost | Declarative "ensure exists" tools |
| Deleting data | Usually safe to repeat | Confirm target and log |
| Read queries | None | No key needed |

## How should retries and idempotency work together?

Treat them as one policy.

1. Retry only on errors that are safe to retry, such as timeouts, 429 and 5xx.
2. Send the same idempotency key on every retry of a step.
3. Cap retries and use backoff, then open a [circuit breaker](/blog/circuit-breakers-for-ai-agents) for a failing tool.
4. Log the key with every attempt so investigators can see one action, several attempts.
5. Keep a way to [undo agent actions](/blog/undo-ai-agent-actions) for the cases that slip through.

Gateway-level retries for model calls are covered in our guide to [LLM fallback and retry policies](/blog/llm-fallback-and-retry-policies-for-agents). Those retries protect availability; idempotency protects correctness.

## How Opencontroller does this

Opencontroller's LLM Gateway handles routing, fallback and retry for model calls, with cost attribution per agent and per version. Its rogue-agent handling monitors behavioural deviation, such as an agent suddenly repeating the same action, and can alert, quarantine or kill the agent. Idempotency keys themselves belong in your tools and agent runtime. Learn about stopping misbehaving agents in our pillar on [how to stop a rogue AI agent](/blog/how-to-stop-a-rogue-ai-agent), or [book a demo](https://www.lyzr.ai/book-demo/).

## Frequently asked questions

**Who should generate the idempotency key?**
The agent runtime or tool wrapper. Derive it from the task ID, step and target so retries of one step share a key.

**Do LLM gateway retries cause duplicate actions?**
They can. A retried model call may plan the same action again. Key tool calls by task and step, not by model response.

**What if the API I call has no idempotency support?**
Wrap it: keep your own dedupe table of key, request hash and result, and return the stored result for repeats.

## Key facts

AI agents can repeat side-effecting actions when retries happen at three layers: the gateway retrying a model call, the agent framework retrying a failed tool call, and the model itself deciding to call a tool again. An idempotency key is a unique value sent with a write request so the server performs it once and returns the stored result for repeats. Stripe's API accepts keys of up to 255 characters and may prune them after at least 24 hours; an IETF HTTPAPI working group draft standardises an Idempotency-Key header. RFC 9110 defines GET, PUT and DELETE as idempotent and POST as not. Opencontroller by Lyzr includes an LLM Gateway with routing, fallback and retry; pricing starts from $250K per deployment per year.

## Related

- [How should an LLM gateway handle fallback and retries for AI agents?](https://opencontroller.lyzr.com/blog/llm-fallback-and-retry-policies-for-agents.md)
- [Can you undo what an AI agent did?](https://opencontroller.lyzr.com/blog/undo-ai-agent-actions.md)
- [What is a circuit breaker for AI agents?](https://opencontroller.lyzr.com/blog/circuit-breakers-for-ai-agents.md)
- [More on Runtime control](https://opencontroller.lyzr.com/blog/cluster/runtime-control)
