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.tgz

Make 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;
    }
  },
});
  • guard asks, 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 throw NotApprovedError.
  • 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, guard still throws, because the action did happen. The refunded flag makes the tool say so, so the model never asks for a second refund.
  • timeoutMs withdraws 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, guard throws ChangedApprovalError, a kind of NotApprovedError, and does nothing. To act on the changed version, pass { acceptChanges: true } and use the approved_amount and approved_summary the function receives.
  • A rule such as “always allow payment.refund up 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.