Vercel AI SDK
Make a Vercel AI SDK tool ask a person before it acts, with the TypeScript client, in generateText, streamText or a background job.
In the Vercel AI SDK a model acts through tools, and a tool acts in its execute function. Ask a person at the top of execute, and the refund, email or deploy cannot happen without their yes. It works the same with generateText, streamText and an agent class, in a route handler, a queue worker or a cron job. A person may take minutes to answer, so give the wait a limit that fits inside your function’s time limit, or let a webhook wake the agent.
1. Install the client
npm install https://variantgate.com/sdk/variantgate-agent-latest.tgzMake an agent key under Agents and put it in VARIANTGATE_KEY. One client per agent is enough:
import { ApprovalClient } from "@variantgate/agent";
export const approvals = new ApprovalClient({
agent: "support-agent",
apiUrl: "https://api.variantgate.com",
key: process.env.VARIANTGATE_KEY ?? "",
});2. Ask inside the tool
import { NotApprovedError } from "@variantgate/agent/errors";
import { tool } from "ai";
import { z } from "zod";
import { approvals } from "./approvals";
import { shop } from "./shop"; // your own refund code
const EUROS = /^\d+(\.\d{1,2})?$/;
export const refundOrder = tool({
description: "Refund an order to the customer's original payment method.",
inputSchema: z.object({
orderId: z.string(),
amountEur: z.string().regex(EUROS).describe("Euros, such as 25.00"),
}),
execute: async ({ orderId, amountEur }) => {
let refunded = false;
try {
return await approvals.guard(
{
action: "payment.refund",
summary: `Refund €${amountEur} for order ${orderId}`,
amount: amountEur,
currency: "EUR",
details: { order: orderId },
},
async () => {
await shop.refund(orderId, amountEur);
refunded = true;
return `Refunded €${amountEur} for order ${orderId}.`;
},
// Withdraw the request if nobody answers before the route times out.
{ timeoutMs: 50_000 }
);
} catch (error) {
if (refunded) {
// Only recording the outcome failed. Never let the model retry.
return `Refunded €${amountEur} for order ${orderId}.`;
}
if (error instanceof NotApprovedError) {
return `Not refunded. ${error.message}`;
}
throw error;
}
},
});guardasks, waits for the answer and runs the function only on a yes, then records whether it worked. Pending, denied, expired, withdrawn and a paused workspace all throwNotApprovedError.- On a no, return a sentence instead of throwing. The model reads it and can tell the customer, rather than retrying the call.
- If the refund went through but recording the outcome failed,
guardstill throws, because the action did happen. Therefundedflag makes the tool say so, so the model never asks for a second refund. timeoutMswithdraws the request when nobody answers in time, so a person cannot approve it after the agent has stopped waiting.- If a person lowers the amount or rewords the request,
guardthrowsChangedApprovalError, a kind ofNotApprovedError, and does nothing. To act on the changed version, pass{ acceptChanges: true }and use theapproved_amountandapproved_summarythe function receives. - A rule such as “always allow
payment.refundup to €20” lets small refunds through at once, while larger ones wait for a person.
3. Give the tool to the model
import { anthropic } from "@ai-sdk/anthropic";
import { generateText, stepCountIs } from "ai";
import { refundOrder } from "./tools";
const { text } = await generateText({
model: anthropic("claude-sonnet-5-5"),
tools: { refundOrder },
stopWhen: stepCountIs(5),
prompt: "Order 1182 arrived broken. Please refund it.",
});Any provider works; the approval lives in your tool, not in the model.
When the AI SDK’s own approval is enough
The AI SDK can also pause a tool call until the person in the chat approves it. That fits when the person chatting is the one who should decide. VariantGate fits when nobody has the chat open: the agent runs in the background, someone else must decide, a rule should answer the routine cases, or you need a record of who approved what. The two can be used together.
Waiting longer than a function may run
Ask without waiting, store the request id, and let a signed webhook wake the agent; then read the answer with check before acting. See the TypeScript client for every method.