ai-sdk-core

AI SDK Core

Production-ready backend AI with Vercel AI SDK v5.

Last Updated: 2025-11-21

Table of Contents

1. [Quick Start](#quick-start-5-minutes)
2. [Core Functions](#core-functions)
3. [Provider Setup & Configuration](#provider-setup--configuration)
4. [Tool Calling & Agents](#tool-calling--agents)
5. [Critical v4→v5 Migration](#critical-v4v5-migration)
6. [Top 12 Errors & Solutions](#top-12-errors--solutions)
7. [Production Best Practices](#production-best-practices)
8. [When to Load References](#when-to-load-references)
9. [When to Use This Skill](#when-to-use-this-skill)
10. [Dependencies & Versions](#dependencies--versions)
11. [Links to Official Documentation](#links-to-official-documentation)
12. [Templates & References](#templates--references)

Quick Start (5 Minutes)

Installation

bun add ai @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google workers-ai-provider zod  # preferred
# or: npm install ai @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google workers-ai-provider zod

Environment Variables

# .env
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_GENERATIVE_AI_API_KEY=...

First Example: Generate Text

import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const result = await generateText({
  model: openai('gpt-4-turbo'),
  prompt: 'What is TypeScript?',
});

console.log(result.text);

First Example: Streaming Chat

import { streamText } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';

const stream = streamText({
  model: anthropic('claude-sonnet-4-5-20250929'),
  messages: [
    { role: 'user', content: 'Tell me a story' },
  ],
});

for await (const chunk of stream.textStream) {
  process.stdout.write(chunk);
}

First Example: Structured Output

import { generateObject } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';

const result = await generateObject({
  model: openai('gpt-4'),
  schema: z.object({
    name: z.string(),
    age: z.number(),
    skills: z.array(z.string()),
  }),
  prompt: 'Generate a person profile for a software engineer',
});

console.log(result.object);
// { name: "Alice", age: 28, skills: ["TypeScript", "React"] }

Secure Installation

This installs 6+ AI provider packages simultaneously — a large dependency surface to audit. Before installing, follow supply chain security best practices:

• Block post-install scripts — npm config set ignore-scripts true (or Bun: disabled by default)
• Cooldown period — Wait 7 days for new package versions to be vetted by the community
• Audit before installing — Run socket package score npm <pkg> or use socket npm install <pkg> to check packages

Load the dependency-upgrade skill for full security configuration including Socket CLI integration, cooldown setup, lockfile validation, and CI enforcement.

Core Functions

Load references/core-functions.md for complete API reference of all 4 core functions.

Quick Overview

AI SDK v5 provides 4 core functions:

| Function | Output | Streaming | Use Case | |----------|--------|-----------|----------| | generateText() | Text | No | Batch processing, simple completions | | streamText() | Text | Yes | Chat UIs, long responses | | generateObject() | Structured | No | Data extraction, JSON generation | | streamObject() | Structured | Yes | Real-time forms, progressive UIs |

Basic Example

import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const result = await generateText({
  model: openai('gpt-4-turbo'),
  prompt: 'Explain quantum computing',
});

console.log(result.text);

→ Load references/core-functions.md for: Complete signatures, tool usage patterns, error handling, streaming examples, comparison table

Provider Setup & Configuration

Load references/provider-setup.md for complete setup instructions for all providers.

Quick Overview

AI SDK v5 supports 4 major providers:

| Provider | Environment Variable | Latest Models | |----------|---------------------|---------------| | OpenAI | OPENAI_API_KEY | GPT-5, GPT-4 Turbo | | Anthropic | ANTHROPIC_API_KEY | Claude Sonnet 4.5, Opus 4 | | Google | GOOGLE_GENERATIVE_AI_API_KEY | Gemini 2.5 Pro/Flash | | Cloudflare | Workers AI binding | Llama 3.1, Qwen 2.5 |

Basic Setup

import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

// API key from environment
const result = await generateText({
  model: openai('gpt-4-turbo'),
  prompt: 'Hello',
});

→ Load references/provider-setup.md for: Complete API configuration, rate limiting, error handling, Cloudflare Workers optimization, model selection guides

Tool Calling & Agents

Load references/tools-and-agents.md for complete tool and agent documentation.

Quick Overview

Tools allow models to call external functions. Agents manage multi-step workflows.

v5 Tool Changes:

• parameters → inputSchema (Zod schema)
• Tool properties: args → input, result → output
• maxSteps → stopWhen(stepCountIs(n))

Basic Tool Example

import { generateText, tool } from 'ai';
import { z } from 'zod';

const result = await generateText({
  model: openai('gpt-4'),
  tools: {
    weather: tool({
      description: 'Get weather for a location',
      inputSchema: z.object({ location: z.string() }),
      execute: async ({ location }) => {
        return { temperature: 72, condition: 'sunny' };
      },
    }),
  },
  prompt: 'What is the weather in Tokyo?',
});

→ Load references/tools-and-agents.md for: Agent class usage, multi-step execution, dynamic tools, stop conditions

Critical v4→v5 Migration

Load references/v4-to-v5-migration.md for complete migration guide.

Key Breaking Changes

AI SDK v5 has 9 major breaking changes:

• maxTokens → maxOutputTokens
• parameters → inputSchema (Zod)
• maxSteps → stopWhen(stepCountIs(n))
• CoreMessage → ModelMessage
• Package reorganization (ai/rsc → @ai-sdk/rsc)

Automated Migration

bunx ai migrate  # Auto-migrates most changes

→ Load references/v4-to-v5-migration.md for: Complete breaking changes list, migration examples, checklist, official migration guide link

Top 12 Errors & Solutions

1. AI_APICallError

Cause: API request failed (network, auth, rate limit).

Solution:

import { AI_APICallError } from 'ai';

try {
  const result = await generateText({
    model: openai('gpt-4'),
    prompt: 'Hello',
  });
} catch (error) {
  if (error instanceof AI_APICallError) {
    console.error('API call failed:', error.message);
    console.error('Status code:', error.statusCode);
    console.error('Response:', error.responseBody);

    // Check common causes
    if (error.statusCode === 401) {
      // Invalid API key
    } else if (error.statusCode === 429) {
      // Rate limit - implement backoff
    } else if (error.statusCode >= 500) {
      // Provider issue - retry
    }
  }
}

Prevention:

• Validate API keys at startup
• Implement retry logic with exponential backoff
• Monitor rate limits
• Handle network errors gracefully

2. AI_NoObjectGeneratedError

Cause: Model didn't generate valid object matching schema.

Solution:

import { AI_NoObjectGeneratedError } from 'ai';

try {
  const result = await generateObject({
    model: openai('gpt-4'),
    schema: z.object({ /* complex schema */ }),
    prompt: 'Generate data',
  });
} catch (error) {
  if (error instanceof AI_NoObjectGeneratedError) {
    console.error('No valid object generated');

    // Solutions:
    // 1. Simplify schema
    // 2. Add more context to prompt
    // 3. Provide examples in prompt
    // 4. Try different model (gpt-4 better than gpt-3.5 for complex objects)
  }
}

Prevention:

• Start wi