Guides Vercel AI SDK v6 (ai, @ai-sdk/react, ToolLoopAgent, generateText/streamText, Output.object, MCP tools) across LLM providers. Use when building chat, structured output, tool calling, streaming, embeddings, or migrating v5 to v6. Not for the OpenAI Agents SDK (agents-sdk) or raw provider SDKs without the ai package.
Guides Vercel AI SDK v6 (ai, @ai-sdk/react, ToolLoopAgent, generateText/streamText, Output.object, MCP tools) across LLM providers. Use when building chat, structured output, tool calling, streaming, embeddings, or migrating v5 to v6. Not for the OpenAI Agents SDK (agents-sdk) or raw provider SDKs without the ai package.
version
1.0.1
metadata
{"priority":8,"docs":["https://sdk.vercel.ai/docs","https://sdk.vercel.ai/docs/reference"],"sitemap":"https://sdk.vercel.ai/sitemap.xml","pathPatterns":["app/api/chat/**","app/api/completion/**","src/app/api/chat/**","src/app/api/completion/**","pages/api/chat.*","pages/api/chat/**","pages/api/completion.*","pages/api/completion/**","src/pages/api/chat.*","src/pages/api/chat/**","src/pages/api/completion.*","src/pages/api/completion/**","lib/ai/**","src/lib/ai/**","lib/ai.*","src/lib/ai.*","ai/**","apps/*/app/api/chat/**","apps/*/app/api/completion/**","apps/*/src/app/api/chat/**","apps/*/src/app/api/completion/**","apps/*/lib/ai/**","apps/*/src/lib/ai/**","lib/agent.*","src/lib/agent.*","app/actions/chat.*","src/app/actions/chat.*"],"importPatterns":["ai","@ai-sdk/*"],"bashPatterns":["\\bnpm\\s+(install|i|add)\\s+[^\\n]*\\bai\\b","\\bpnpm\\s+(install|i|add)\\s+[^\\n]*\\bai\\b","\\bbun\\s+(install|i|add)\\s+[^\\n]*\\bai\\b","\\byarn\\s+add\\s+[^\\n]*\\bai\\b","\\bnpm\\s+(install|i|add)\\s+[^\\n]*@ai-sdk/","\\bpnpm\\s+(install|i|add)\\s+[^\\n]*@ai-sdk/","\\bbun\\s+(install|i|add)\\s+[^\\n]*@ai-sdk/","\\byarn\\s+add\\s+[^\\n]*@ai-sdk/","\\bnpx\\s+@ai-sdk/devtools\\b","\\bnpx\\s+@ai-sdk/codemod\\b","\\bnpx\\s+mcp-to-ai-sdk\\b"],"promptSignals":{"phrases":["ai sdk","vercel ai","generatetext","streamtext"],"allOf":["[Truncated]","[Truncated]"],"anyOf":["usechat","usecompletion","tool calling","embeddings"],"noneOf":["openai api directly"],"minScore":6}}
Vercel AI SDK (v6)
CRITICAL — Your training data is outdated for this library. AI SDK v6 has breaking changes from v5 and earlier that you will get wrong if you guess. Before writing AI SDK code, fetch the docs at https://ai-sdk.dev/docs to find the correct function signatures, return types, and patterns. Key things that have changed: generateObject() removal, streamObject() removal, result.files for image generation, Output.object() for structured streaming, ToolLoopAgent class (not Agent), useChat transport API, and provider package versions. Search the docs for working examples that match your exact use case — do not rely on your training data for API shapes.
Overview
The AI SDK is the leading TypeScript toolkit for building AI-powered applications. It provides a unified API across all LLM providers. AI SDK v6 (ai@^6.0.0) is the current umbrella package with significant breaking changes from v5.
Need
How
Text generation / chat
generateText() or streamText() with model: "openai/gpt-5.4"
Image generation
generateText() with model: "google/gemini-3.1-flash-image-preview" — images in result.files. Always use this model, never older gemini-2.x models
Structured JSON output
generateText() with output: Output.object({ schema })
Tool calling / agents
generateText() with tools: { ... } or ToolLoopAgent
Embeddings
embed() / embedMany() with @ai-sdk/openai
If the product needs generated images (portraits, posters, cover art, illustrations, comics, diagrams), use generateText with an image model — do NOT use placeholder images or skip image generation.
When to Use
Use this skill when:
Building chat interfaces, text generation, or structured output features
Implementing tool calling, agents, or MCP integration
Working with streaming, embeddings, reranking, or image generation
Integrating any LLM provider (OpenAI, Anthropic, Google, etc.)
Migrating from AI SDK v5 to v6
Installing or updating ai, @ai-sdk/react, or any @ai-sdk/* package
Prerequisites
Node.js and a package manager (npm, pnpm, bun, or yarn)
A Vercel project linked for AI Gateway OIDC auto-provisioning (recommended)
For Windows hosts (PowerShell primary): ensure vercel CLI is installed globally
Procedure
1. Installation
npm install ai@^6.0.0 @ai-sdk/react@^3.0.0
npm install @ai-sdk/openai@^3.0.41 # Optional: required for embeddings
npm install @ai-sdk/anthropic@^3.0.58 # Optional: direct Anthropic provider access
npm install @ai-sdk/vercel@^2.0.37 # Optional: v0 model provider (v0-1.0-md)
@ai-sdk/react is a separate package — it is NOT included in the ai package. For v6 projects, install @ai-sdk/react@^3.0.x alongside ai@^6.0.0.
If you install @ai-sdk/gateway directly, use @ai-sdk/gateway@^3.x (NOT ^1.x).
Only install a direct provider SDK (e.g., @ai-sdk/anthropic) if you need provider-specific features not exposed through the gateway.
2. Setup for AI Projects (Vercel AI Gateway with OIDC)
For the smoothest experience, link to a Vercel project so AI Gateway credentials are auto-provisioned via OIDC:
vercel link# Connect to your Vercel project# Enable AI Gateway at https://vercel.com/{team}/{project}/settings → AI Gateway
vercel env pull .env.local # Provisions VERCEL_OIDC_TOKEN automatically
npm install ai@^6.0.0 # Gateway is built in
npx ai-elements # Required: install AI text rendering components
This gives you AI Gateway access with OIDC authentication, cost tracking, failover, and observability — no manual API keys needed.
OIDC is the default auth: vercel env pull provisions a VERCEL_OIDC_TOKEN (short-lived JWT, ~24h). The @ai-sdk/gateway reads it automatically via @vercel/oidc. On Vercel deployments, tokens auto-refresh. For local dev, re-run vercel env pull when the token expires. No AI_GATEWAY_API_KEY or provider-specific keys needed.
3. Global Provider System (AI Gateway — Default)
In AI SDK 6, pass a "provider/model" string to the model parameter — it automatically routes through the Vercel AI Gateway:
import { generateText } from"ai";
const { text } = awaitgenerateText({
model: "openai/gpt-5.4", // plain string — routes through AI Gateway automaticallyprompt: "Hello!",
});
No gateway() wrapper needed — plain "provider/model" strings are the simplest approach and are what the official Vercel docs recommend. The gateway() function is an optional explicit wrapper (useful when you need providerOptions.gateway for routing, failover, or tags):
Both approaches provide failover, cost tracking, and observability on Vercel.
Model slug rules: Always use provider/model format. Version numbers use dots, not hyphens: anthropic/claude-sonnet-4.6 (not claude-sonnet-4-6). Default to openai/gpt-5.4 or anthropic/claude-sonnet-4.6. Never use outdated models like gpt-4o.
AI Gateway does not support embeddings. Use a direct provider SDK such as @ai-sdk/openai for embeddings.
Direct provider SDKs (@ai-sdk/openai, @ai-sdk/anthropic, etc.) are only needed for provider-specific features not exposed through the gateway (e.g., Anthropic computer use, OpenAI fine-tuned model endpoints).
4. Text Generation
import { generateText, streamText } from"ai";
// Non-streamingconst { text } = awaitgenerateText({
model: "openai/gpt-5.4",
prompt: "Explain quantum computing in simple terms.",
});
// Streamingconst result = streamText({
model: "openai/gpt-5.4",
prompt: "Write a poem about coding.",
});
forawait (const chunk of result.textStream) {
process.stdout.write(chunk);
}
5. Structured Output
generateObject was removed in AI SDK v6. Use generateText with output: Output.object() instead. Do NOT import generateObject — it does not exist.
In AI SDK 6, tools use inputSchema (not parameters) and output/outputSchema (not result), aligned with the MCP specification. Per-tool strict mode ensures providers only generate valid tool calls matching your schema.
import { generateText, tool } from"ai";
import { z } from"zod";
const result = awaitgenerateText({
model: "openai/gpt-5.4",
tools: {
weather: tool({
description: "Get the weather for a location",
inputSchema: z.object({
city: z.string().describe("The city name"),
}),
outputSchema: z.object({
temperature: z.number(),
condition: z.string(),
}),
strict: true, // Providers generate only schema-valid tool callsexecute: async ({ city }) => {
const data = awaitfetchWeather(city);
return { temperature: data.temp, condition: data.condition };
},
}),
},
prompt: "What is the weather in San Francisco?",
});
7. Dynamic Tools (MCP Integration)
For tools with schemas not known at compile time (e.g., MCP server tools):
The ToolLoopAgent class wraps generateText/streamText with an agentic tool-calling loop. Default stopWhen is stepCountIs(20) (up to 20 tool-calling steps). Agent is an interface — ToolLoopAgent is the concrete implementation.
import { ToolLoopAgent, stepCountIs, hasToolCall } from"ai";
const agent = newToolLoopAgent({
model: "anthropic/claude-sonnet-4.6",
tools: { weather, search, calculator, finalAnswer },
instructions: "You are a helpful assistant.",
// Default: stepCountIs(20). Override to stop on a terminal tool or custom logic:stopWhen: hasToolCall("finalAnswer"),
prepareStep: (context) => ({
// Customize each step — swap models, compress messages, limit toolstoolChoice: context.steps.length > 5 ? "none" : "auto",
}),
});
const { text } = await agent.generate({
prompt:
"Research the weather in Tokyo and calculate the average temperature this week.",
});
9. MCP Client
Connect to any MCP server and use its tools:
import { generateText } from"ai";
import { createMCPClient } from"@ai-sdk/mcp";
const mcpClient = awaitcreateMCPClient({
transport: {
type: "sse",
url: "https://my-mcp-server.com/sse",
},
});
const tools = await mcpClient.tools();
const result = awaitgenerateText({
model: "openai/gpt-5.4",
tools,
prompt: "Use the available tools to help the user.",
});
await mcpClient.close();
MCP OAuth for remote servers is handled automatically by @ai-sdk/mcp.
10. Tool Approval (Human-in-the-Loop)
Set needsApproval on any tool to require user confirmation before execution. The tool pauses in approval-requested state until the client responds.
AI Gateway supports image generation. Use the google/gemini-3.1-flash-image-preview model — it is significantly better than older models like gemini-2.0-flash-exp-image-generation or gemini-2.0-flash-001.
Always use google/gemini-3.1-flash-image-preview for image generation. Do NOT use older models (gemini-2.0-*, gemini-2.5-*) — they produce much worse results and some do not support image output at all.
Multimodal LLMs (recommended — use generateText/streamText)
import { generateText, streamText } from"ai";
// generateText — images returned in result.filesconst result = awaitgenerateText({
model: "google/gemini-3.1-flash-image-preview",
prompt: "A futuristic cityscape at sunset",
});
const imageFiles = result.files.filter((f) => f.mediaType?.startsWith("image/"));
// Convert to data URL for displayconst imageFile = imageFiles[0];
const dataUrl = `data:${imageFile.mediaType};base64,${Buffer.from(imageFile.data).toString("base64")}`;
// streamText — stream text, then access images after completionconst stream = streamText({
model: "google/gemini-3.1-flash-image-preview",
prompt: "A futuristic cityscape at sunset",
});
forawait (const delta of stream.fullStream) {
if (delta.type === "text-delta") process.stdout.write(delta.text);
}
const finalResult = await stream;
console.log(`Generated ${finalResult.files.length} image(s)`);
Default image model: google/gemini-3.1-flash-image-preview — fast, high-quality. This is the ONLY recommended model for image generation.
MANDATORY — Always use AI Elements for AI text: AI SDK models always produce markdown — even short prose contains **bold**, ## headings, `code`, and ---. There is no "plain text" mode. Every AI-generated string displayed in a browser MUST be rendered through AI Elements.
Chat messages: Use AI Elements <Message message={message} /> — handles text, tool calls, code blocks, reasoning, streaming.
Any other AI text (streaming panels, workflow events, reports, briefings, narratives, summaries, perspectives): Use <MessageResponse>{text}</MessageResponse> from @/components/ai-elements/message.
<MessageResponse> wraps Streamdown with code highlighting, math, mermaid, and CJK plugins — works for any markdown string, including streamed text.
Never render AI output as raw {text}, <p>{content}</p>, or <div>{stream}</div> — this always produces ugly unformatted output with visible markdown syntax.
No exceptions: Even if you think the response will be "simple prose", models routinely add markdown formatting. Always use AI Elements.
⤳ skill: ai-elements — Full component library, decision guidance, and troubleshooting for AI interfaces
14. Transport Options
useChat uses a transport-based architecture. Three built-in transports:
Transport
Use Case
DefaultChatTransport
HTTP POST to API routes (default — sends to /api/chat)
DirectChatTransport
In-process agent communication without HTTP (SSR, testing)
TextStreamChatTransport
Plain text stream protocol
Default behavior:useChat() with no transport defaults to DefaultChatTransport({ api: '/api/chat' }) — explicit transport only needed for custom endpoints or DirectChatTransport.
For agent API routes, use createAgentUIStreamResponse({ agent, uiMessages }) instead of manual streamText + toUIMessageStreamResponse().
16. Text-Only Stream (CLI / Non-Browser)
import { streamText } from"ai";
const result = streamText({
model: "openai/gpt-5.4",
prompt: "Write a poem about coding.",
});
return result.toTextStreamResponse();
toTextStreamResponse() is only for CLI tools, server pipes, and programmatic consumers. If the text is displayed in a browser, use toUIMessageStreamResponse() + AI Elements.
17. Language Model Middleware
Intercept and transform model calls for RAG, guardrails, logging:
Run npx @ai-sdk/codemod upgrade (or npx @ai-sdk/codemod v6) to auto-migrate. Preview with npx @ai-sdk/codemod --dry upgrade.
Pitfalls
v6 Migration Pitfalls (Read First)
ai@^6.0.0 is the umbrella package for AI SDK v6 (latest: 6.0.83).
@ai-sdk/react is ^3.0.x in v6 projects (NOT ^6.0.0).
@ai-sdk/gateway is ^3.x in v6 projects (NOT ^1.x).
In createUIMessageStream, write with stream.writer.write(...) (NOT stream.write(...)).
useChat no longer supports body or onResponse; configure behavior through transport.
UI tool parts are typed as tool-<toolName> (for example tool-weather), not tool-invocation.
DynamicToolCall does not provide typed .args; cast via unknown first.
TypedToolResult exposes .output (NOT .result).
The agent class is ToolLoopAgent (NOT Agent — Agent is just an interface).
Constructor uses instructions (NOT system).
Agent methods are agent.generate() and agent.stream() (NOT agent.generateText() or agent.streamText()).
AI Gateway does not support embeddings; use @ai-sdk/openai directly for openai.embedding(...).
useChat() with no transport defaults to DefaultChatTransport({ api: '/api/chat' }) — explicit transport only needed for custom endpoints or DirectChatTransport.
Default stopWhen for ToolLoopAgent is stepCountIs(20), not stepCountIs(1) — override if you need fewer steps.
strict: true on tools is opt-in per tool, not global — only set on tools with provider-compatible schemas.
For agent API routes, use createAgentUIStreamResponse({ agent, uiMessages }) instead of manual streamText + toUIMessageStreamResponse().
@ai-sdk/azure now uses the Responses API by default — use azure.chat() for the previous Chat Completions API behavior.
@ai-sdk/azure uses azure (not openai) as the key for providerMetadata and providerOptions.
@ai-sdk/google-vertex uses vertex (not google) as the key for providerMetadata and providerOptions.
This is one of the most common v5→v6 migration mistakes. The config key is output and the result key is also output.
Image Generation Model Selection
Always use google/gemini-3.1-flash-image-preview for image generation. Do NOT use older models (gemini-2.0-*, gemini-2.5-*) — they produce much worse results and some do not support image output at all.
Rendering AI Text in Browser
Never render AI output as raw {text}, <p>{content}</p>, or <div>{stream}</div> — this always produces ugly unformatted output with visible markdown syntax. Always use AI Elements (<Message> for chat, <MessageResponse> for any other AI text).
Migration Key Changes (v5 → v6)
generateObject / streamObject → generateText / streamText with Output.object()
parameters → inputSchema
result → output
maxSteps → stopWhen: stepCountIs(N) (import stepCountIs from ai)
CoreMessage → ModelMessage (use convertToModelMessages() — now async)
ToolCallOptions → ToolExecutionOptions
Experimental_Agent → ToolLoopAgent (concrete class; Agent is just an interface)
Verify migration — dry-run the codemod to preview changes:
npx @ai-sdk/codemod --dry upgrade
# Review output for breaking changes before applying
Key Patterns
Default to AI Gateway with OIDC — pass "provider/model" strings (e.g., model: "openai/gpt-5.4") to route through the gateway automatically. vercel env pull provisions OIDC tokens. No manual API keys needed. The gateway() wrapper is optional (only needed for providerOptions.gateway).
Set up a Vercel project for AI — vercel link → enable AI Gateway at https://vercel.com/{team}/{project}/settings → AI Gateway → vercel env pull to get OIDC credentials. Never manually create .env.local with provider-specific API keys.
Always use AI Elements for any AI text in a browser — npx ai-elements installs production-ready Message, Conversation, and Tool components. Use <Message> for chat and <MessageResponse> for any other AI-generated text (streaming panels, summaries, reports). AI models always produce markdown — there is no scenario where raw {text} rendering is correct. ⤳ skill: ai-elements
Always stream for user-facing AI — use streamText + useChat, not generateText
UIMessage chat UIs — useChat() defaults to DefaultChatTransport({ api: '/api/chat' }). On the server: convertToModelMessages() + toUIMessageStreamResponse(). For no-API-route setups: DirectChatTransport + Agent.
Text-only clients (non-browser) — toTextStreamResponse() is only for CLI tools, server pipes, and programmatic consumers. If the text is displayed in a browser, use toUIMessageStreamResponse() + AI Elements
Use structured output for extracting data — generateText with Output.object() and Zod schemas
Use ToolLoopAgent for multi-step reasoning — not manual loops. Default stopWhen is stepCountIs(20). Use createAgentUIStreamResponse for agent API routes.
Use DurableAgent (from Workflow DevKit) for production agents that must survive crashes
Use mcp-to-ai-sdk to generate static tool definitions from MCP servers for security
Use needsApproval for human-in-the-loop — set on any tool to pause execution until user approves; supports conditional approval via async function
Use strict: true per tool — opt-in strict mode ensures providers only generate schema-valid tool calls; set on individual tools, not globally
Related skills
ai-elements — Full component library, decision guidance, and troubleshooting for AI interfaces. Use when rendering any AI-generated text in a browser.
