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
- Inspect
package.json, lockfiles, and node_modules/ai/package.json.
- Confirm the installed
ai major version is 7 before applying this guide.
- Search local docs first:
node_modules/ai/docs/ and node_modules/ai/src/.
- In monorepos, check app/package workspaces such as
apps/*/node_modules/ai/
and packages/*/node_modules/ai/.
- 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.
1---2name: ai-sdk-73description: "Vercel AI SDK v7 development and migration. Use when building or upgrading AI SDK 7 apps, especially ToolLoopAgent, WorkflowAgent, HarnessAgent, Claude Code/Codex/Pi harnesses, runtimeContext, toolsContext, toolApproval, telemetry, reasoning, file or skill uploads, realtime, video generation, or v6-to-v7 breaking changes. For AI SDK v6 code use ai-sdk-6; for version discovery and general doc lookup use ai-sdk."4argument-hint: "[question or feature]"5compatibility: "TypeScript/JavaScript projects using AI SDK 7; Node.js >=22; AI SDK packages are ESM-only."6metadata:7 source: https://skillmd.com/skills/laguagu/ai-sdk-78---910# Vercel AI SDK v7 Development Guide1112Use this skill for AI SDK 7-specific implementation, migrations, and agent13architecture. For AI SDK 6 projects, use `ai-sdk-6`. For unknown versions, use14`ai-sdk` first to inspect `node_modules/ai/package.json` and local docs.1516## First Checks17181. Inspect `package.json`, lockfiles, and `node_modules/ai/package.json`.192. Confirm the installed `ai` major version is 7 before applying this guide.203. Search local docs first: `node_modules/ai/docs/` and `node_modules/ai/src/`.214. In monorepos, check app/package workspaces such as `apps/*/node_modules/ai/`22 and `packages/*/node_modules/ai/`.235. If local docs are missing or ambiguous, verify against `ai-sdk.dev` or the24 Vercel AI repository docs source before coding.2526AI SDK 7 requires Node.js >=22 and AI SDK packages are ESM-only. Convert27`require()` imports to `import` syntax before chasing downstream type errors.2829## Install3031Use the project's package manager and install only packages needed by the task:3233```bash34bun add ai @ai-sdk/react35bun add @ai-sdk/openai # or the provider already used by the project36```3738For durable agents, add `@ai-sdk/workflow` and `workflow`. For harness agents,39add `@ai-sdk/harness`, one harness adapter, and a sandbox provider.4041## Core v7 Patterns4243| Task | Prefer in AI SDK 7 |44| --- | --- |45| Text generation | `generateText` / `streamText` |46| System prompt | top-level `instructions`, not `system` |47| Structured output | `output: Output.object(...)` on text functions |48| Loop limit | `stopWhen: isStepCount(n)` |49| Shared server state | `runtimeContext` |50| Per-tool state/secrets | tool `contextSchema` + `toolsContext` |51| Sensitive tools | `toolApproval` on `generateText`, `streamText`, or `ToolLoopAgent` |52| Durable long-running agents | `WorkflowAgent` from `@ai-sdk/workflow` |53| Running Claude Code/Codex/Pi | `HarnessAgent` from `@ai-sdk/harness/agent` |54| Observability | `registerTelemetry(new OpenTelemetry())` |55| Stalled calls | `timeout` number or object |5657In examples, `__MODEL__` is a placeholder: resolve a current model via the58project's provider package (e.g. `anthropic('...')`) or a gateway model string,59following the model-ID guidance in the `ai-sdk` skill. Never hard-code a model60ID from memory.6162```ts63import { generateText, isStepCount, Output } from 'ai';64import { z } from 'zod';6566const result = await generateText({67 model: __MODEL__,68 instructions: 'Answer concisely.',69 prompt: 'Classify this support ticket.',70 reasoning: 'high',71 stopWhen: isStepCount(3),72 timeout: { totalMs: 60_000, stepMs: 15_000 },73 output: Output.object({74 schema: z.object({75 priority: z.enum(['low', 'medium', 'high']),76 summary: z.string(),77 }),78 }),79});8081console.log(result.output);82```8384## Documentation Routing8586Read only the reference needed for the current task:8788- [agents.md](references/agents.md) - `ToolLoopAgent`, `WorkflowAgent`, context, approvals.89- [harnesses.md](references/harnesses.md) - `HarnessAgent`, sessions, adapters, sandboxing, UI.90- [core-functions.md](references/core-functions.md) - `generateText`, `streamText`, output, result shape.91- [tools.md](references/tools.md) - tools, context, approvals, MCP Apps, sandbox handles.92- [ui-hooks.md](references/ui-hooks.md) - `useChat`, typed tool parts, approvals, harness/workflow UI.93- [migration-v6-to-v7.md](references/migration-v6-to-v7.md) - codemod and breaking-change checklist.94- [telemetry.md](references/telemetry.md) - OpenTelemetry, tracing channel, lifecycle telemetry.95- [media-and-files.md](references/media-and-files.md) - `uploadFile`, `uploadSkill`, realtime, video.96- [examples.md](references/examples.md) - how to fetch canonical examples from `vercel/ai`.9798## Gotchas99100- Do not rely on memory for AI SDK APIs. Verify against local docs/source or101 official docs before writing code.102- Harness packages are experimental. Keep adapter/package details easy to change103 and re-check docs before adding long-lived abstractions.104- `result.usage` now aggregates all steps. Use `result.finalStep.usage` for105 previous final-step-only behavior.106- For `streamText`, await `result.finalStep` before reading final-step-only107 metadata.108- Harness sessions own conversation history. Persist resume state from109 `detach()` or `stop()` instead of replaying the entire UI message history.110- `WorkflowAgent` is stream-first and durable; use `ToolLoopAgent` for simple111 in-memory agents.112- `toolApproval` applies to AI SDK-executed tools. Provider-executed tools and113 harness built-ins have separate approval/permission behavior.114- Always fetch or verify current model IDs from the project's config or provider115 docs before hard-coding a model string.