Vercel AI SDK

The Vercel AI SDK is a powerful toolkit for building AI-powered applications in TypeScript and JavaScript. It provides unified APIs for text generation, streaming, chatbot interfaces, tool calling, structured data generation, and multi-provider support. The SDK abstracts away provider differences, enabling seamless integration with OpenAI, Anthropic, Mistral, and other AI models through a consistent interface.

Quick Start

Installation

bash

npm install ai

Basic Patterns

Text Generation

typescript

import { generateText } from 'ai';

const { text } = await generateText({
  model: yourModel,
  prompt: 'Write a story about a robot learning to love'
});

Streaming

typescript

import { streamText } from 'ai';

const result = await streamText({
  model: yourModel,
  prompt: 'Explain quantum computing'
});

for await (const textPart of result.textStream) {
  console.log(textPart);
}

Building Chatbots

typescript

import { useChat } from 'ai/react';

const { messages, input, handleInputChange, handleSubmit } = useChat();

Tool Calling

typescript

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

const { text } = await generateText({
  model: yourModel,
  tools: {
    weather: tool({
      description: 'Get weather for a location',
      parameters: z.object({
        city: z.string(),
      }),
      execute: async ({ city }) => {
        return getWeather(city);
      },
    }),
  },
});

Core Workflows

Text Generation & Streaming

The SDK provides two primary functions for text generation:

generateText: Use for non-interactive generation when you need the complete result
streamText: Use for interactive applications requiring real-time streaming

Both functions support identical parameters for prompts, messages, tools, and settings. Key configurations include

maxTokens

temperature

topP

, and

stopSequences

. Always use

abortSignal

for cancellation in production applications.

Configure settings globally or per-request. Global settings apply across all calls using

defaultSettingsMiddleware

. Per-request settings override global configuration.

Error handling is built-in through callbacks (

onError

) and typed error objects (

AIError

NoTextGeneratedError

). Enable warning logging with

globalThis.AI_SDK_LOG_WARNINGS = true

References:

references/Generating-and-Streaming-Text.md

references/Settings.md

references/Error-Handling&warnings.md

Building Chatbots & UI

The

useChat

hook provides complete chatbot functionality with real-time streaming, state management, and error handling.

Core Features

Automatic message state management
Real-time streaming from server to client
Built-in error handling and retry logic
Support for tool usage and approvals
Message persistence and resumable streams
Custom transport configuration

Additional Hooks

useCompletion: For text completion interfaces (non-chat)
useObject: For streaming structured JSON object generation
readUIMessageStream: For terminal UIs and custom stream processing

Generative UI: Build interfaces where LLMs generate React components dynamically. Use tools that return UI components, then render them in the chat interface with proper streaming and state reconciliation.

Message Persistence: Store messages server-side using

generateId()

for unique IDs. Validate messages with

validateUIMessages()

before storage. Implement message loading and saving with automatic UI updates.

Resumable Streams: Enable users to reconnect to ongoing AI generation using Redis storage and custom API endpoints. Stream context persists across disconnections.

Transport Layer: Customize message transmission with

DefaultChatTransport

or custom implementations. Configure headers, body preparation, and streaming behavior.

References:

references/Chatbot.md

references/Chatbot-Tool-Usage.md

references/Chatbot-Message-Persistence.md

references/Chatbot-Resume-Streams.md

references/Completion.md

references/Generative-User-Interfaces.md

references/Object-Generation.md

references/Transport.md

Tool Calling

Tool calling enables LLMs to execute functions and use the results to formulate responses.

Definition Define tools using the

tool()

function with Zod schemas for parameters:

typescript

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

const myTool = tool({
  description: 'Tool description',
  parameters: z.object({
    param1: z.string(),
    param2: z.number(),
  }),
  execute: async (params) => {
    // Tool execution logic
    return result;
  },
});

Dynamic Tools: Use

dynamicTool()

for tools determined at runtime or with dynamic parameters.

Multi-Step Tool Calling: The model can call tools multiple times in a single generation. Use

maxSteps

stepCountIs()

to control execution. Use

stopWhen()

to conditionally stop based on tool results.

Tool Approval in Chatbots: Implement server-side tools (executed automatically) and client-side tools (require user approval). Use

addToolOutput()

to provide results and

addToolApprovalResponse()

for user decisions.

