Give every intended external action a stable identity and reuse that identity across retries. An AI agent may repeat a tool call after a timeout, resume from a checkpoint, or lose track of an earlier result. The receiving system should recognize the same intended action instead of performing it again.
This is idempotency at the business-action boundary. It is different from caching repeated read-only searches.
A timeout does not prove nothing happened
Imagine a refund tool sends a request, the payment provider creates the refund, and the response is lost. The agent sees a timeout. A fresh request with a new action identity may create another refund.
The correct recovery is to reconcile the original action or retry using the provider’s supported idempotency mechanism. Do not let the model decide that an ambiguous result means the operation is safe to repeat.
Stripe’s API documentation describes idempotency keys and version-specific retry behavior. Use the contract for the API version you integrate with; do not assume every provider retains keys indefinitely or handles errors the same way.
Model the action before calling the tool
Use a durable action record created by trusted application code. A proposed record looks like this:
{
"action_id": "act_8d2f",
"tenant_id": "tenant_a",
"operation": "refund",
"subject_id": "order_42",
"request_fingerprint": "server-computed-fingerprint",
"state": "pending",
"provider_reference": null
}This is a design example, not an SDK schema. The action identity must survive process restarts and graph resumes. A new random key on every retry defeats the mechanism. A key based only on the order ID can wrongly merge two separate, authorized partial refunds.
Define identity around the user’s intended operation, with authorization and parameters recorded separately. If parameters change, do not silently reuse an old successful result.
Handle concurrency and recovery
| Situation | Required behavior |
|---|---|
| Same action arrives twice simultaneously | Atomically claim or find one durable action record |
| Same key arrives with different parameters | Reject or explicitly reconcile the conflict |
| Provider completed, local update failed | Reconcile from the provider reference or key |
| Outcome is unknown | Keep an unknown/pending state; do not claim completion |
| User requests a genuinely new action | Create a new authorized action identity |
An in-memory set of completed IDs is insufficient for multiple workers or restarts. Use a transactional mechanism appropriate to your storage and the provider’s contract. A database record alone also does not create exactly-once behavior across an external API boundary; recovery still needs a reconciliation path.
Check agent resumes explicitly
A durable agent workflow can revisit code when resumed. Read your framework’s execution semantics and place nonrepeatable work behind a durable action boundary. LangGraph’s interrupt documentation explains that resumed execution can re-enter the interrupted node. Avoid relying on the assumption that every line before a pause ran only once.
Test a crash immediately before the external request, after provider acceptance, and before the local result is persisted. These are different recovery windows. Also test two workers receiving the same action concurrently.
Monitor effects, not only calls
Two calls can be harmless if both resolve to one authorized effect. One call can still produce the wrong effect if it targets the wrong customer. Record the logical action ID, attempt IDs, provider reference, and final business state.
A useful alert asks whether multiple effects exist for one intended action, or whether an unresolved action has aged beyond its expected window. A raw duplicate-call count is only a starting signal.
Use Agnost’s tool execution evidence to connect attempts to the conversation, while keeping authoritative action records in the owning application. Follow the false-success guide to ensure the assistant describes the reconciled state accurately. For read-only repetition, use the narrower duplicate-search approach.