Design idempotency keys for agent actions

The same business operation needs one stable key across uncertain retries.

01 / The operating case

What changes in a real workflow?

A payment API times out after accepting invoice I-42; the agent retries.

Trace the authority boundary
  1. 01Authority origin
  2. 02Task and grant
  3. 03Current decision
  4. 04Observed outcome

02 / Decision contract

What the executor must check

Derive key from stable invoice-release intent, store request digest and effect result atomically, return the first result on identical retry and reject changed payee or amount.

InputPrincipal · task · action · target
DecisionGrant ancestry · policy · current state
ResultEnforce · record · verify outcome

03 / Failure and evidence

What goes wrong, and what can be proven?

Failure mode

A per-attempt random key allows duplicate payments, while a broad key conflates distinct invoices.

Evidence to retain

Keep key, canonical request hash, attempts, executor transaction ID and reconciled settlement.

04 / Canonical scope

Why this reference stands alone

Authorization replay concerns reuse of permission; idempotency owns deduplication of an allowed effect.

Illustrative implementation artifact

Retry decision table

Same key + same digest + completed => return prior result
Same key + same digest + unknown => reconcile first
Same key + different digest => reject conflict
New key + same business intent => investigate duplicate

Primary references

Read the underlying material

Architecture discussion

Choose one consequential action and make its boundary explicit.

Request a Conversation