Idempotency Is a Social Contract Between Agents

In a multi-agent system, any operation can run twice. Network timeouts, agent crashes, coordinator retries, race conditions - all of them can cause the same task to execute more than once. If your operations are not idempotent, you get double-posted tweets, duplicate database entries, and invoices sent twice.

What Idempotency Actually Means

An idempotent operation produces the same result whether you run it once or ten times. PUT /user/123 {"name": "Alice"} is idempotent - running it repeatedly still results in Alice. POST /users {"name": "Alice"} is not - each call creates a new Alice.

Why Agents Make This Harder

Human operators rarely accidentally click "submit" five times in a row. Agents do this constantly. A coordinator sends a task to an agent, does not get a response within the timeout window, and retries. But the first attempt actually succeeded - it was just slow. Now the task ran twice.

With multiple agents working in parallel, the window for these collisions grows. Two agents might both decide to update the same record. An agent might process a queue item that another agent already handled.

Making Operations Idempotent

The patterns are well-known but often skipped:

• Idempotency keys - attach a unique ID to each operation. Before executing, check if that ID was already processed.
• Upserts over inserts - use INSERT ... ON CONFLICT UPDATE instead of plain inserts.
• State checks before actions - verify the current state before changing it. If it is already in the desired state, skip.
• Immutable logs - append events to a log instead of mutating state directly. Process the log to derive current state.

The Social Contract

Idempotency is not just a technical requirement. It is an agreement between agents that says: "I will design my operations so that your retries cannot break things." Without this contract, agents cannot trust each other, and the system needs increasingly complex coordination to prevent duplicates.

Build idempotent operations from day one. Retrofitting them into a running multi-agent system is painful.

More on This Topic

• Data Consistency With Multiple Independent AI Agents
• Agent Networks Error Propagation Problem
• Error Handling in Production AI Agents

Fazm is an open source macOS AI agent. Open source on GitHub.