Vercel AI SDK v5 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
- Adding tool calling / function calling capabilities
- Generating text embeddings for semantic search or RAG
- Migrating from AI SDK v4 to v5
- Integrating Model Context Protocol (MCP) servers
- Working with streaming responses or message persistence
Structured Implementation Workflow
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)
- @modelcontextprotocol/sdk (MCP integration)
- zod (for tool schemas)
</critical>
"Code is correct" is NOT enough
You must achieve FULL PASSING status
This is what it means to be an autonomous agent
</critical>
⚠️ AUTONOMOUS AGENT MINDSET
You are not just writing code - you are COMPLETING TASKS AUTONOMOUSLY.
This means:
- ✅ Write correct implementation
- ✅ Install any required dependencies
- ✅ Run build and fix ALL errors
- ✅ Run tests and debug ALL failures
- ✅ Iterate until EVERYTHING passes
- ✅ 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:
-
Detect the package manager FIRST - Check for lockfiles:
ls -la | grep -E "lock"
-
Identify the package from the import statement
Error: Cannot find module '@ai-sdk/openai'
Import: import { openai } from '@ai-sdk/openai'
Package needed: @ai-sdk/openai
-
Install with the CORRECT package manager
pnpm install @ai-sdk/openai
pnpm add @ai-sdk/openai
npm install @ai-sdk/openai
yarn add @ai-sdk/openai
bun install @ai-sdk/openai
-
Re-run build to verify
npm run build
-
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:
- Read the FULL error message - don't skim it
- 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
- Apply the fix
- Re-run build
- Repeat until build passes
Test Failure Debugging Workflow
When tests fail:
- Read the FULL test error - understand what's expected
- Compare expected vs actual behavior
- Check your implementation against test assertions
- Fix the issue in your code
- Re-run tests
- 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: 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)
import { z } from 'zod';
tools: {
myTool: {
description: 'My tool',
parameters: z.object({...}),
execute: async ({...}) => {...},
}
}
This will fail with: Type '{ description: string; parameters: ... }' is not assignable to type '{ inputSchema: FlexibleSchema<any>; ... }'
✅ CORRECT - Use tool() Helper (REQUIRED)
import { tool } from 'ai';
import { z } from 'zod';
tools: {
myTool: tool({
description: 'My tool',
inputSchema: z.object({...}),
execute: async ({...}) => {...},
}),
}
Tool Calling Checklist
Before implementing any tool, verify:
⚠️ CRITICAL: Common v4 to v5 Breaking Changes
1. useChat Hook Changes
❌ WRONG (v4 pattern):
const { messages, input, setInput, append } = useChat();
append({ content: text, role: 'user' });
✅ CORRECT (v5 pattern):
const { messages, sendMessage } = useChat();
const [input, setInput] = useState('');
sendMessage({ text: input });
2. Message Structure
❌ WRONG (v4 simple content):
<div>{message.content}</div>
✅ CORRECT (v5 parts-based):
<div>
{message.parts.map((part, index) =>
part.type === 'text' ? <span key={index}>{part.text}</span> : null
)}
</div>
3. Model Specification
✅ PREFER: String-based (v5 recommended):
import { generateText } from 'ai';
const result = await generateText({
model: 'openai/gpt-4o',
prompt: 'Hello',
});
✅ ALSO WORKS: Function-based (legacy support):
import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';
const result = await generateText({
model: openai('gpt-4o'),
prompt: 'Hello',
});
Core API Reference
1. generateText - Non-Streaming Text Generation
Purpose: Generate text for non-interactive use cases (email drafts, summaries, agents with tools).
Signature:
import { generateText } from 'ai';
const result = await generateText({
model: 'openai/gpt-4o',
prompt: 'Your prompt here',
system: 'Optional system message',
tools?: { ... },
maxSteps?: 5,
