How to Write an Idempotency Key an Agent Can Derive

An idempotency key needs three properties. OneUptime's event key guide names them: deterministic (same input, same key), unique (different events, different keys), and stable (the key does not change on retry). Content-based hashing is the strategy that gets you all three without trusting the caller.

The recipe has four steps.

1. Pick the identity fields. These are the values that define the operation: tenant, operation name, resource, and any natural id that already exists (an order number, an invoice id, a shipment id). Not the model's reasoning, not a timestamp, not a random uuid.
2. Build a canonical string. Join the fields with a separator that cannot appear in a field value, and fix the order. tenant_id:operation:resource_id is the minimum. Add an amount or a version only if the business rule says two different amounts are two different operations.
3. Hash it. SHA-256 over the UTF-8 bytes of the canonical string, hex-encoded.
4. Send and store. The agent puts the digest in the Idempotency-Key header; the server stores it next to the result.

In TypeScript, with a stable serializer for any payload fields you choose to include:

import crypto from "node:crypto";

function canonical(parts: readonly string[]): string {
  return parts.map((p) => p.normalize("NFC").trim()).join("\u001f");
}

function deriveKey(tenantId: string, op: string, resourceId: string): string {
  const input = canonical([tenantId, op, resourceId]);
  return crypto.createHash("sha256").update(input, "utf8").digest("hex");
}

The \u001f unit separator matters. A naive join with : breaks the moment a field contains a colon, and two different operations can then hash to the same string. Length-prefixing each field is the stricter alternative: tenant.length + ":" + tenant + ....

If you must include payload fields, hash a stable stringify of just the fields that define uniqueness, and drop timestamps, request ids, and anything the model generated.

Most duplicate-charge incidents come from a key that includes too much or too little. Too much and retries look like new work; too little and genuinely separate operations collapse into one.

The decision rule: include a field if a change to it means a different business outcome. Exclude it if a change to it is noise from the retry or the model.

The Shopify documentation draws the same line from the other side: two inventory increments with identical variables are still two operations if the client intended them as separate receipts from separate suppliers, and the client is the only party that knows the intent (Shopify). For an agent, "client intent" has to come from the business record, not from the model's narration of its own intent.

That is the rule that survives a model swap. If the key is sha256(tenant:refund.create:order_8812:v2), moving from one model to another changes nothing about the key, so a retry after the swap still hits the stored result.

A derived key is worthless if the server does not enforce it. Five rules cover most of the ground.

Store the result, not just the key. The record needs the key, the request fingerprint, the status, the response body, and a state. Zuplo recommends keeping keys for 24 hours to 7 days, long enough to cover retry windows without growing the table forever. Shopify uses a 24-hour retention window for its idempotent mutations (Shopify).

Reject mismatched reuse. If the same key arrives with a different fingerprint, return an error rather than replaying. This catches a derivation bug before it silently merges two operations.

Serialize concurrent duplicates. Two parallel tool calls with the same key must not both execute. A unique index on the key plus a row lock, or a distributed lock, makes one wait and the other replay (Zuplo). Shopify returns a dedicated concurrent-request error for the in-flight case.

Record in-progress state. Write the key with a pending status before the side effect, then update to succeeded or failed. Without the pending row, a crash between the side effect and the result write leaves no trace, and the next retry repeats the charge.

Scope keys per tenant. Even with a tenant id inside the hash, enforce tenant scoping in the lookup so a key leak cannot read another tenant's stored response.

A minimal table looks like this:

CREATE TABLE idempotency_keys (
  key           text PRIMARY KEY,
  tenant_id     text NOT NULL,
  fingerprint   text NOT NULL,
  status        text NOT NULL,   -- pending | succeeded | failed
  status_code   int,
  response_body jsonb,
  created_at    timestamptz NOT NULL DEFAULT now(),
  expires_at    timestamptz NOT NULL
);

The fingerprint column holds a hash of the canonical request, not the model's text, so a re-plan with cosmetic differences still maps to a clear rejection rather than a mystery.

Agents that re-plan need to know which operations already happened. A decision log, the running record of what was chosen and why, is the natural place, as long as the idempotency key is one of its fields. Addy Osmani's automated decision log pattern asks the assistant to keep a file recording what, why, and how, then verify it (Osmani). For an agent doing side effects, "what" should include the derived key.

A practical entry:

- operation: refund.create
- key: 9f2c...  (sha256 of tenant:refund.create:order_8812:v2)
- result: 201, refund_id rf_5521
- retried: yes, replayed from store

This closes a gap that outcome-only evaluation misses. The log analysis paper from Princeton and collaborators argues that benchmark scores hide how an agent behaved, and that logs are needed to see shortcuts and deployment failure modes that a pass or fail bit conceals. A duplicated refund that returns 200 looks identical to a single refund in an outcome metric. In the log, the second retried: yes, replayed line is the difference.

The same discipline shows up in config-driven systems: OPA's decision logs attach a decision_id and a trace_id to every policy decision so that each result can be traced and replayed (Open Policy Agent). Treat your derived key as that identifier for side effects.

One caution: the log is a record, not the source of truth. A pending entry means the operation may or may not have landed, and the server's key table, not the log, decides what happens next.

Two properties need separate tests.

Collision testing checks that distinct operations never share a key. Generate a corpus of realistic triples, derive keys, and assert uniqueness. Include adversarial cases: values containing the separator, values differing only by whitespace or Unicode form, and empty strings. A property test is cheap here:

import hypothesis.strategies as st
from hypothesis import given

@given(st.lists(st.text(), min_size=3, max_size=3, unique=True))
def test_distinct_ops_differ(parts):
    keys = {derive_key(*parts) for parts in permutations(parts)}
    assert len(keys) == 6

Replay testing checks that the same operation produces one side effect. Run the agent against a sandboxed tool, then force a retry by dropping the response and re-invoking the tool with the same key. Assert one charge, one refund, one shipment. Braintrust's guide to multi-agent testing makes the same point about shared state: start from a known state, reset between trials, and turn each requirement into a separate scorer so a polished response cannot hide a skipped or repeated action.

Three test cases catch the majority of real bugs:

The third is the hard one and the one most teams skip. It is also where deriving from business ids pays off, because a deterministic key can be recomputed from the record alone, with no session memory and no model call.

For the broader question of which HTTP methods are already idempotent and which need keys, the REST API primer is a good refresher: GET, PUT, and DELETE are idempotent, POST and PATCH are not and need the header.

The derivation itself is perhaps forty lines of code. The parts that take time are the key table, the locking, the retention policy, and the tests that simulate a crash. If you are wiring an agent to several model providers and want the retry path to be the same regardless of which model answered, Quanta Inference puts text, image, video, audio and embedding models behind one OpenAI-compatible API with prepaid US-dollar pricing, which keeps the key derivation independent of the transport. When the design questions are bigger than the header, a free 30-minute discovery call helps scope the side-effect boundaries before any code is written: Quanta Consulting.