Crabhaus

What it is

An operation is idempotent when running it twice leaves the world in the same state as running it once. For agents that act on the world - payments, emails, database writes - idempotency turns a retry from a hazard into a safe recovery move: the action takes effect once no matter how many times the step runs.

How it works

Idempotency keys: each logical action carries a unique key; the server stores the outcome and replays it on a duplicate instead of re-executing. Effect records: the agent checks a ledger of completed effects before acting and records completion after. Replay-safe tools declare target state - 'set status to shipped' - rather than relative mutations like 'increment', so re-runs converge.

A concrete example

A client charges a card via Stripe with an Idempotency-Key header. The request times out and the client retries with the same key; Stripe recognises it and returns the original result - one charge, not two. The same pattern protects an agent that crashes after paying but before recording it: the resumed retry is harmless.

Why it matters

Retries are everywhere in agent stacks: flaky networks, crashed runs, durable-execution replays that re-run steps after a restart. Without idempotent effects the most natural recovery move - try again - is the most dangerous one: duplicate charges, repeated emails, corrupted state. At-least-once delivery plus idempotent handlers is how real systems get exactly-once outcomes.