--- name: ai-sdk-core description: | Build backend AI with Vercel AI SDK v6 stable. Covers Output API (replaces generateObject/streamObject), speech synthesis, transcription, embeddings, MCP tools with security guidance. Includes v4→v5 migration and 15 error solutions with workarounds.

Use when: implementing AI SDK v5/v6, migrating versions, troubleshooting AI_APICallError, Workers startup issues, Output API errors, Gemini caching issues, Anthropic tool errors, MCP tools, or stream resumption failures. user-invocable: true ---

AI SDK Core

Backend AI with Vercel AI SDK v5 and v6.

Installation:

npm install ai @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google zod

---

AI SDK 6 (Stable - January 2026)

Status: Stable Latest: [email protected] (Jan 2026)

BREAKING: Output API Replaces generateObject/streamObject

⚠️ CRITICAL: generateObject() and streamObject() are DEPRECATED and will be removed in a future version. Use the new Output API instead.

Before (v5 - DEPRECATED):

// ❌ DEPRECATED - will be removed
import { generateObject } from 'ai';

const result = await generateObject({
  model: openai('gpt-5'),
  schema: z.object({ name: z.string(), age: z.number() }),
  prompt: 'Generate a person',
});

After (v6 - USE THIS):

// ✅ NEW OUTPUT API
import { generateText, Output } from 'ai';

const result = await generateText({
  model: openai('gpt-5'),
  output: Output.object({ schema: z.object({ name: z.string(), age: z.number() }) }),
  prompt: 'Generate a person',
});

// Access the typed object
console.log(result.object); // { name: "Alice", age: 30 }

Output Types

import { generateText, Output } from 'ai';

// Object with Zod schema
output: Output.object({ schema: myZodSchema })

// Array of typed objects
output: Output.array({ schema: personSchema })

// Enum/choice from options
output: Output.choice({ choices: ['positive', 'negative', 'neutral'] })

// Plain text (explicit)
output: Output.text()

// Unstructured JSON (no schema validation)
output: Output.json()

Streaming with Output API

import { streamText, Output } from 'ai';

const result = streamText({
  model: openai('gpt-5'),
  output: Output.object({ schema: personSchema }),
  prompt: 'Generate a person',
});

// Stream partial objects
for await (const partialObject of result.objectStream) {
  console.log(partialObject); // { name: "Ali..." } -> { name: "Alice", age: ... }
}

// Get final object
const finalObject = await result.object;

v6 New Features

1. Agent Abstraction Unified interface for building agents with ToolLoopAgent class:

• Full control over execution flow, tool loops, and state management
• Replaces manual tool calling orchestration

2. Tool Execution Approval (Human-in-the-Loop)

Use selective approval for better UX. Not every tool call needs approval.

tools: {
  payment: tool({
    // Dynamic approval based on input
    needsApproval: async ({ amount }) => amount > 1000,
    inputSchema: z.object({ amount: z.number() }),
    execute: async ({ amount }) => { /* process payment */ },
  }),

  readFile: tool({
    needsApproval: false, // Safe operations don't need approval
    inputSchema: z.object({ path: z.string() }),
    execute: async ({ path }) => fs.readFile(path),
  }),

  deleteFile: tool({
    needsApproval: true, // Destructive operations always need approval
    inputSchema: z.object({ path: z.string() }),
    execute: async ({ path }) => fs.unlink(path),
  }),
}

Best Practices:

• Use dynamic approval for operations where risk depends on parameters (e.g., payment amount)
• Always require approval for destructive operations (delete, modify, purchase)
• Don't require approval for safe read operations
• Add system instruction: "When a tool execution is not approved, do not retry it"
• Implement timeout for approval requests to prevent stuck states
• Store user preferences for repeat actions

Sources:

• Next.js Human-in-the-Loop Guide
• Cloudflare Agents Human-in-the-Loop
• Permit.io Best Practices

3. Reranking for RAG

import { rerank } from 'ai';

const result = await rerank({
  model: cohere.reranker('rerank-v3.5'),
  query: 'user question',
  documents: searchResults,
  topK: 5,
});

4. MCP Tools (Model Context Protocol)

⚠️ SECURITY WARNING: MCP tools have significant production risks. See security section below.

import { experimental_createMCPClient } from 'ai';

const mcpClient = await experimental_createMCPClient({
  transport: { type: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem'] },
});

const tools = await mcpClient.tools();

const result = await generateText({
  model: openai('gpt-5'),
  tools,
  prompt: 'List files in the current directory',
});

Known Issue: MCP tools may not execute in streaming mode (Vercel Community Discussion). Use generateText() instead of streamText() for MCP tools.

MCP Security Considerations

⚠️ CRITICAL: Dynamic MCP tools in production have security risks:

Risks:

• Tool definitions become part of your agent's prompt
• Can change unexpectedly without warning
• Compromised MCP server can inject malicious prompts
• New tools can escalate user privileges (e.g., adding delete to read-only server)

Solution - Use Static Tool Generation:

// ❌ RISKY: Dynamic tools change without your control
const mcpClient = await experimental_createMCPClient({ /* ... */ });
const tools = await mcpClient.tools(); // Can change anytime!

// ✅ SAFE: Generate static, versioned tool definitions
// Step 1: Install mcp-to-ai-sdk
npm install -g mcp-to-ai-sdk

// Step 2: Generate static tools (one-time, version controlled)
npx mcp-to-ai-sdk generate stdio 'npx -y @modelcontextprotocol/server-filesystem'

// Step 3: Import static tools
import { tools } from './generated-mcp-tools';

const result = await generateText({
  model: openai('gpt-5'),
  tools, // Static, reviewed, versioned
  prompt: 'Use tools',
});

Best Practice: Generate static tools, review them, commit to version control, and only update intentionally.

Source: Vercel Blog: MCP Security

5. Language Model Middleware

import { wrapLanguageModel, extractReasoningMiddleware } from 'ai';

const wrappedModel = wrapLanguageModel({
  model: anthropic('claude-sonnet-4-5-20250929'),
  middleware: extractReasoningMiddleware({ tagName: 'think' }),
});

// Reasoning extracted automatically from <think>...</think> tags

6. Telemetry (OpenTelemetry)

const result = await generateText({
  model: openai('gpt-5'),
  prompt: 'Hello',
  experimental_telemetry: {
    isEnabled: true,
    functionId: 'my-chat-function',
    metadata: { userId: '123' },
    recordInputs: true,
    recordOutputs: true,
  },
});

Official Docs: https://ai-sdk.dev/docs

---

Latest AI Models (2025-2026)

OpenAI

GPT-5.2 (Dec 2025):

• 400k context window, 128k output tokens
• Enhanced reasoning capabilities
• Available in API platform

GPT-5.1 (Nov 2025):

• Improved speed and efficiency over GPT-5
• "Warmer" and more intelligent responses

GPT-5 (Aug 2025):

• 45% less hallucination than GPT-4o
• State-of-the-art in math, coding, visual perception

o3 Reasoning Models (Dec 2025):

• o3, o3-pro, o3-mini - Advanced reasoning
• o4-mini - Fast reasoning

...