Vercel AI SDK

Overview

Vercel AI SDK is the official TypeScript toolkit from Vercel for building AI-powered applications. While not exclusively an agent framework, it provides powerful agent-building capabilities through its unified LLM API, tool calling, structured outputs, and streaming support.

The SDK abstracts away the differences between model providers, eliminating boilerplate code for building chatbots and AI applications. It supports 50+ LLM providers through a unified interface, making it easy to switch between providers without rewriting code.

Built specifically for the TypeScript ecosystem, Vercel AI SDK integrates seamlessly with Next.js, React, Vue, Svelte, and Node.js. It's the go-to choice for developers building AI-powered web applications in TypeScript.

Features

• Unified API for 50+ LLM Providers: Single interface for OpenAI, Anthropic, Google, Mistral, Cohere, and more
• Built-in Tool Calling: Native support for function calling with type-safe tool definitions
• Structured Outputs: Generate JSON data constrained to Zod schemas with generateObject and streamObject
• Streaming Support: Real-time streaming for chat interfaces and progressive responses
• React Hooks: useChat, useCompletion, useAssistant for AI-powered UI components
• AI Gateway: Built-in caching, rate limiting, and analytics for production deployments
• TypeScript First: Full type safety with excellent IDE autocomplete

Installation

npm install ai

For Next.js projects, also install the provider package:

npm install @ai-sdk/openai
# or
npm install @ai-sdk/anthropic
npm install @ai-sdk/google

Quick Start

Basic Text Generation

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

const { text } = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Explain the concept of quantum entanglement.',
});

console.log(text);

Tool Calling

import { generateText, tool } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';

const { text, toolResults } = await generateText({
  model: openai('gpt-4o'),
  prompt: 'What is the weather like in San Francisco and New York?',
  tools: {
    getWeather: tool({
      description: 'Get the current weather for a location',
      parameters: z.object({
        location: z.string().describe('The city name'),
      }),
      execute: async ({ location }) => {
        // Call weather API
        return { location, temperature: 72, condition: 'sunny' };
      },
    }),
  },
});

Structured Outputs

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

const { object } = await generateObject({
  model: openai('gpt-4o'),
  schema: z.object({
    recipe: z.object({
      name: z.string(),
      ingredients: z.array(z.object({
        name: z.string(),
        amount: z.string(),
      })),
      steps: z.array(z.string()),
    }),
  }),
  prompt: 'Generate a lasagna recipe.',
});

console.log(object.recipe);

React Chat Component

'use client';

import { useChat } from 'ai/react';

export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit } = useChat();

  return (
    <div>
      {messages.map(m => (
        <div key={m.id}>
          {m.role === 'user' ? 'User: ' : 'AI: '}
          {m.content}
        </div>
      ))}
      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} />
      </form>
    </div>
  );
}

Building AI Agents

While Vercel AI SDK is not a full agent framework, you can build agent-like systems using its primitives:

Simple Agent with Tool Calling

import { generateText, tool } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';

async function agent(prompt: string) {
  const { text, toolResults } = await generateText({
    model: openai('gpt-4o'),
    prompt,
    tools: {
      search: tool({ /* ... */ }),
      calculate: tool({ /* ... */ }),
      fetch: tool({ /* ... */ }),
    },
    maxSteps: 5, // Allow multiple tool calls
  });

  return { text, toolResults };
}

Multi-Step Reasoning

async function researchAgent(query: string) {
  const steps = [];
  let context = '';

  for (let i = 0; i < 3; i++) {
    const { text, toolResults } = await generateText({
      model: openai('gpt-4o'),
      prompt: `Research: ${query}\n\nContext so far: ${context}`,
      tools: { search, summarize },
      maxSteps: 3,
    });

    steps.push({ step: i, text, toolResults });
    context += text + '\n';
  }

  return { steps, finalAnswer: text };
}

Advanced Features

Streaming with React

import { useChat } from 'ai/react';

function Chat() {
  const { messages, input, handleInputChange, handleSubmit } = useChat({
    api: '/api/chat',
    onFinish: (message) => {
      console.log('Stream finished:', message);
    },
  });

  return (
    <ChatUI messages={messages} onInputChange={handleInputChange} onSubmit={handleSubmit} />
  );
}

