ai-sdk-7

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: node_modules/ai/docs/ and node_modules/ai/src/.
4. In monorepos, check app/package workspaces such as apps/*/node_modules/ai/ and packages/*/node_modules/ai/.
5. 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

Task	Prefer in AI SDK 7
Text generation	generateText / streamText
System prompt	top-level instructions, not system
Structured output	output: Output.object(...) on text functions
Loop limit	stopWhen: isStepCount(n)
Shared server state	runtimeContext
Per-tool state/secrets	tool contextSchema + toolsContext
Sensitive tools	toolApproval on generateText, streamText, or ToolLoopAgent
Durable long-running agents	WorkflowAgent from @ai-sdk/workflow
Running Claude Code/Codex/Pi	HarnessAgent from @ai-sdk/harness/agent
Observability	registerTelemetry(new OpenTelemetry())
Stalled calls	timeout number or object

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 - ToolLoopAgent, WorkflowAgent, context, approvals.
• harnesses.md - HarnessAgent, sessions, adapters, sandboxing, UI.
• core-functions.md - generateText, streamText, output, result shape.
• tools.md - tools, context, approvals, MCP Apps, sandbox handles.
• ui-hooks.md - useChat, typed tool parts, approvals, harness/workflow UI.
• migration-v6-to-v7.md - codemod and breaking-change checklist.
• telemetry.md - OpenTelemetry, tracing channel, lifecycle telemetry.
• media-and-files.md - uploadFile, uploadSkill, realtime, video.
• 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.