Once.
VERCEL AI SDK / SAFE TOOL EXECUTION

Make consequential Vercel AI SDK tool calls safe to retry.

AI SDK tools can trigger refunds, payments, bookings and other external writes. If the action succeeds but the response is lost, blindly running the tool again can repeat the real-world side effect.

Short answer: Give each logical operation a stable identity and route supported consequential execution through durable state and provider reconciliation instead of treating every tool invocation as a new operation.

The duplicate-tool-call failure

  1. The model invokes a consequential AI SDK tool.
  2. The external provider performs the action.
  3. The response is lost or times out.
  4. The application cannot prove whether the action happened.
  5. The tool is invoked again.
  6. A blind retry can duplicate the side effect.

The Once pattern

const operationId = Once.id("refund", orderId);

await once.execute({
  operationId,
  provider,
  action: {
    type: "refund",
    order_id: orderId
  }
});

The same logical refund receives the same operation ID on every retry. Another tool invocation is therefore not automatically treated as permission to perform a new external action.

Vercel AI SDK example

The Once repository includes a working JavaScript example using the Vercel AI SDK tool pattern with @once-agent/sdk.

View the Once + Vercel AI SDK example on GitHub

Claim boundary: Once does not claim universal exactly-once execution. Safety depends on stable operation identity, durable Once state, the provider integration and sufficiently authoritative provider truth. When the outcome cannot be established safely, Once can preserve uncertainty instead of blindly repeating the action.

Add execution safety to AI SDK tools

npm install @once-agent/sdk

Try the Once tester · SDK package · Vercel AI SDK example