agentsop-llm-tool-idempotency

What it does

Decision protocol to ensure side-effectful agent tools are idempotent when an LLM tool call is retried. It prescribes mechanisms so a second call is a no-op, focusing on idempotency keys, dedup tables, content-addressed writes, and saga-based compensation. Targets engineers wiring tools whose actions include emails, payments, DB writes, and API calls. Triggers include tool names with send_, create_, charge_, post_, write_, publish_, transfer_, delete_, update_, or notify_, as well as retries via various layers. It outlines a taxonomy of idempotency strategies (OP-1 to OP-5) and operational steps for classifying, selecting mechanisms, key generation, propagation through layers, conflict handling, and dedup record persistence. It also details how to expose a replay indicator was_replay in results.

How it works

Activation rules specify when to apply the protocol (e.g., idempotency-key capable APIs, internal writes, compensatable operations). Core mental model contrasts: LM at-least-once vs tool at-most-once, using an idempotency key generated by the agent and persisted before the tool call. The protocol describes four retry sources and the idempotency key guidance: origin in agent state, persistence before call, and reuse on resume. It presents three practical mechanisms: OP-1 Idempotency-key HTTP header (Stripe pattern), OP-2 Dedup table at tool-call layer, OP-3 Content-addressed write, OP-4 Database INSERT … ON CONFLICT DO NOTHING, OP-5 Saga/compensation for non-idempotent external calls. Step-by-step guidance covers classification, mechanism choice, key naming, key propagation, conflict responses, and recording was_replay in results. It also includes concrete action templates for each pattern (e.g., HTTP headers, dedup table schema, content-addressed write, and SQL constructs).

When to use it

Use when any tool performs a side effect (send_email, create_record, charge_card, post_message, write_file, publish_event, transfer_funds) or when a LangGraph node with an interrupt and side effect may resume, or when a transport timeout or model duplicate emission could trigger a retry. It also applies when a server or client layer may re-invoke tools after timeouts or retries. Do not activate for read-only tools or when the side effect is inherently commutative and safe under duplication.

What it can touch

Tool wrappers and state management must store and propagate the idempotency key through: agent state, tool wrapper, HTTP client, and external API. It prescribes using headers like Idempotency-Key and maintaining state-persisted keys before the call. It covers including the key in retries and caching responses server-side (TTL specifics referenced for Stripe).

Caveats

References Stripe idempotency patterns and related patterns in AWS and databases; notes that same key with same args may return cached response, while same key with different args indicates a caller bug. It emphasizes persisting dedup records atomically with commits in transactional patterns and warns about potential conflicts if keys collide or if key generation is not persisted before the call. License: MIT (from frontmatter).