Vercel AI SDK v7 Development Guide

Use this skill for AI SDK 7-specific implementation, migrations, and agent architecture. For AI SDK 6 projects, use ai-sdk-6. For unknown versions, use ai-sdk first to inspect node_modules/ai/package.json and local docs.

First Checks

1. Inspect package.json, lockfiles, and node_modules/ai/package.json.
2. Confirm the installed ai major version is 7 before applying this guide.
3. Search local docs first: nodemodules/ai/docs/ and nodemodules/ai/src/.
4. In monorepos, check app/package workspaces such as apps/*/node_modules/ai/

and packages/*/node_modules/ai/.

1. If local docs are missing or ambiguous, verify against ai-sdk.dev or the

Vercel AI repository docs source before coding.

AI SDK 7 requires Node.js >=22 and AI SDK packages are ESM-only. Convert require() imports to import syntax before chasing downstream type errors.

Install

Use the project's package manager and install only packages needed by the task:

bun add ai @ai-sdk/react
bun add @ai-sdk/openai # or the provider already used by the project

For durable agents, add @ai-sdk/workflow and workflow. For harness agents, add @ai-sdk/harness, one harness adapter, and a sandbox provider.

Core v7 Patterns

In examples, MODEL is a placeholder: resolve a current model via the project's provider package (e.g. anthropic('...')) or a gateway model string, following the model-ID guidance in the ai-sdk skill. Never hard-code a model ID from memory.

import { generateText, isStepCount, Output } from 'ai';
import { z } from 'zod';

const result = await generateText({
  model: __MODEL__,
  instructions: 'Answer concisely.',
  prompt: 'Classify this support ticket.',
  reasoning: 'high',
  stopWhen: isStepCount(3),
  timeout: { totalMs: 60_000, stepMs: 15_000 },
  output: Output.object({
    schema: z.object({
      priority: z.enum(['low', 'medium', 'high']),
      summary: z.string(),
    }),
  }),
});

console.log(result.output);

Documentation Routing

Read only the reference needed for the current task:

• [agents.md](references/agents.md) - ToolLoopAgent, WorkflowAgent, context, approvals.
• [harnesses.md](references/harnesses.md) - HarnessAgent, sessions, adapters, sandboxing, UI.
• [core-functions.md](references/core-functions.md) - generateText, streamText, output, result shape.
• [tools.md](references/tools.md) - tools, context, approvals, MCP Apps, sandbox handles.
• [ui-hooks.md](references/ui-hooks.md) - useChat, typed tool parts, approvals, harness/workflow UI.
• [migration-v6-to-v7.md](references/migration-v6-to-v7.md) - codemod and breaking-change checklist.
• [telemetry.md](references/telemetry.md) - OpenTelemetry, tracing channel, lifecycle telemetry.
• [media-and-files.md](references/media-and-files.md) - uploadFile, uploadSkill, realtime, video.
• [examples.md](references/examples.md) - how to fetch canonical examples from vercel/ai.

Gotchas

• Do not rely on memory for AI SDK APIs. Verify against local docs/source or

official docs before writing code.

• Harness packages are experimental. Keep adapter/package details easy to change

and re-check docs before adding long-lived abstractions.

• result.usage now aggregates all steps. Use result.finalStep.usage for

previous final-step-only behavior.

• For streamText, await result.finalStep before reading final-step-only

metadata.

• Harness sessions own conversation history. Persist resume state from

detach() or stop() instead of replaying the entire UI message history.

• WorkflowAgent is stream-first and durable; use ToolLoopAgent for simple

in-memory agents.

• toolApproval applies to AI SDK-executed tools. Provider-executed tools and

harness built-ins have separate approval/permission behavior.

• Always fetch or verify current model IDs from the project's config or provider

docs before hard-coding a model string.