Idempotency Keys
An idempotency key is a caller-supplied token that lets a system recognize and de-duplicate retried requests, so submitting the same agent action twice produces one effect instead of two.
Definition
An idempotency key is a caller-supplied token that lets a system recognize and de-duplicate retried requests, so submitting the same agent action twice produces one effect instead of two.
Why agents need idempotency
Distributed systems retry. A network blip, a timeout, or a worker restart can cause the same job to be submitted more than once — and for an agent, a duplicated action might mean two payments, two emails, or two infrastructure changes. An idempotency key solves this: the caller attaches a unique token to the request, and the platform uses it to deduplicate. The same key returns the same run identifier and the same result, so a safe retry never causes a second side effect.
Idempotency in the workflow engine
Cordum's workflow engine supports idempotency so a re-submitted run with the same key maps to the existing run rather than starting a new one. The subtlety is payload consistency: if the same key arrives with a different payload, that is a client bug, not a retry, and the platform must reject it rather than silently pick one. Correct idempotency handling is foundational to the saga pattern and to any at-least-once delivery system, because it lets retries be aggressive without being dangerous.
Frequently asked questions
What problem do idempotency keys solve for AI agents?
They make retries safe. Because distributed systems re-deliver messages, an agent action could otherwise execute twice. An idempotency key lets the platform recognize the duplicate and apply the effect once, returning the original result.
What happens if the same key is reused with a different payload?
That signals a client error rather than a genuine retry. A correct implementation rejects the mismatched request instead of silently choosing a payload, so callers are forced to fix the inconsistency.
Related reading
Govern your AI agents with Cordum
Cordum is the agent control plane: policy-before-dispatch enforcement, human approvals, and a tamper-evident audit trail for autonomous AI agents.