AI Gateway Integration

import { createOpenAI } from '@ai-sdk/openai';
import { createAIGateway } from '@ai-sdk/ai-gateway';

const aiGateway = createAIGateway({
  apiKey: process.env.AIGATEWAY_API_KEY,
});

const openai = createOpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: aiGateway.baseURL,
});

Multi-Provider Fallback

import { createFallback } from '@ai-sdk/fallback';
import { openai } from '@ai-sdk/openai';
import { anthropic } from '@ai-sdk/anthropic';

const model = createFallback({
  models: [openai('gpt-4o'), anthropic('claude-3-5-sonnet-20241022')],
  fallbackStrategy: 'on-error',
});

Examples

AI-Powered Code Review

const { object } = await generateObject({
  model: openai('gpt-4o'),
  schema: z.object({
    issues: z.array(z.object({
      line: z.number(),
      severity: z.enum(['error', 'warning', 'info']),
      message: z.string(),
      suggestion: z.string(),
    })),
  }),
  prompt: `Review this code:\n\n${code}`,
});

RAG Pipeline

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

// Embed query
const { embedding } = await embed({
  model: openai('text-embedding-3-small'),
  value: userQuery,
});

// Search vector database, then generate response
const { text } = await generateText({
  model: openai('gpt-4o'),
  prompt: `Context: ${relevantDocs}\n\nQuestion: ${userQuery}`,
});

Pros

• ✅ Best-in-class TypeScript Type Safety: Full types for all operations
• ✅ Unified API: Switch providers with minimal code changes
• ✅ Next.js Integration: Seamless with App Router and Server Actions
• ✅ Excellent Documentation: Comprehensive guides and examples
• ✅ Production-Ready: AI Gateway for caching, rate limiting, analytics
• ✅ Active Development: Frequent updates and new features
• ✅ React Hooks: Ready-to-use components for chat and completion

Cons

• ❌ TypeScript/JavaScript Only: No Python or other language support
• ❌ Not a Full Agent Framework: Requires building agent logic yourself
• ❌ Vercel Ecosystem Focus: Best suited for Vercel/Next.js projects
• ❌ Limited Pre-built Tools: Fewer integrations than LangChain
• ❌ Provider-Specific Features: Some features only work with certain providers

Use Cases

Use Case	Why Vercel AI SDK
Next.js AI Apps	Native integration with Next.js App Router
TypeScript Projects	Best-in-class type safety for JS/TS
Multi-provider Apps	Switch LLM providers without code changes
Chat Interfaces	Ready-to-use React hooks for chat UIs
Structured Outputs	Zod-based schema validation for responses

Comparison with Alternatives

Feature	Vercel AI SDK	LangChain	OpenAI Agents SDK	LiteLLM
Paradigm	TypeScript SDK	Python/TS framework	Python/TS SDK	Proxy layer
TypeScript Native	✅ Yes	⚠️ Yes	✅ Yes	❌ No
Multi-provider	✅ 50+	✅ 50+	❌ OpenAI only	✅ 100+
React Hooks	✅ Yes	❌ No	❌ No	❌ No
Structured Outputs	✅ Zod-based	⚠️ Via tools	✅ JSON schema	❌ No
Learning Curve	Low	High	Low	Low
Best for	TS/Next.js apps	Complex apps	OpenAI apps	Provider routing

Best Practices

1. Use generateObject for structured data — Zod schemas ensure valid output
2. Leverage useChat for UI — Built-in React hooks for chat interfaces
3. Set maxSteps for agent behavior — Allow multiple tool calls per prompt
4. Use AI Gateway for production — Caching, rate limiting, analytics
5. Implement provider fallback — Use fallback models for reliability
6. Stream for better UX — Use streamObject for progressive output

Troubleshooting

Issue	Solution
Type errors	Ensure Zod schema matches expected output
Tool calling fails	Verify tool function is async and returns proper format
Streaming issues	Check useChat API endpoint configuration
Provider not found	Install corresponding @ai-sdk/* package
Structured output invalid	Use schema instead of output for Zod validation

Resources

• Official Documentation
• GitHub Repository
• AI SDK Cookbook
• Vercel AI Templates
• AI Gateway Docs