Vercel AI SDK security guide

How do you secure Vercel AI SDK?

To secure a Vercel AI SDK application, screen text before generation, wrap authored tools with guardTool, and pass conversation context through aiToolsContext. Use guardAction for application-invoked work. Authorize resources with trusted caller identity; a clean prompt or a model-selected tool does not grant permission.

Use this guide on the Vercel AI SDK 7 (ai >=7 <8, @ai-sdk/provider-utils >=5 <6). AI SDK 7 requires Node.js 22 or later and ESM-only imports – CommonJS require() doesn't work.

The Vercel AI SDK is a toolkit for calling models and defining tools in TypeScript. When you call generateText or streamText, the model may invoke tool({ execute }) handlers you registered – send email, charge a card, call an internal API. User prompts, RAG chunks, and tool outputs can all contain text that tries to steer those calls. That is prompt injection.

Arcjet Guard is a runtime policy layer for AI agents. You define rules – prompt-injection detectors, rate limits, PII checks, allowlists – and Guard allows or denies inbound text and tool calls before side effects run. The following examples use Guard for both controls. They wrap AI SDK tool({ execute }) handlers only – not Mastra createTool, Eve defineTool, LangGraph tool(), or other frameworks' tool types.

Use this checklist to review your application:

• Patch and lock dependencies. Stay on AI SDK 7 and Node 22+.
• Keep API keys off the client and out of NEXT_PUBLIC_ variables.
• Screen user text before generateText / streamText.
• Wrap model-invoked tools before execute runs. Correlate the run.
• Don't declare contextSchema on a tool that an action gate wraps.
• Gate app-invoked work separately from model-invoked tools.
• Validate arguments. Scan free-text notes, not opaque IDs.
• Catch issues in the editor and in CI before they ship.

For a shorter wiring recipe, see How do I secure a Vercel AI SDK agent?. For the Guard helpers used in the examples, see the Vercel AI SDK agent guard. Prompt injection protection for LangChain, LlamaIndex, and Vercel AI SDK only places detectors on the route and the retriever – a clean inbound score still isn't authorization for sendEmail.

How do you keep Vercel AI SDK dependencies safe?