Error Handling: Handle tool execution errors gracefully. The model can retry failed tools or continue based on error information.

References:

references/Tool-Calling.md

references/Chatbot-Tool-Usage.md

Structured Data Generation

Generate type-safe structured data using

Output

helpers with Zod schemas.

Output.object: Generate complete JSON objects with schema validation

typescript

const { object } = await generateText({
  model: yourModel,
  output: Output.object({
    schema: z.object({
      name: z.string(),
      age: z.number(),
    }),
  }),
});

Output.array: Generate arrays with typed elements Output.choice: Generate single values from a defined set of options Output.json: Flexible JSON generation when schema is less strict

For streaming structured data, use

useObject

hook with real-time partial updates. The UI receives incrementally updated objects as generation progresses.

Best Practices: Use clear schema descriptions, leverage

.describe()

for field documentation, and test schema robustness with edge cases. Consider provider compatibility when designing complex schemas.

References:

references/Generating-Structured-Data.md

references/Object-Generation.md

references/Prompt-Engineering.md

Provider Configuration

Provider Registry: Manage multiple providers with

createProviderRegistry()

. Configure different providers for different use cases and switch between them using model aliases.

Custom Providers: Build custom providers using the Provider V3 specification. Implement

LanguageModelV3

interface with

doGenerate

and

doStream

methods. Use helper functions like

postJsonToApi

for HTTP requests.

Model Settings: Configure default settings per-provider using

defaultSettingsMiddleware

. Apply temperature, max tokens, and other configurations automatically.

Multi-Provider Setups: Use

wrapLanguageModel

to chain providers, add telemetry, or modify parameters. Combine multiple providers for A/B testing or fallback strategies.

References:

references/Provider&Model-Management.md

references/Writing-Custom-Provider.md

Advanced Features

Language Model Middleware: Intercept and modify all language model calls using

wrapLanguageModel()

. Built-in middleware includes

extractReasoningMiddleware

and

defaultSettingsMiddleware

. Create custom middleware for logging, parameter transformation, or response modification.

Model Context Protocol (MCP): Connect to MCP servers providing tools, resources, and prompts. Use

createMCPClient()

with HTTP, SSE, or stdio transports. Access tools via

mcpClient.tools

and resources via

mcpClient.listResources()

Telemetry: Enable OpenTelemetry observability with

experimental_telemetry

. Collect spans, attributes, and metrics from

generateText

streamText

, and other SDK functions.

Testing: Use

MockLanguageModelV3

and

MockEmbeddingModelV3

for deterministic testing without real LLM calls. Simulate streaming with

simulateReadableStream()

Stream Protocols: Understand how data streams from backend to frontend using AI SDK protocols. Use

toUIMessageStreamResponse

and

toTextStreamResponse

helpers.

Custom Data Streaming: Stream application data alongside AI responses using

createUIMessageStream()

and

writer.write()

. Handle data reconciliation with client-side

onData

callbacks.

References:

references/Language-Model-Middleware.md

references/Model-Context-Protocol(MCP).md

references/Telemetry.md

references/Testing.md

references/Stream-Protocols.md

references/Streaming-Custom-Data.md

Media Processing

Embeddings: Generate embeddings with

embed()

or batch with

embedMany()

. Calculate similarity with

cosineSimilarity()

. Wrap embedding models with

wrapEmbeddingModel()

for customization.

Reranking: Improve search relevance with

rerank()

. Reorder documents using specialized models from Cohere, Bedrock, or other providers.

Image Generation: Generate images with

generateImage()

. Handle

NoImageGeneratedError

for failed generations. Configure providers like OpenAI or Vertex.

Speech: Generate speech with

experimental_generateSpeech()

. Support for multiple speech providers including OpenAI and LMNT.

Transcription: Transcribe audio to text with

experimental_transcribe()

. Handle

NoTranscriptGeneratedError

for empty results.

References:

references/Embeddings.md

references/Reranking.md

references/Image-Generation.md

references/Speech.md

references/Transcription.md

Key APIs by Category

Core APIs

generateText: Generate complete text non-interactively
streamText: Stream text for interactive applications
smoothStream: Smooth streaming for better UX
Output.object: Generate structured JSON objects
Output.array: Generate typed arrays
Output.choice: Generate from predefined choices
Output.json: Flexible JSON generation
tool: Define tools with Zod schemas
dynamicTool: Define runtime-dynamic tools
stopWhen: Conditionally stop tool execution
stepCountIs: Control multi-step tool calling

