Idempotent Tool Calls: Stop Agents From Double-Charging and Double-Sending
Retries are going to happen. A network call times out, the agent loop tries again, and the tool runs twice. If the tool charges a card or sends an email, you've just done it twice and told nobody. The fix is idempotency
Retries are going to happen. A network call times out, the agent loop tries again, and the tool runs twice. If the tool charges a card or sends an email, you've just done it twice and told nobody.
The fix is idempotency: the same request, run twice, has the effect of running once. This post builds a small version in Node.js with no dependencies. I ran the tests and they pass.
What goes wrong without it
Picture an agent that issues a refund. The call reaches the payment system, which processes it, but the response gets lost. The agent sees a timeout and retries, and the customer gets two refunds. Or the model itself decides to call the tool again because the result looked odd.
You can't fix this by asking the model to be careful. The protection has to live in the code that runs the tool.
I work on AI Hive's enterprise agent platform, and a retry that doubles a side effect is the incident I most want teams to design out before launch.
The approach
Give every action a key that identifies the request, not the attempt. The first call with that key runs the tool and stores the result. Any later call with the same key returns the stored result without running the tool again. If a second call arrives while the first is still running, it waits for the same result.
The key should come from what makes the request unique: the user, the tool and the arguments. Sort the argument names so the same request always produces the same key. Return the stored result with a flag that says it was a replay, so the model knows the action had already happened.
The code
const test = require("node:test");
const assert = require("node:assert");
const { createHash } = require("node:crypto");
function keyFor(user, tool, args) {
const canonical = JSON.stringify([user, tool, Object.keys(args).sort().map((k) => [k, args[k]])]);
return createHash("sha256").update(canonical).digest("hex");
}
// In production the Map becomes a database table with a unique index on the key.
const store = new Map();
async function once(key, fn) {
const hit = store.get(key);
if (hit) return hit.promise; // finished or still running: share the result
const promise = (async () => {
try {
return await fn();
} catch (err) {
store.delete(key); // a failure must stay retryable
throw err;
}
})();
store.set(key, { promise });
return promise;
}
test("same request twice runs the tool once", async () => {
store.clear();
let charges = 0;
const charge = async () => { charges += 1; return { id: "ch_1" }; };
const key = keyFor("u1", "charge_card", { amount: 20, order: "A1" });
const [a, b] = await Promise.all([once(key, charge), once(key, charge)]);
await once(key, charge);
assert.equal(charges, 1);
assert.deepStrictEqual(a, b);
});
test("different arguments get different keys", () => {
assert.notEqual(keyFor("u1", "charge_card", { amount: 20 }), keyFor("u1", "charge_card", { amount: 25 }));
assert.equal(keyFor("u1", "t", { a: 1, b: 2 }), keyFor("u1", "t", { b: 2, a: 1 }));
});
test("a failed call can be retried", async () => {
store.clear();
let n = 0;
const flaky = async () => { n += 1; if (n === 1) throw new Error("timeout"); return "ok"; };
const key = keyFor("u1", "send_email", { to: "[email protected]" });
await assert.rejects(once(key, flaky), /timeout/);
assert.equal(await once(key, flaky), "ok");
assert.equal(n, 2);
});
Run it with node --test idempotent.test.js. The first test fires the same request twice at once and checks the tool ran a single time. The second checks that different arguments get different keys. The third checks that a failed call isn't remembered, so a retry can succeed.
Details that bite in production
Use a durable store, not memory. In production, the Map becomes a table with a unique index on the key, so a restart doesn't forget what already happened. Put an expiry on the entries, long enough to cover your longest retry window, and keep the stored result for as long as a duplicate could plausibly arrive.
Don't store failures. If the tool threw an error, the next attempt should run for real. The exception is a failure that's final, such as a rejected payment, which you may want to remember.
Pass the key downstream when you can. Many payment and messaging services accept an idempotency key of their own. Send yours, so the guarantee holds even if your own store is down.
Which tools need it
Anything that writes or sends: charges, refunds, emails, ticket creation, record updates. Reads don't need it. If you're unsure, ask what happens if this runs twice. If the answer is a problem, protect it.
For a wider view of how agents connect to the systems behind these tools, see this guide on connecting AI agents to CRM and ERP systems.
Test the ugly case
Add a test that kills the process between running the tool and storing the result, then retries. That's the case the in-memory version can't survive, and it tells you whether your real store handles it. Run that test against a real database in a staging environment, killing the process at each step in turn.
What's the tool in your stack that would hurt most if it ran twice?
Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes β full credit and traffic to the original publisher.