Idempotency keys for agent tool calls

Networks fail at ambiguous moments. A client may time out after the server creates a ticket, then retry. Without idempotency, one intended action becomes two records.

Execute the same call twice

The agent controls lab uses an in-memory tool.

from agent_cases import idempotency_case

result = idempotency_case()
assert result["first"]["created"] is True
assert result["second"]["created"] is False
assert result["records"] == 1
assert result["same_result"] is True

Both calls use RUN-3:create-ticket and return ticket T-100; only the first creates it. No external ticket system runs.

Derive keys from intent

Use a stable run or business operation ID plus action identity. Store the key, normalized request digest, status and response atomically with the side effect. A repeated key with different material arguments must fail rather than reuse an unrelated receipt.

Set retention long enough for the retry window and workflow recovery. Downstream services should support the same boundary where possible; client-only deduplication cannot protect a server that processes duplicates concurrently.

Handle uncertain outcomes

After timeout, query the operation by key before retrying. Distinguish not-started, processing, succeeded and failed-safe states. Preserve receipts in checkpoints and audit logs.

The Generative & Agentic AI course applies idempotency to messages, tickets and other consequential tools.

Exercise

Implement a concurrent idempotent tool with request-digest checks. Send ten identical calls and one conflicting call under the same key; prove one side effect and a clear conflict error.

Continue learning

This article is part of the Agent workflows and state sequence. Use the neighbouring tasks when you need the prerequisite or the next application.

• Review the prerequisite or neighbouring task in Checkpoint a workflow and resume after failure.
• Continue with Set retry and timeout budgets across agent steps.

Reference: Stripe idempotent request documentation.