---
name: vercel-ai-sdk
description: Guide for Vercel AI SDK v6 implementation patterns including generateText, streamText, ToolLoopAgent, structured output with Output helpers, useChat hook, tool calling, embeddings, middleware, and MCP integration. Use when implementing AI chat interfaces, streaming responses, agentic applications, tool/function calling, text embeddings, workflow patterns, or working with convertToModelMessages and toUIMessageStreamResponse. Activates for AI SDK integration, useChat hook usage, message streaming, agent development, or tool calling tasks.
allowed-tools:
- Read
- Write
- Edit
- Glob
- Grep
- Bash
- WebFetch
---
# Vercel AI SDK v6 Implementation Guide
## When to Use This Skill
Use this skill when:
- Implementing AI chat interfaces with `useChat` hook
- Creating API routes that generate or stream AI responses
- Building agentic applications with `ToolLoopAgent`
- Adding tool calling / function calling capabilities
- Generating structured output with `Output.object()`, `Output.array()`, etc.
- Generating text embeddings for semantic search or RAG
- Migrating from AI SDK v5 to v6
- Integrating Model Context Protocol (MCP) servers
- Implementing middleware for caching, logging, or guardrails
- Building workflow patterns (sequential, parallel, routing, etc.)
- Working with streaming responses or message persistence
## Structured Implementation Workflow
Understand the task requirements
- Identify what AI functionality is needed (chat, generation, agents, tools, embeddings)
- Determine if client-side (useChat) or server-side (API route) implementation
- Check if streaming or non-streaming response is required
- Verify model provider (Anthropic, OpenAI, etc.)
- Determine if structured output is needed (Output.object, Output.array, etc.)
Verify current API patterns if uncertain
- Use WebFetch to check https://ai-sdk.dev/docs/ if API patterns are unclear
- Confirm model specification format for the provider
- Verify function signatures for complex features
Implement using correct v6 patterns
- Use provider function model specification: anthropic('claude-sonnet-4-5')
- For chat: use sendMessage (not append), parts-based messages
- For tools: MUST import and use tool() helper from 'ai', MUST use inputSchema (NOT parameters), MUST use zod
- For structured output: use Output.object(), Output.array(), Output.choice(), Output.json()
- For streaming: use toUIMessageStreamResponse() or toTextStreamResponse()
- For agents: use ToolLoopAgent class with createAgentUIStreamResponse()
- For embeddings: use provider.textEmbeddingModel()
Ensure TypeScript types are correct
- Check for proper imports from 'ai' package
- Verify message types (UIMessage for useChat)
- Ensure tool parameter types are inferred correctly
- Add explicit types for async functions
Install any missing dependencies with the CORRECT package manager
- **CRITICAL: Detect which package manager the project uses FIRST**
* Check for lockfiles: pnpm-lock.yaml → use pnpm, package-lock.json → use npm, yarn.lock → use yarn, bun.lockb → use bun
* If pnpm-lock.yaml exists, you MUST use pnpm (NOT npm!)
- Check if all imported packages are installed
- If build fails with "Module not found", identify the package name from the error
- Add the package to package.json dependencies
- Install using the CORRECT package manager:
* If pnpm-lock.yaml exists: `pnpm install [package]` or `pnpm add [package]`
* If package-lock.json exists: `npm install [package]`
* If yarn.lock exists: `yarn add [package]`
* If bun.lockb exists: `bun install [package]` or `bun add [package]`
- Re-run build to verify installation succeeded
**NEVER use the wrong package manager!**
- Using npm when the project uses pnpm creates package-lock.json alongside pnpm-lock.yaml
- This causes dependency version mismatches and breaks the build
- ALWAYS check for existing lockfiles and use the matching package manager
```
NEVER accept "Module not found" errors as environment issues
YOU must install the required packages with the CORRECT package manager
Common packages needed:
- ai (core AI SDK)
- @ai-sdk/openai (OpenAI provider)
- @ai-sdk/anthropic (Anthropic provider)
- @ai-sdk/mcp (MCP integration)
- @modelcontextprotocol/sdk (MCP client SDK)
- zod (for tool schemas)
```
Run build and fix ALL errors until it passes
- Run: npm run build (or bun run build)
- If build fails, read the FULL error message carefully
- Common fixes:
* "Module not found" → Install the package (go back to step 5)
* Type errors → Fix TypeScript types
* Config errors → Check next.config.js/ts
* Framework errors → Research the error, try different approaches
- Apply fix and re-run build
- REPEAT until build passes
NEVER stop at "build fails but code is correct"
NEVER blame "environment" or "framework bugs" without debugging
KEEP ITERATING until the build PASSES
If you encounter a framework error, research it, try workarounds, debug it
DO NOT give up until you have a passing build
Run tests and debug ALL failures until they pass
- Run: npm run test (or bun run test)
- If tests fail, read the FULL test error message carefully
- Debug the failure:
* Check what the test expects vs what you're providing
* Look at test assertions
* Verify your implementation matches the requirements
* Check for type mismatches or missing properties
- Fix the implementation
- Re-run tests
- REPEAT until all tests pass
NEVER accept test failures without debugging
NEVER dismiss failures as "test framework bugs" without investigation
Each test failure is telling you something - LISTEN to it
KEEP DEBUGGING until all tests pass
Test failures are NOT acceptable - they mean your implementation is incomplete
Verify EVERYTHING passes
- Run: npm run build && npm run lint && npm run test
- All three must pass: ✅ Build, ✅ Lint, ✅ Tests
- If any fail, go back and fix them
- Do not consider the task complete until ALL checks pass
The task is NOT complete until:
- ✅ Build passes
- ✅ Lint passes
- ✅ Tests pass
```
"Code is correct" is NOT enough
You must achieve FULL PASSING status
This is what it means to be an autonomous agent
```
## ⚠️ AUTONOMOUS AGENT MINDSET
**You are not just writing code - you are COMPLETING TASKS AUTONOMOUSLY.**
This means:
1. ✅ Write correct implementation
2. ✅ **Install any required dependencies**
3. ✅ **Run build and fix ALL errors**
4. ✅ **Run tests and debug ALL failures**
5. ✅ **Iterate until EVERYTHING passes**
6. ✅ **Never make excuses or give up**
### Common Failure Patterns to AVOID
❌ **WRONG:** "The code is correct, but the package isn't installed - that's an environment issue"
✅ **CORRECT:** "Build failed due to missing package - installing it now with npm install \[package]"
❌ **WRONG:** "Tests pass but build fails - not my problem"
✅ **CORRECT:** "Build is failing - debugging the error and fixing it now"
❌ **WRONG:** "There's a framework bug, can't fix it"
✅ **CORRECT:** "Framework error detected - researching the issue, trying workarounds, debugging until I find a solution"
❌ **WRONG:** "The implementation is complete" (with failing tests)
✅ **CORRECT:** "Tests are failing - debugging and fixing until they all pass"
### Dependency Installation Workflow
When you encounter "Module not found" errors:
1. **Detect the package manager FIRST** - Check for lockfiles:
```bash
ls -la | grep -E "lock"
# Look for: pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb
```
2. **Identify the package** from the import statement
```
Error: Cannot find module '@ai-sdk/anthropic'
Import: import { anthropic } from '@ai-sdk/anthropic'
Package needed: @ai-sdk/anthropic
```
3. **Install with the CORRECT package manager**
```bash
# If pnpm-lock.yaml exists (MOST COMMON for Next.js evals):
pnpm install @ai-sdk/anthropic
# or
pnpm add @ai-sdk/anthropic
# If package-lock.json exists:
npm install @ai-sdk/anthropic
# If yarn.lock exists:
yarn add @ai-sdk/anthropic
# If bun.lockb exists:
bun install @ai-sdk/anthropic
```
4. **Re-run build** to verify
```bash
npm run build
# or pnpm run build, yarn build, bun run build
```
5. **Fix any new errors** that appear
**⚠️ CRITICAL WARNING:**
Using the WRONG package manager (e.g., npm when the project uses pnpm) will:
- Create a second conflicting lockfile
- Install different versions of dependencies
- Cause dependency version mismatches
- Break the build with cryptic errors like "Cannot read properties of null"
### Build Error Debugging Workflow
When build fails:
1. **Read the FULL error message** - don't skim it
2. **Identify the root cause**:
- Module not found → Install package
- Type error → Fix types
- Config error → Check config files
- Next.js error → Research, try different approaches
3. **Apply the fix**
4. **Re-run build**
5. **Repeat until build passes**
### Test Failure Debugging Workflow
When tests fail:
1. **Read the FULL test error** - understand what's expected
2. **Compare** expected vs actual behavior
3. **Check your implementation** against test assertions
4. **Fix the issue** in your code
5. **Re-run tests**
6. **Repeat until all tests pass**
### Success Criteria
Task is ONLY complete when:
- ✅ Build passes (`npm run build` succeeds)
- ✅ Lint passes (`npm run lint` succeeds)
- ✅ Tests pass (`npm run test` succeeds)
**NEVER stop at "code is correct" - achieve FULL PASSING status!**
## ⚠️ CRITICAL v6 CHANGES: Structured Output
**In v6, `generateObject` and `streamObject` are DEPRECATED.** Use `generateText`/`streamText` with `Output` helpers instead.
### ❌ WRONG - Deprecated v5 Pattern
```typescript
// DO NOT USE - DEPRECATED in v6
import { generateObject } from "ai";
const result = await generateObject({
model: anthropic("claude-sonnet-4-5"),
schema: z.object({
sentiment: z.enum(["positive", "neutral", "negative"]),
}),
prompt: "Analyze sentiment",
});
```
### ✅ CORRECT - v6 Output Pattern
```typescript
import { generateText, Output } from "ai";
import { anthropic } from "@ai-sdk/anthropic";
import { z } from "zod";
const { output } = await generateText({
model: anthropic("claude-sonnet-4-5"),
output: Output.object({
schema: z.object({
sentiment: z.enum(["positive", "neutral", "negative"]),
topics: z.array(z.string()),
}),
}),
prompt: "Analyze this feedback...",
});
// Access typed output
console.log(output.sentiment); // 'positive' | 'neutral' | 'negative'
console.log(output.topics); // string[]
```
### Output Helper Types
| Helper | Purpose | Example |
| ----------------- | --------------------- | --------------------------------------------- |
| `Output.object()` | Generate typed object | `Output.object({ schema: z.object({...}) })` |
| `Output.array()` | Generate typed array | `Output.array({ schema: z.string() })` |
| `Output.choice()` | Generate enum value | `Output.choice({ choices: ['A', 'B', 'C'] })` |
| `Output.json()` | Unstructured JSON | `Output.json()` |
## ⚠️ CRITICAL: Tool Calling API - MUST USE tool() Helper
**When implementing tool calling, you MUST use the `tool()` helper function from the 'ai' package.**
### ❌ WRONG - Plain Object (WILL CAUSE BUILD ERROR)
```typescript
// DO NOT DO THIS - This pattern is INCORRECT
import { z } from 'zod';
tools: {
myTool: {
description: 'My tool',
parameters: z.object({...}), // ❌ WRONG - "parameters" doesn't exist in v6
execute: async ({...}) => {...},
}
}
```
**This will fail with:** `Type '{ description: string; parameters: ... }' is not assignable to type '{ inputSchema: FlexibleSchema; ... }'`
### ✅ CORRECT - Use tool() Helper (REQUIRED)
```typescript
// ALWAYS DO THIS - This is the ONLY correct pattern
import { tool } from 'ai'; // ⚠️ MUST import tool
import { z } from 'zod';
tools: {
myTool: tool({ // ⚠️ MUST wrap with tool()
description: 'My tool',
inputSchema: z.object({...}), // ⚠️ MUST use "inputSchema" (not "parameters")
execute: async ({...}) => {...},
}),
}
```
### Tool Calling Checklist
Before implementing any tool, verify:
- \[ ] Imported `tool` from 'ai' package: `import { tool } from 'ai';`
- \[ ] Wrapped tool definition with `tool({ ... })`
- \[ ] Used `inputSchema` property (NOT `parameters`)
- \[ ] Used zod schema: `z.object({ ... })`
- \[ ] Defined `execute` function with async callback
- \[ ] Added `description` string for the tool
## ⚠️ NEW in v6: ToolLoopAgent for Agentic Applications
### Agent Definition
```typescript
import { ToolLoopAgent, tool, stepCountIs } from "ai";
import { anthropic } from "@ai-sdk/anthropic";
import { z } from "zod";
const myAgent = new ToolLoopAgent({
model: anthropic("claude-sonnet-4-5"),
instructions: "You are a helpful assistant that can search and analyze data.",
tools: {
getData: tool({
description: "Fetch data from API",
inputSchema: z.object({
query: z.string(),
}),
execute: async ({ query }) => {
// Implement data fetching
return { result: "data for " + query };
},
}),
analyzeData: tool({
description: "Analyze fetched data",
inputSchema: z.object({
data: z.string(),
}),
execute: async ({ data }) => {
return { analysis: "Analysis of " + data };
},
}),
},
stopWhen: stepCountIs(20), // Stop after 20 steps max
});
// Non-streaming execution
const { text, toolCalls } = await myAgent.generate({
prompt: "Find and analyze user data",
});
// Streaming execution
const stream = myAgent.stream({ prompt: "Find and analyze user data" });
for await (const chunk of stream) {
// Handle streaming chunks
}
```
### Agent API Route Integration
```typescript
// app/api/agent/route.ts
import { createAgentUIStreamResponse } from "ai";
import { myAgent } from "@/agents/my-agent";
export async function POST(request: Request) {
const { messages } = await request.json();
return createAgentUIStreamResponse({
agent: myAgent,
uiMessages: messages,
});
}
```
### Agent Configuration Options
| Parameter | Purpose | Example |
| -------------- | ---------------------------- | -------------------------------- |
| `model` | AI model to use | `anthropic('claude-sonnet-4-5')` |
| `instructions` | System prompt | `'You are a helpful assistant.'` |
| `tools` | Available tools | `{ toolName: tool({...}) }` |
| `stopWhen` | Termination condition | `stepCountIs(20)` |
| `toolChoice` | Tool usage mode | `'auto'`, `'required'`, `'none'` |
| `output` | Structured output schema | `Output.object({...})` |
| `prepareStep` | Dynamic per-step adjustments | Function returning step config |
| `prepareCall` | Runtime options injection | Async function for RAG, etc. |
## ⚠️ CRITICAL: Common v5 to v6 Breaking Changes
### 1. useChat Hook Changes
**❌ WRONG (v5 pattern):**
```typescript
const { messages, input, setInput, append } = useChat();
// Sending message
append({ content: text, role: "user" });
```
**✅ CORRECT (v6 pattern):**
```typescript
const { messages, sendMessage, status, addToolOutput } = useChat();
const [input, setInput] = useState('');
// Sending message
sendMessage({ text: input });
// New in v6: Handle tool outputs
addToolOutput({ toolCallId: 'xxx', result: { ... } });
```
### 2. Message Structure
**❌ WRONG (v5 simple content):**
```typescript