ai-sdk-core

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

import { openai } from '@ai-sdk/openai';
const gpt52 = openai('gpt-5.2');
const gpt51 = openai('gpt-5.1');
const gpt5 = openai('gpt-5');
const o3 = openai('o3');
const o3mini = openai('o3-mini');

Anthropic

Claude 4 Family (May-Oct 2025):

• Opus 4 (May 22): Best for complex reasoning, $15/$75 per million tokens
• Sonnet 4 (May 22): Balanced performance, $3/$15 per million tokens
• Opus 4.1 (Aug 5): Enhanced agentic tasks, real-world coding
• Sonnet 4.5 (Sept 29): Most capable for coding, agents, computer use
• Haiku 4.5 (Oct 15): Small, fast, low-latency model

import { anthropic } from '@ai-sdk/anthropic';
const sonnet45 = anthropic('claude-sonnet-4-5-20250929');  // Latest
const opus41 = anthropic('claude-opus-4-1-20250805');
const haiku45 = anthropic('claude-haiku-4-5-20251015');

Google

Gemini 2.5 Family (Mar-Sept 2025):

• Pro (March 2025): Most intelligent, #1 on LMArena at launch
• Pro Deep Think (May 2025): Enhanced reasoning mode
• Flash (May 2025): Fast, cost-effective
• Flash-Lite (Sept 2025): Updated efficiency

import { google } from '@ai-sdk/google';
const pro = google('gemini-2.5-pro');
const flash = google('gemini-2.5-flash');
const lite = google('gemini-2.5-flash-lite');

---

Core Functions

Text Generation

generateText() - Text completion with tools streamText() - Real-time streaming

Structured Output (v6 Output API)

Output.object() - Typed objects with Zod schema (replaces generateObject) Output.array() - Typed arrays Output.choice() - Enum selection Output.json() - Unstructured JSON

See "AI SDK 6" section above for usage examples.

Multi-Modal Capabilities

Speech Synthesis (Text-to-Speech)

import { experimental_generateSpeech as generateSpeech } from 'ai';
import { openai } from '@ai-sdk/openai';

const result = await generateSpeech({
  model: openai.speech('tts-1-hd'),
  voice: 'alloy',
  text: 'Hello, how can I help you today?',
});

// result.audio is an ArrayBuffer containing the audio
const audioBuffer = result.audio;

Supported Providers:

• OpenAI: tts-1, tts-1-hd, gpt-4o-mini-tts
• ElevenLabs: eleven_multilingual_v2, eleven_turbo_v2
• LMNT, Hume

Transcription (Speech-to-Text)

import { experimental_transcribe as transcribe } from 'ai';
import { openai } from '@ai-sdk/openai';

const result = await transcribe({
  model: openai.transcription('whisper-1'),
  audio: audioFile, // File, Blob, ArrayBuffer, or URL
});

console.log(result.text); // Transcribed text
con

---

*Content truncated.*