Idempotency key

An idempotency key is a unique label attached to a request so that if the same request is sent again, the receiving service recognizes it as a repeat and runs the action only once.

An idempotency key is a unique label attached to a request so that if the same request is sent again, the receiving service recognizes it as a repeat and runs the action only once. The agent generates one label per intended action and reuses that exact label on every retry. Say an agent sends a customer a payment receipt by email, the connection drops before it hears back, and the agent retries. Without a key, the service treats the retry as a brand-new request and the customer gets two receipts. With the same key on both tries, the service sees the second one matches the first, returns the original result, and sends nothing twice.

Builder example

Retries are normal in any agent that talks to outside services, because a timeout often means the request went through but the reply got lost. If your agent charges a card, books a slot, or posts a message, a blind retry can double the action and the user feels the mistake directly. Tell your agent to attach a stable idempotency key to each action that has a side effect, and reuse the same key when it retries rather than minting a fresh one.

Common confusion: An idempotency key works only when the receiving service is built to honor it and store recent keys. The key is a request you make of the service; if that service ignores the header or has no memory of past keys, sending one changes nothing and the duplicate still goes through.