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

  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)
</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:

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:

   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

   # 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

   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

// 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

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)

// 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<any>; ... }'

✅ CORRECT - Use tool() Helper (REQUIRED)

// 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

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: {