Idempotent Tool Writes for AI Agents: Stop Duplicate Records
Design write tools so a retried AI agent action cannot create duplicate invoices, bookings or records. Keys, state checks and recovery steps for business teams.

An idempotent tool write is one that produces the same result no matter how many times the same request reaches it. For AI agents, this matters because timeouts, network retries and re-planning are normal, so a create-invoice or book-slot call can arrive twice. The fix is to give every write a stable operation key, record the outcome before answering, and make the agent check the target system before it tries again.
Key takeaways
- Every write tool should require an operation key that identifies the business intent, not the attempt.
- The tool should store the outcome of each key and return that same outcome to any repeated call.
- The agent should read the target system before any second attempt at a write it cannot confirm.
- Ambiguous results, such as a timeout after the request left, need a reconciliation path and a person when the amount or commitment is significant.
- Idempotency is a design property of the tool, so it belongs in the tool contract and the acceptance tests, not in a prompt.
Why retries create duplicates in agent workflows
A duplicate write rarely comes from one obvious mistake. It usually comes from a chain of reasonable steps. The model sends a request, the network drops the response, the orchestrator times out, and the agent, which never saw a confirmation, plans the action again. If the tool treats each call as new, the invoice is created twice, the room is booked twice, or the same customer record appears in two places.
Retries come from several layers at once. The language model may regenerate a tool call after a partial failure. The workflow runner may retry a step that did not report success. A webhook provider may redeliver an event it believes was not acknowledged. Each layer is doing what it was designed to do. The write tool is the only place where you can make the second arrival harmless.
This is why the question is not "will the agent retry?" but "what happens when it does?" Plan for repeated arrival as the normal case.
How do you give every write a stable operation key?
An operation key is an identifier that the caller sends with each write request. The tool uses it to decide whether it has already done this work. The key must stay the same across every retry of the same intent, and it must change when the intent changes.
The common mistake is generating a new random identifier on each attempt. That gives the tool no way to recognize a retry, so the protection disappears. A better approach derives the key from the business facts that define the action.
- Name the business object and the action, for example the customer, the order and the step "create invoice".
- Include the period or version that makes the intent unique, such as the billing date or the booking request identifier from the originating message.
- Build the key deterministically from those fields, so the agent or the workflow produces the same string on every retry.
- Reject any write that arrives without a key. A missing key is a design error, not a case to guess around.
- Keep keys in a format your team can read in logs, so an operator can see which intent a record came from.
Where the target system already supports idempotency keys, use them. Payment and billing providers often accept a key header and return the original response for repeated requests. Read the provider's documentation for how long keys are kept and what happens when the same key is sent with different parameters. Your own tool should still apply the same rule, because not every system you connect will offer this feature.
How should the tool store outcomes before it answers?
The tool needs a ledger. This is a small record, separate from the business system, that maps each operation key to its status and result. A typical record holds the key, the requested action, a status such as pending, succeeded or failed, the identifier created in the target system, and a timestamp.
The order of operations matters. The tool should write a pending record before it calls the target system. After the target confirms, it updates the record to succeeded and stores the returned identifier. When a repeated call arrives, the tool looks up the key first. If the status is succeeded, it returns the stored result without writing again. If the status is pending, it must not start a second write. It should either wait, reconcile against the target system, or report that the outcome is unknown.
Keep the ledger readable. Operators should be able to search it by business object and see every attempt, including the ones that failed. That history is what makes a duplicate investigation take minutes instead of days.
A ledger entry is a receipt for an intent. If the receipt exists, the work is not repeated.
Illustrative scenario: A small clinic lets an agent book follow-up appointments from a patient's message. The request times out after the booking system accepted it. The agent sees no confirmation and asks to book again. Because the key was built from the patient, the requested slot and the originating message, the second call finds the pending record, checks the booking system, finds the appointment, and returns it. No second appointment is created, and the agent reports the existing booking to the patient.
What should the agent check before a second attempt?
The tool protects against repeated writes, but the agent should also learn a habit: before it retries a write it cannot confirm, it reads the state of the target. This is read-before-write. It is cheap, and it catches cases the key does not, such as a person creating the same invoice by hand while the agent was working.
The check should compare specific fields, not just whether something similar exists. For an invoice, compare the customer, the amount, the issue date and the reference. For a booking, compare the resource, the time window and the requester. If an exact match exists, the agent treats the write as done. If a close but different record exists, the agent stops and asks a person, because a near match is a question, not an answer.
Give the agent a short checklist for this step:
- Search the target system by the operation key or by the business reference that the key was built from.
- Compare the fields that define the intent, not only the identifier.
- If an exact match exists, record the existing identifier in the ledger and report success.
- If nothing matches, retry once with the same key and then stop.
- If a similar record exists, escalate to a named person instead of writing.
The retry limit matters. An agent that loops on a failing write can produce many partial results even when each call is protected. A small, fixed number of attempts, followed by an alert, keeps the failure visible.
How should the tool contract make duplicates hard to ask for?
The tool's name, inputs and outputs shape how the agent uses it. A contract that is vague invites misuse. Name write tools for the business action, such as create invoice draft or request booking, not for a generic action like update record. Separate create from update, so the agent cannot accidentally create a second object when it meant to change the first.
Require the operation key in the input schema, and return the stored identifier and status in the output. The output should tell the agent clearly whether the write was new, already existed, or is still pending. An agent that receives an explicit already existed status is much less likely to treat a repeated result as a failure and try again.
Keep the input narrow. Every free-text field is a place where two calls with the same intent can differ by a space or a word, and then the key no longer matches. Where a value has a fixed set of options, use an enumeration. Where a value is a date or an amount, use a typed field and validate it before the write. Our guide on tool schemas for business agents covers naming and types in more detail.
Finally, decide which writes are allowed at all. A write tool that can create a payment or a refund should not be exposed to the same agent that drafts customer replies. Separate the permission from the mechanics, so that idempotency protects the writes you have chosen to allow.
What happens when the result is unknown?
Some failures leave the outcome unknown. The request may have reached the target system, or it may not have. Treat this state as its own case, with its own rule. Do not guess, and do not write again until the status is known.
The reconciliation path is straightforward. The tool marks the ledger record as unknown, schedules a check against the target system, and retries the lookup at intervals that respect the target's rate limits. If the record is found, the ledger is updated to succeeded. If the record is not found after the check window, the ledger is marked failed and the operation returns to the queue or to a person. For guidance on pacing these checks, see rate limit handling for agent tools.
Amounts, legal commitments and customer-facing messages deserve a person in the loop when the outcome is unknown. The agent can prepare the summary, including the key, the time of the attempt and the search it ran, so the person decides in one look instead of reconstructing the history.
If the connection itself fails, the problem is larger than one write. Pause the write tool, keep the ledger intact, and follow a recovery process before resuming. What an agent should do when a connection expires walks through that sequence.
How Be Human handles this in managed operations
Be Human treats idempotency as part of the first engagement, not as a patch after a duplicate appears. The first step defines the single write the agent needs, the operation key it will use, the ledger that records each intent, and the approval boundary for actions with financial or legal effect. Each of these is documented so the client's operations lead can read it and change it. Managed operations then keep the protection working over time: monitoring of pending and unknown ledger entries, periodic tests that send repeated calls to confirm they return the original result, and review whenever the target system's API or permissions change. The aim is that a retry is a routine event that the system absorbs, and that a person sees anything it cannot resolve on its own.
If you want to see which of your workflows has the highest exposure to repeated writes, take the free Be Human AI diagnostic to find the first task worth handing to an agent.
Frequently asked questions
Does an idempotency key stop every duplicate? No. It stops duplicates that come from repeated calls with the same intent. It does not stop two different people, or two different intents, from creating similar records. That is why the agent should also check the target system before acting on a near match, and why the key should be built from the business facts that define the action.
Should the agent generate the operation key or should the tool? The tool should accept the key and reject requests without one, while the workflow or the agent builds it from stable business fields. If the agent invents a random key on each attempt, the protection fails. A deterministic key derived from the originating record gives the same value on every retry, and the ledger can recognize it.
Is idempotency enough if the agent has permission to write? No. Idempotency protects against repeated writes, but it does not decide whether a write should happen at all. High-value or irreversible actions still need an approval boundary, a named person who can approve them, and a clear record of who authorized each step. Idempotency and approval are complementary controls.
How do I test idempotent writes before production? Send the same request several times in a test environment, including with a simulated timeout between the target's confirmation and the tool's response. Confirm that the target system holds one record, that the repeated calls return the original identifier, and that the ledger shows a single succeeded entry. Repeat the test whenever the tool, the target API or the permissions change.
Your next step
See where an AI agent fits in your company first.
Take the free Be Human AI diagnostic. A few questions about your work show which task to hand to an agent first, what it needs to know and where a person approves.
Be Human editorial guidance. Examples are illustrative unless explicitly attributed. Sources provide background; implementation choices depend on your workflow.


