ai-sdk

name	ai-sdk
description	Comprehensive guide to AI SDK v6 for agent development, tool definitions, multi-step agentic workflows, and result extraction patterns

Vercel AI SDK v6 Patterns

Zod 4.x

This repo uses Zod 4.x (4.3.5+) directly:

// ✅ Standard Zod 4 import
import { z } from 'zod'

Zod 4's optimized types work well with AI SDK v6's recursive generics.

---

Comprehensive guide for Vercel AI SDK v6 (6.0+) patterns used in agent-first applications. Contains rules for provider setup, tool definitions, multi-step workflows, and result extraction.

When to Apply

Reference these guidelines when:

• Setting up AI model providers
• Defining agent tools with tool()
• Implementing multi-step agentic workflows
• Extracting results from generateText/streamText
• Migrating from AI SDK v5 to v6

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Provider Setup	CRITICAL	provider-
2	Text Generation	HIGH	generate-
3	Tool Definitions	HIGH	tool-
4	Multi-Step Agents	HIGH	agent-
5	Result Extraction	MEDIUM	result-
6	Message Types	MEDIUM	message-
7	Error Handling	MEDIUM	error-

Quick Reference

Critical v6 Breaking Changes

// ❌ v5 patterns that FAIL in v6:
import { type CoreMessage } from 'ai'     // → ModelMessage
parameters: z.object({...})               // → inputSchema
maxSteps: 5                               // → stopWhen: stepCountIs(5)
call.args                                 // → call.input
call.toolResult                           // → step.toolResults[].output

1. Provider Setup (CRITICAL)

• provider-gateway - Use AI Gateway model strings (recommended)

import { generateText } from 'ai'

const result = await generateText({
  model: 'anthropic/claude-opus-4-5',  // AI Gateway string
  prompt: 'Hello',
})

No provider wrapper is required when using AI Gateway model strings.

2. Text Generation (HIGH)

• generate-basic - Core generateText pattern

3. Tool Definitions (HIGH)

• tool-input-schema - v6 uses inputSchema not parameters
• tool-definition - Complete tool() pattern

import { tool } from 'ai'
import { z } from 'zod'

const myTool = tool({
  description: 'What this does',
  inputSchema: z.object({  // ✅ inputSchema not parameters
    param: z.string().describe('Description'),
  }),
  execute: async ({ param }) => {
    return { result: 'done' }
  },
})

4. Multi-Step Agents (HIGH)

• agent-stop-when - v6 uses stopWhen not maxSteps
• agent-multi-step - Complete agent pattern

import { generateText, stepCountIs } from 'ai'

const result = await generateText({
  model: 'anthropic/claude-opus-4-5',
  messages,
  tools: agentTools,
  stopWhen: stepCountIs(5),  // ✅ not maxSteps: 5
})

5. Result Extraction (MEDIUM)

• result-tool-access - Access tool calls and results correctly

// ✅ Correct v6 pattern
const toolCalls = result.steps.flatMap((step) => {
  const resultsMap = new Map(
    (step.toolResults || []).map((r) => [r.toolCallId, r.output])
  )
  return (step.toolCalls || []).map((tc) => ({
    name: tc.toolName,
    args: tc.input,  // ✅ input not args
    result: resultsMap.get(tc.toolCallId),  // ✅ from toolResults
  }))
})

6. Message Types (MEDIUM)

• message-model-message - Use ModelMessage type

import { type ModelMessage } from 'ai'  // ✅ not CoreMessage

const messages: ModelMessage[] = [
  { role: 'user', content: 'Hello' },
]

How to Use

Read individual rule files for detailed explanations and code examples:

rules/provider-gateway.md
rules/tool-input-schema.md
rules/agent-stop-when.md
rules/result-tool-access.md
rules/_sections.md

Each rule file contains:

• Brief explanation of why it matters
• Incorrect code example with explanation
• Correct code example with explanation
• Reference links

Key Imports

import {
  generateText,
  generateObject,
  streamText,
  streamObject,
  tool,
  stepCountIs,
  hasToolCall,
  type ModelMessage,
} from 'ai'
import { z } from 'zod'  // Zod 4.x

Model Strings (AI Gateway)

anthropic/claude-opus-4-5
anthropic/claude-sonnet-4
openai/gpt-4o
google/gemini-2.0-flash

Auth: Set AI_GATEWAY_API_KEY environment variable.