Apply patches on a schedule you actually keep, and out of band for a critical advisory. Commit a lockfile so every environment installs the same graph, and turn on Dependabot, Renovate, or an equivalent bot for npm. Run npm audit (or your package manager's audit) in CI and fail on known high-severity issues you haven't waived.

Pin ai and every @ai-sdk/* package together so a provider major can't drift under the core SDK. AI SDK 7 is ESM-only: set "type": "module" or use .mjs, and don't load it through CommonJS require().

Node.js 18 and 20 are unsupported – Node 20 reached end-of-life on 2026-04-30. Node 22 is Maintenance LTS until 2027-04-30; prefer Node 24 LTS for production. Node 26 is Current, not LTS. Put the floor you choose in engines.node so installs fail loudly on an unsupported runtime.

Treat added provider packages as review events: they often gain network or filesystem access. Prefer a short function that you maintain over a trivial one-liner package. See trivial packages.

How do you manage Vercel AI SDK secrets?

Model and gateway keys such as OPENAI_API_KEY and AI_GATEWAY_API_KEY belong on the server, loaded at process start. In a Next.js app, anything named NEXT_PUBLIC_* is inlined into the client bundle – anyone can read it – so never put a signing key or other server secret there. See the Next.js security checklist if the agent lives in a Next.js route.

Don't log tool arguments or the raw prompt. A support dump that includes the last user message is a leak. Prefer a secrets manager in production, and redact before records leave the process. See storing secrets in environment variables and redacting sensitive data from logs.

How do you screen inbound Vercel AI SDK text?

The AI SDK doesn't expose a first-class inbound hook, so screen in your route handler, job, or webhook before you call generateText or streamText. That is where a user prompt or retrieved chunk is still plain text – not yet part of the model's context.

With Guard, call arcjet.guard() with prompt-injection rules on that string. Launch the client once at module scope. Create one createAgentContext at the HTTP route, job, or webhook that starts the run – don't stash it in module state or AsyncLocalStorage. Direct guard() fails open: an ALLOW isn't proof the rules ran, so gate on decision.hasFailedOpen() when this call site must fail closed. On deny, don't start generation.

1
import { detectPromptInjection } from "@arcjet/guard";
2
import { createAgentContext } from "@arcjet/guard/vercel-ai/v7";
3
import { arcjet } from "./arcjet.js";
4

5
const context = createAgentContext({ correlationId: conversationId });
6
const inbound = detectPromptInjection();
7

8
const decision = await arcjet.guard({
9
  label: "message.received",
10
  rules: [inbound(prompt)],
11
  correlationId: context.correlationId,
12
});
13

14
if (decision.conclusion === "DENY" || decision.hasFailedOpen()) {
15
  throw new Error("message blocked");
16
}

A caller-supplied correlationId must be 1-256 characters of printable ASCII. Prefer a conversation ID, request ID, or ticket ID over a generated value.

How do you gate Vercel AI SDK tools and actions?

After inbound screening, side effects happen when the model calls a tool – or when your application performs a risky step on its own. Guard's AI SDK helpers cover three callers:

• guardTool() for model-invoked work. The LLM decided to call the tool.
• guardAction() for app-invoked work. Your code performs the risky step.
• captureAction() for observe-only records. No decision.

The wrapped tool must have execute – a tool with none has nothing to wrap. It also can't already declare contextSchema, because Guard uses that slot and throws if the tool already owns it.

On deny the email provider never runs and the model receives an ArcjetDenialResult. Don't throw from guardTool: a throw becomes a generic tool error and drops the fields. guardAction throws so application code can catch – ArcjetDeniedError on a deny, ArcjetGuardUnavailableError when the policy could not be evaluated.

1
import { launchArcjet, policyInput, tokenBucket } from "@arcjet/guard";
2
import {
3
  aiToolsContext,
4
  createAgentContext,
5
  guardTool,
6
} from "@arcjet/guard/vercel-ai/v7";
7
import { generateText, tool } from "ai";
8
import { z } from "zod";
9

10
const arcjet = launchArcjet({ key: process.env.ARCJET_KEY! });
11
const emailLimit = tokenBucket({
12
  bucket: "email",
13
  refillRate: 5,
14
  intervalSeconds: 60,
15
  maxTokens: 5,
16
});
17

18
export async function runAgent(
19
  user: { id: string; allowedRecipients: string[] },
20
  prompt: string,
21
  conversationId: string,
22
) {
23
  const sendEmail = guardTool(
24
    arcjet,
25
    tool({
26
      description: "Send an email",
27
      inputSchema: z.object({
28
        recipient: z.string().email(),
29
        body: z.string(),
30
      }),
31
      execute: ({ recipient, body }) =>
32
        emailProvider.send({ to: recipient, body }),
33
    }),
34
    {
35
      action: "email.sent",
36
      actor: user.id,
37
      rules: () => [emailLimit({ key: user.id, requested: 1 })],
38
      inputs: ({ recipient, body }) => ({
39
        recipient: policyInput.server.string(recipient),
40
        allowed_recipients: policyInput.server.stringList(
41
          user.allowedRecipients,
42
        ),
43
        body: policyInput.local.string(body),
44
      }),
45
    },
46
  );
47

48
  const tools = { sendEmail };
49
  const context = createAgentContext({ correlationId: conversationId });
50

51
  return generateText({
52
    model: "openai/gpt-4o-mini",
53
    prompt,
54
    tools,
55
    toolsContext: aiToolsContext(context, tools),
56
  });
57
}

Derive actor from an authenticated server-side identity. A policy can be conditioned on the actor, so an actor taken from model-produced tool input lets whoever controls the prompt escape their own policy scope.

If you omit toolsContext, Guard still runs but the call is uncorrelated. The first such call always warns. Omitting rules still makes the guard call so a remote policy can apply.

AI SDK 7 human-approval primitives aren't a remote policy. See human approval is not a security policy.

How do the editor and CI catch Vercel AI SDK security bugs?

Turn on TypeScript strict, ESLint, and secret scanning in the editor. Trunk, Semgrep, TruffleHog, and Gitleaks all have editor plugins and CI jobs. Run the same scanners in CI that you run locally – an editor warning that isn't a CI failure will be ignored.

Fail the build on secrets in the diff, on known vulnerable dependencies, and on CommonJS require("ai") if your repo is ESM-only. None of these replace a review of which tools have execute and which ones you actually wrapped. They catch the mistakes that are cheap to find automatically.

How do you verify enforcement before deployment?

Use deterministic Guard responses and a handler call counter. A DENY or unavailable evaluation must leave the counter at zero; an authorized ALLOW must call the handler once. Also test another tenant's resource identifier: application authorization must still refuse access even when Guard allows.

Test the wrapped execute directly and through a model run, then exercise application-invoked work guarded with guardAction. Confirm the published policy consuming allowed_recipients is active: supplying typed inputs alone does not enforce an allowlist. Reuse the conversation ID across turns while retaining the authenticated user as the actor.

What do you do after this guide?

Confirm each item against one sensitive route: a prompt that asks to email finance, an authored sendEmail that you wrapped, and an app-invoked GitHub review that uses guardAction. Then apply the Next.js security checklist if the route is a Next.js handler, and AI agent runtime security for sequence, budget, and identity controls.