UI Hooks

useChat: Build chatbots with streaming and state management
useCompletion: Text completion interface
useObject: Stream structured JSON objects
readUIMessageStream: Process streams for custom UIs
DefaultChatTransport: Configure chat message transmission
prepareSendMessagesRequest: Prepare chat API requests

Provider & Model Management

customProvider: Create custom AI providers
createProviderRegistry: Manage multiple providers
wrapLanguageModel: Middleware for language models
defaultSettingsMiddleware: Apply default model settings
transformParams: Transform request parameters

Advanced Features

createMCPClient: Connect to MCP servers
experimental_telemetry: Enable OpenTelemetry
MockLanguageModelV3: Test with mocked language models
simulateReadableStream: Test streaming behavior
createUIMessageStream: Custom data streaming
extractReasoningMiddleware: Extract model reasoning

Media APIs

embed: Generate single embedding
embedMany: Generate batch embeddings
cosineSimilarity: Calculate embedding similarity
rerank: Reorder documents by relevance
generateImage: Generate images from text
experimental_generateSpeech: Text-to-speech generation
experimental_transcribe: Audio-to-text transcription

Utility & Configuration

maxTokens, temperature, topP: Configure generation parameters
abortSignal: Cancel ongoing requests
onError: Handle errors globally
validateUIMessages: Validate chat messages
generateId: Generate unique message IDs
toUIMessageStreamResponse: Format UI message streams
toTextStreamResponse: Format text streams

When to Reference Original Docs

Consult detailed documentation in the

references/

directory for:

Core Implementation Details

Generating-and-Streaming-Text.md: Deep dive into text generation, streaming transformations, and advanced patterns
Settings.md: Complete reference for all configuration options and their effects
Error-Handling&warnings.md: Comprehensive error handling strategies and warning types
Prompt-Engineering.md: Best practices for prompts, tools, and schema design

Chatbot & UI Development

Chatbot.md: Complete chatbot implementation guide with all features
Chatbot-Tool-Usage.md: Server-side, client-side, and user approval tool workflows
Chatbot-Message-Persistence.md: File-based storage, validation, and ID generation
Chatbot-Resume-Streams.md: Redis-backed resumable stream implementation
Completion.md: useCompletion hook patterns and examples
Generative-User-Interfaces.md: Dynamic component generation from LLM output
Object-Generation.md: Real-time structured object streaming
Message-Metadata.md: Attach and access custom message metadata
Reading-UI-Message-Streams.md: Terminal UI patterns and custom processing
Transport.md: Custom transport implementation and configuration

Tools & Structured Data

Tool-Calling.md: Complete tool calling guide with patterns and edge cases
Generating-Structured-Data.md: All Output helpers and schema design

Provider & Advanced Features

Provider&Model-Management.md: Multi-provider setups, registries, and configuration
Writing-Custom-Provider.md: Build providers matching V3 specification
Language-Model-Middleware.md: Built-in and custom middleware patterns
Model-Context-Protocol(MCP).md: MCP client setup and usage
Stream-Protocols.md: Backend-to-frontend streaming architecture
Streaming-Custom-Data.md: Custom data streaming with reconciliation
Telemetry.md: OpenTelemetry integration and observability
Testing.md: Mock providers and test helpers

Media Processing

Embeddings.md: Embedding generation, batching, and similarity
Reranking.md: Document reranking for search relevance
Image-Generation.md: Image generation with multiple providers
Speech.md: Text-to-speech generation
Transcription.md: Audio-to-text transcription

Each reference document contains comprehensive examples, edge case handling, type signatures, and production-ready patterns. Reference them when implementing specific features or encountering complex scenarios beyond basic usage.

vercel-ai-sdk

NPX Install

Tags

SKILL.md Content

Vercel AI SDK

Quick Start

Installation

Basic Patterns

Core Workflows

Text Generation & Streaming

Building Chatbots & UI

Tool Calling

Structured Data Generation

Provider Configuration

Advanced Features

Media Processing

Key APIs by Category

Core APIs

UI Hooks

Provider & Model Management

Advanced Features

Media APIs

Utility & Configuration

When to Reference Original Docs