Integration guides2 min read
Human Approval for Vercel AI SDK Tools, Even When Nobody Is in the Chat
AI SDK 7 can pause a tool for approval inside a chat. Agents that run on a schedule or in a queue have no chat. Here is a tool that waits for a person anyway.
AI SDK 7 moved tool approval from the tool to the call: you set toolApproval on generateText, streamText or an agent, and the result comes back with approval requests for your UI to answer. That is the right design when a person is sitting in the chat. It does nothing for the agent that runs from a cron job at 3 a.m., works through a queue, or reviews pull requests in CI. Nobody is there to click approve.
For those agents the approval has to travel to where the person is, and the tool has to wait for the answer. That is what the Vibez.now request API is for: the tool submits what it wants to do, the request appears on your Requests page and your phone, and the tool carries on only once you approve.
The tool
This is a complete script. askHuman submits a request, then polls its status every few seconds, backing off to thirty. The tool calls it before running anything. Install ai and zod, set VIBEZ_API_KEY (from Settings in Vibez.now) and AI_GATEWAY_API_KEY, and run it with tsx.
// An AI SDK tool that waits for your approval on Vibez.now before it runs.
//
// npm i ai zod
// VIBEZ_API_KEY=… AI_GATEWAY_API_KEY=… npx tsx examples/ai-sdk/approved-shell-tool.ts
//
// Written for AI SDK 7. Its own `toolApproval` option suits a person sitting
// in the chat; this is for when they aren't — the request reaches the Vibez.now
// Requests page and phone, and the tool waits. Anything but an approval, a
// network error included, means the command does not run.
import { exec } from "node:child_process";
import { promisify } from "node:util";
import { generateText, stepCountIs, tool } from "ai";
import { z } from "zod";
const API = process.env.VIBEZ_API_URL ?? "https://vibez.now/api";
const sh = promisify(exec);
const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
async function call(path: string, init: RequestInit = {}): Promise<Record<string, unknown>> {
const res = await fetch(`${API}${path}`, {
...init,
headers: {
"Content-Type": "application/json",
"x-api-key": process.env.VIBEZ_API_KEY ?? "",
...init.headers,
},
});
if (res.status === 429) {
// Over 60 calls a minute: wait as long as the server says.
await sleep(Number(res.headers.get("retry-after") ?? 10) * 1000);
return call(path, init);
}
if (!res.ok) throw new Error(`${path}: ${res.status}`);
return res.json();
}
/** True only if a person approved within `minutes`. */
export async function askHuman(title: string, detail: string, minutes = 30): Promise<boolean> {
try {
const created = await call("/submit-request", {
method: "POST",
body: JSON.stringify({
title: title.slice(0, 255),
code_snippet: detail,
source: "ai-sdk-agent",
expires_in_minutes: minutes,
}),
headers: { "x-idempotency-key": `ai-sdk:${detail}:${Math.floor(Date.now() / 60_000)}` },
});
// An auto-approve rule can approve the request as it is created.
let status = created.status;
const deadline = Date.now() + minutes * 60_000;
for (let delay = 3_000; status === "pending" && Date.now() < deadline; ) {
await sleep(delay);
delay = Math.min(delay * 1.5, 30_000);
({ status } = await call(`/check-status?request_id=${created.request_id}`));
}
return status === "approved";
} catch {
return false;
}
}
export const runCommand = tool({
description: "Run a shell command. A person approves every command before it runs.",
inputSchema: z.object({ command: z.string().describe("The shell command to run") }),
execute: async ({ command }) => {
if (!(await askHuman(`Run: ${command.slice(0, 80)}`, command))) {
return `Not approved: "${command}" was not run.`;
}
const { stdout, stderr } = await sh(command);
return { stdout, stderr };
},
});
const { text } = await generateText({
model: "anthropic/claude-sonnet-5-5",
tools: { runCommand },
stopWhen: stepCountIs(5),
prompt: "How much disk space is free here?",
});
console.log(text);
Why it fails closed
An approval gate is only as good as its worst failure. If the network drops, the key is wrong, or the API answers with an error, askHuman returns false and the command does not run. The same goes for a request nobody answers: it expires after the window you set and comes back rejected. Only an explicit approval returns true.
- Approved: the tool runs the command and returns its output to the model.
- Rejected, or expired unanswered: the tool returns a sentence saying it was not run, so the model can explain or try something else.
- Any error: treated as not approved.
When every command asks, nobody reads them
Gate a busy agent's every command and you will be approving ls and git status forty times an hour, which trains you to approve without reading. Auto-approve rules in Settings approve matching requests as they are created, and the submit call returns status approved straight away, which this tool already handles. Keep the gate for the commands that change something.
Is needsApproval still the way to require approval in AI SDK 7?
It still exists on tool() but is deprecated. AI SDK 7 sets approval with toolApproval on generateText, streamText or an agent, and returns approval requests for your UI to answer.
What happens if nobody answers?
The request expires after expires_in_minutes and comes back rejected, so the tool returns without running the command.
How do I stop approving harmless commands?
Add an auto-approve rule in Vibez.now Settings for the agent or source. Matching requests are approved as they are created, and the submit call returns status approved, which the tool treats as an approval.