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 or 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.