Agent tool call idempotency ensures that repeated attempts with the same business intent produce one accepted effect. It protects payments, tickets, messages and configuration changes when a model repeats itself, a client retries after timeout, a worker resumes from a checkpoint or a network response disappears. The aim is not exactly-once packet delivery. It is a business system that recognizes duplicate intent, returns the original outcome and exposes uncertainty for reconciliation.
Permission answers whether an action may occur; idempotency answers whether this intended action has already occurred. Production agents need both. Edilec's agent tool permissions guide covers bounded authority, and the agent control plan covers approval and audit. This guide focuses on the execution contract after an action is authorized.
Define agent tool call idempotency at the business-effect boundary
Choose the effect that must occur once: one payment for an invoice, one support case for an incident, one email campaign enrollment or one desired configuration revision. An HTTP request is too low-level; several requests may legitimately implement one effect. Conversely, two requests with similar text may represent distinct user intentions. The domain service that owns the record should enforce the uniqueness rule because it can evaluate authoritative identifiers and state.
Classify tools as read-only, naturally idempotent, idempotency-key protected, compensatable or non-repeatable. A set_status(closed) operation may be naturally idempotent in final state but still emit duplicate notifications unless downstream events are deduplicated. A payment create is not naturally idempotent. A “send message” call may be impossible to undo. Publish the classification and retry policy in the tool catalog.
Create stable idempotency keys from intent
Generate the key before dispatch and persist it with the workflow. It should identify the tenant, tool contract, business operation and intent instance, using an opaque random identifier or a keyed digest of stable fields. Do not ask the model to invent it on each attempt. Retries and resumed workers reuse the same key; a genuinely new user intent receives a new key even if arguments match.
Bind the key to a canonical request digest. If the same key arrives with a different amount, destination or operation, reject it as a conflict rather than replaying the old result or executing the new request. Define retention from the maximum retry and reconciliation window plus business obligations. Scope uniqueness by tenant and operation so unrelated customers cannot collide or infer one another's activity.
| Key component | Example role | Design rule |
|---|---|---|
| Tenant | Customer or business unit | Enforce isolation in uniqueness constraint |
| Operation | invoice.pay version 2 | Prevent reuse across different effects |
| Intent ID | Workflow-generated opaque value | Create once before first dispatch |
| Request digest | Canonical consequential fields | Reject changed payload under same key |
| Retention class | Payment or notification policy | Outlive every valid retry window |
Use an authoritative tool execution ledger
The executor stores idempotency key, request digest, principal chain, approval reference, state, attempt metadata, downstream identifier and result. Insert the record under a unique constraint before causing the effect. States commonly include accepted, executing, succeeded, failed-retryable, failed-final and outcome-unknown. A duplicate request reads the existing record and returns its status instead of starting another action.
Keep this ledger near the authoritative effect, not solely in the agent runtime. The agent can crash or be retried by another platform. If the effect spans a local database and an external service, use a transactional outbox or durable command record: commit intent atomically, dispatch asynchronously and reconcile the external result. Never hold a database transaction open across a model call or human approval.
Reconcile ambiguous outcomes before retrying
A timeout, closed socket or lost response creates uncertainty, not proof of failure. Transition the ledger to outcome-unknown and query the downstream system by idempotency key, merchant reference, ticket correlation ID or desired-state version. If the downstream accepted the effect, record success and return the original result. If it definitively did not, retry under the same key. If neither can be proven, escalate to an owned reconciliation queue.
Design the downstream correlation path before enabling the tool. A payment provider may support an idempotency key; a legacy system may require a unique business reference and lookup endpoint. If no reliable query exists, reduce retry automation and require human review for uncertainty. A compensation such as refund or ticket closure is a new effect with a new authorization and key, not evidence that the original call never happened.
Publish retry semantics in the tool contract
The MCP tools specification defines tool discovery, typed input and results, but business idempotency remains an implementation responsibility. Add fields or catalog metadata that state whether an idempotency key is required, the uniqueness scope, result retrieval behavior, cancellation support and possible outcome-unknown status. Return structured business identifiers and ledger state, not only prose.
Separate transport errors from business failures. invalidaccount is final until input changes; providerunavailable may be retryable; outcomeunknown requires reconciliation; duplicateconflict means the same key carried a changed payload. The model may explain these states to a user, but deterministic runtime policy decides retry, wait or escalation. The OpenAI Agents SDK results guide shows how run results and generated items can be carried forward; retain the operation key outside model-generated content.
Bind approval and idempotency to one intent
An approval record should include the idempotency key and canonical request digest. After approval, a worker can retry the approved effect under the same key without asking again, provided approval and material facts remain valid. If consequential fields change, create a new intent and approval. This prevents a model or caller from reusing approval for a different destination while preserving safe recovery from infrastructure failure.
Concurrency controls matter when duplicate user clicks, model branches or workers race. Use a unique constraint and compare-and-set transition so only one executor acquires the operation. Other attempts return the same record. Do not solve races with prompt instructions such as “call once.” The control belongs in durable code under the record owner's authority.
Carry idempotency across agent and task boundaries
An A2A task ID identifies collaborative work, but one task may contain several business actions, and a retried message may refer to the same task. The A2A specification includes durable task operations and requires idempotent behavior for specific operations such as repeated deletion of a push configuration. Application effects still need their own intent identifiers. Propagate parent task and action key together without assuming they are interchangeable.
When one agent delegates to another, the receiving executor becomes authoritative for its action ledger. The caller stores the returned action ID and queries status after interruption. Gateways and adapters must preserve idempotency keys end to end; generating a fresh downstream key on every retry defeats the contract. Trace the full chain so operators can reconcile task, tool call and business record.
| Failure injection | Expected behavior | Pass evidence |
|---|---|---|
| Same key, same payload concurrently | One execution, shared result | Single ledger row and business record |
| Same key, changed amount | Reject conflict | No second effect |
| Response lost after success | Reconcile downstream and return original outcome | Stable external reference |
| Worker crashes before dispatch | New worker claims accepted record | One dispatch attempt at a time |
| Worker crashes after dispatch | Enter unknown state and query | No blind repeat |
Test and operate the duplicate paths
Automate concurrent retries, delayed responses, duplicate events, worker termination and ledger failover. Verify downstream notifications and analytics are also deduplicated or intentionally repeatable. Use property tests for canonical request hashing and tenant scoping. NIST's Secure Software Development Framework supports integrating secure practices and evidence into the development lifecycle; treat retry and recovery code as production-critical software, not middleware configuration.
Monitor duplicate-hit rate, key conflicts, unknown-outcome age, reconciliation success, retry attempts and compensation frequency by tool. A sudden rise may indicate a network regression, caller bug or model loop. Give operators a console that shows safe status and permitted actions without allowing them to overwrite ledger history. Apply the audit log design guide so investigations can join retries to principals and outcomes. Periodically verify retention covers actual delayed retries and that expired keys cannot recreate regulated effects unexpectedly.
Key takeaways
- Define one business intent and effect before selecting an idempotency mechanism.
- Generate and persist keys in the runtime; never rely on the model to repeat them correctly.
- Enforce a request digest and unique ledger record at the authoritative executor.
- Treat timeouts as unknown outcomes and reconcile before any repeat dispatch.
- Carry one action key through approvals, gateways, agents and downstream systems.
Frequently asked questions
Are read-only tool calls always safe to retry?
Not always. A nominal read may consume quota, mark a message read, trigger billing or return time-sensitive data. Document observable effects and consistency. Pure reads can usually retry with backoff, while reads with hidden effects need an explicit contract.
Can a database unique constraint provide idempotency?
It is an excellent atomic foundation, but the record must also bind the request digest, state and result. External effects require dispatch and reconciliation. A uniqueness error alone does not tell the caller whether prior work succeeded or remains in progress.
When can an idempotency key expire?
After all valid retries, delayed events, resumptions and investigations are impossible under policy. Consequential domains may retain a compact business reference longer than request details. Document expiry so a late retry cannot silently become a new effect.
Conclusion
Agent tool call idempotency converts repeated attempts from a business hazard into a status lookup. The runtime creates one intent, the executor records one authoritative operation, the downstream system correlates one effect and every retry returns to that shared history. Permissions limit who may act; the ledger limits how many times that intent can act.
Start with the highest-consequence tool and deliberately lose its response after success. If the system can identify the effect, return the original outcome and avoid a second action, the core contract works. Extend that pattern through approval, delegation and recovery before trusting autonomous retries at scale.