Vercel AI SDK Guide for Next.js Streaming and Multi-Step Agents

Master the Vercel AI SDK in Next.js App Router. Learn streamText, useChat, generateObject with Zod, multi-step tool agents, and multi-provider integration.

Mahmudul Haque Qudrati — CEO & ML Engineer at Pristren

Mahmudul Haque Qudrati

CEO & ML Engineer

May 18, 2026
11 min read
Vercel AI SDK Guide for Next.js Streaming and Multi-Step Agents Cover Graphic

Why the Vercel AI SDK Accelerates Full-Stack Engineering

Building artificial intelligence features into full-stack web applications involves repetitive boilerplate. Developers must manually handle server-sent event protocols, chunked response buffering, streaming React state synchronization, model provider API differences, and schema parsing errors.

The Vercel AI SDK eliminates this complexity by providing a unified, type-safe library for Node.js, Next.js, and modern frontend frameworks. It abstracts model providers behind standard function signatures while exposing ergonomic React hooks for real-time user interfaces.

Whether your application calls OpenAI, Anthropic, Google Gemini, or local models via Ollama, the Vercel AI SDK allows you to swap providers by changing a single import statement while preserving identical frontend streaming state.


The Core Primitives of the Vercel AI SDK

The SDK organizes artificial intelligence engineering into four distinct operational primitives.

The Unified Model Provider Layer

Every frontier model provider uses proprietary request schemas, header formats, and error codes. The SDK normalizes these interfaces under official provider packages:

typescript
import { openai } from "@ai-sdk/openai";
import { anthropic } from "@ai-sdk/anthropic";
import { google } from "@ai-sdk/google";

// Standardized model instantiation
const primaryModel = openai("gpt-4o");
const fallbackModel = anthropic("claude-3-5-sonnet-latest");
const researchModel = google("gemini-1.5-pro");

Server-Side Generation and Streaming

The core server functions are streamText for token streaming and generateText for non-streaming batch jobs. Both functions accept standardized parameters including system prompts, message histories, temperature, and external tool definitions.

Structured Object Generation with Zod

The generateObject and streamObject functions force models to return structured JSON adhering to TypeScript-validated Zod schemas. If the model returns malformed JSON, the SDK handles correction retries automatically.

Client-Side Reactive Hooks

On the browser client, hooks like useChat and useCompletion manage conversational state, optimistic updates, request cancellations, and token streaming without custom WebSocket infrastructure.


Implementing Real-Time Chat Streaming in Next.js App Router

The most common architectural pattern pairs an App Router Route Handler with a client-side chat interface.

The Server Route Handler

In your Next.js API route, invoke streamText and transform the result into an HTTP response using toDataStreamResponse:

typescript
// app/api/chat/route.ts
import { streamText } from "ai";
import { openai } from "@ai-sdk/openai";

export const maxDuration = 30;

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = streamText({
    model: openai("gpt-4o"),
    system: "You are an expert full-stack TypeScript engineer.",
    messages,
    onFinish({ usage, text }) {
      console.log(`Generated ${usage.totalTokens} tokens. Prompt tokens: ${usage.promptTokens}`);
    },
  });

  return result.toDataStreamResponse();
}

The toDataStreamResponse method sets necessary HTTP headers, including Transfer-Encoding chunked and Content-Type text/plain, ensuring streaming tokens pass through edge proxies without buffering delays.

The React Client Component

On the client, useChat coordinates user message submissions and streaming responses:

tsx
// components/ChatInterface.tsx
"use client";

import { useChat } from "ai/react";

export function ChatInterface() {
  const { messages, input, handleInputChange, handleSubmit, isLoading, stop } = useChat({
    api: "/api/chat",
  });

  return (
    <div className="flex flex-col h-[600px] border rounded-lg p-4 bg-white">
      <div className="flex-1 overflow-y-auto space-y-4 mb-4">
        {messages.map((message) => (
          <div
            key={message.id}
            className={`p-3 rounded-md ${
              message.role === "user" ? "bg-blue-50 text-blue-900" : "bg-gray-100 text-gray-900"
            }`}
          >
            <span className="font-semibold capitalize">{message.role}: </span>
            <span>{message.content}</span>
          </div>
        ))}
      </div>

      <form onSubmit={handleSubmit} className="flex gap-2">
        <input
          value={input}
          onChange={handleInputChange}
          placeholder="Ask an engineering question..."
          className="flex-1 border rounded px-3 py-2 text-sm"
          disabled={isLoading}
        />
        {isLoading ? (
          <button
            type="button"
            onClick={stop}
            className="bg-red-600 text-white px-4 py-2 rounded text-sm font-medium"
          >
            Stop
          </button>
        ) : (
          <button
            type="submit"
            className="bg-black text-white px-4 py-2 rounded text-sm font-medium"
          >
            Send
          </button>
        )}
      </form>
    </div>
  );
}

The useChat hook automatically appends streamed text deltas to the active assistant message, maintaining sixty frames-per-second UI fluidity.


Type-Safe Structured Data Extraction with generateObject

Unstructured natural language answers often fail in production workflows where databases require rigid typing. The SDK guarantees typed outputs through Zod integration.

Extracting Strongly Typed Schemas

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

const UserTicketSchema = z.object({
  category: z.enum(["billing", "bug", "feature_request"]),
  urgency: z.enum(["low", "medium", "high", "critical"]),
  detectedEntities: z.array(z.string()),
  recommendedAction: z.string(),
  estimatedResolutionMinutes: z.number(),
});

export async function triageSupportTicket(ticketText: string) {
  const { object } = await generateObject({
    model: openai("gpt-4o"),
    schema: UserTicketSchema,
    prompt: `Analyze this customer support communication: ${ticketText}`,
  });

  // Fully typed as z.infer<typeof UserTicketSchema>
  console.log(object.category);
  console.log(object.urgency);
  return object;
}

Behind the scenes, the SDK configures model provider JSON schemas and enforces validation. If the model emits incomplete fields, the SDK triggers targeted repair attempts.


Multi-Step Autonomous Agents with Tool Calling

Modern agentic workflows require models to call external tools, inspect returned data, and decide whether further actions are necessary.

Configuring Tools and Multi-Step Execution

Using the tool helper and maxSteps configuration, you build autonomous agents that resolve complex multi-turn inquiries:

typescript
import { streamText, tool } from "ai";
import { anthropic } from "@ai-sdk/anthropic";
import { z } from "zod";

export async function runResearchAgent(query: string) {
  const result = streamText({
    model: anthropic("claude-3-5-sonnet-latest"),
    system: "You are an autonomous research agent. Use tools to gather facts before composing final answers.",
    prompt: query,
    maxSteps: 5, // Allows the agent to take up to 5 tool call rounds
    tools: {
      searchKnowledgeBase: tool({
        description: "Search internal technical documentation by keyword query",
        parameters: z.object({
          query: z.string(),
        }),
        execute: async ({ query }) => {
          // Simulated internal vector search lookup
          return [
            { docId: "auth-101", title: "OAuth PKCE Flow", content: "PKCE requires code_verifier." },
            { docId: "auth-102", title: "Token Refresh", content: "Refresh tokens expire after 30 days." },
          ];
        },
      }),
      sendNotification: tool({
        description: "Dispatch an alert notification to team Slack channels",
        parameters: z.object({
          channel: z.string(),
          message: z.string(),
        }),
        execute: async ({ channel, message }) => {
          return { status: "delivered", timestamp: new Date().toISOString() };
        },
      }),
    },
  });

  return result.toDataStreamResponse();
}

Setting maxSteps activates the agentic execution loop. The model emits a tool call, the SDK executes the asynchronous execute handler, feeds the resulting JSON back to the model, and continues generation until the model completes its final response. For additional tool integration patterns, see our guide on function calling in LLMs.


Handling Multi-Modal Attachments and File Uploads

Modern AI applications frequently process images, diagrams, and PDF files alongside conversational user prompts. The Vercel AI SDK provides native primitives for client-side file selection and server-side multi-modal parsing.

Client-Side Attachment Handling

On the frontend, useChat exposes an attachments state that accepts FileList objects directly:

tsx
// components/MultiModalChat.tsx
"use client";

import { useChat } from "ai/react";
import { useRef, useState } from "react";

export function MultiModalChat() {
  const [files, setFiles] = useState<FileList | null>(null);
  const fileInputRef = useRef<HTMLInputElement>(null);
  const { messages, input, handleInputChange, handleSubmit } = useChat();

  return (
    <form
      onSubmit={(e) => {
        handleSubmit(e, {
          experimental_attachments: files ?? undefined,
        });
        setFiles(null);
        if (fileInputRef.current) fileInputRef.current.value = "";
      }}
    >
      <input
        type="file"
        ref={fileInputRef}
        onChange={(e) => setFiles(e.target.files)}
        multiple
        accept="image/*,application/pdf"
      />
      <input value={input} onChange={handleInputChange} placeholder="Describe this architecture diagram..." />
      <button type="submit">Send Analysis Request</button>
    </form>
  );
}

Server-Side Multi-Modal Stream Processing

In the backend Route Handler, the SDK converts uploaded file buffers into standard multi-modal message parts:

typescript
import { streamText } from "ai";
import { google } from "@ai-sdk/google";

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = streamText({
    model: google("gemini-1.5-pro"),
    messages,
  });

  return result.toDataStreamResponse();
}

The SDK automatically serializes base64 image strings and file attachments into the exact data structures expected by Google Gemini, OpenAI, or Anthropic models.


Server Actions Integration for Zero-API Workflows

While Route Handlers work well for chat interfaces, Next.js Server Actions allow you to run server-side generation directly from button clicks and form submissions without writing API routes.

Invoking AI Generation in Server Actions

typescript
// app/actions/ai-actions.ts
"use server";

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

export async function generateProductSummary(description: string) {
  if (!description || description.length < 10) {
    throw new Error("Invalid product description length.");
  }

  const { text } = await generateText({
    model: openai("gpt-4o-mini"),
    system: "You write concise, high-converting e-commerce product summaries.",
    prompt: description,
  });

  return { summary: text };
}

In your client forms, call generateProductSummary directly using React transition hooks:

tsx
"use client";

import { useState, useTransition } from "react";
import { generateProductSummary } from "@/app/actions/ai-actions";

export function SummaryGenerator() {
  const [description, setDescription] = useState("");
  const [summary, setSummary] = useState("");
  const [isPending, startTransition] = useTransition();

  function handleGenerate() {
    startTransition(async () => {
      const result = await generateProductSummary(description);
      setSummary(result.summary);
    });
  }

  return (
    <div className="space-y-3">
      <textarea
        value={description}
        onChange={(e) => setDescription(e.target.value)}
        className="w-full border p-2 rounded text-sm"
        placeholder="Enter product details..."
      />
      <button
        onClick={handleGenerate}
        disabled={isPending}
        className="bg-black text-white px-4 py-2 rounded text-sm font-medium"
      >
        {isPending ? "Generating..." : "Generate Summary"}
      </button>
      {summary && <p className="p-3 bg-gray-50 rounded border text-sm">{summary}</p>}
    </div>
  );
}

To review Server Action best practices and cache revalidation, review our comprehensive deep-dive on Next.js Server Actions.


Production Observability and Telemetry Integration

Running generative AI in high-scale production requires continuous monitoring of latency, token budgets, and error rates across all model calls.

Instrumenting Telemetry with onFinish Callbacks

The streamText primitive exposes execution hooks that capture detailed operational telemetry without degrading client streaming speeds:

typescript
import { streamText } from "ai";
import { openai } from "@ai-sdk/openai";

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = streamText({
    model: openai("gpt-4o"),
    messages,
    async onFinish({ usage, finishReason, text, response }) {
      // Record telemetry in database or monitoring platform
      await recordMetrics({
        model: response.modelId,
        promptTokens: usage.promptTokens,
        completionTokens: usage.completionTokens,
        totalTokens: usage.totalTokens,
        finishReason,
        timestamp: new Date().toISOString(),
      });
    },
  });

  return result.toDataStreamResponse();
}

This data allows teams to track daily token consumption, identify anomalous runaway prompts, and calculate accurate unit economics per feature.


Multi-Provider Fallbacks and Error Handling

Production web applications must safeguard against downstream provider rate limits and unexpected downtime.

Fallback Model Pipeline Architecture

You can structure dynamic fallbacks using standard try-catch blocks or wrapper functions:

typescript
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
import { anthropic } from "@ai-sdk/anthropic";

export async function executeResilientGeneration(prompt: string) {
  try {
    // Primary attempt using OpenAI
    return await generateText({
      model: openai("gpt-4o"),
      prompt,
    });
  } catch (error) {
    console.warn("Primary model provider failed. Falling back to Anthropic...", error);
    // Automatic fallback to Claude
    return await generateText({
      model: anthropic("claude-3-5-sonnet-latest"),
      prompt,
    });
  }
}

For detailed pricing breakdowns and token reduction techniques across providers, review our complete guide on cutting LLM API costs. To explore direct provider parameters, explore our dedicated OpenAI API guide and Anthropic API guide.


Frequently Asked Questions

What is the difference between streamText and generateText?

streamText returns a readable stream that delivers tokens progressively to the client as they generate, providing real-time responsiveness. generateText awaits the complete model output before returning the finalized string, making it better suited for background batch jobs and headless tasks.

How does useChat handle conversation history?

The useChat hook maintains an internal message array containing user inputs, assistant outputs, and tool call states. When the user sends a new message, useChat transmits the entire message array to the designated API route, ensuring multi-turn conversational context is preserved.

Can the Vercel AI SDK work with local open-source models?

Yes. The SDK supports local models via community providers like ollama-ai-provider or any OpenAI-compatible server endpoint. You configure the custom baseURL pointing to your local instance while utilizing standard SDK hooks.

How does generateObject ensure JSON schema compliance?

generateObject instructs the model to format responses using constrained grammar rules or provider-native JSON schema modes. It parses output through a Zod validator and returns TypeScript-inferred types, automatically triggering repair prompts if formatting errors occur.

Does the Vercel AI SDK require hosting on Vercel?

No. The Vercel AI SDK is an open-source TypeScript library that runs in any Node.js, Next.js, Docker container, or self-hosted server environment, including AWS, Google Cloud, and private virtual machines.


Build Production-Ready AI Applications Today

Modern artificial intelligence should feel integrated and instantaneous. By leveraging the Vercel AI SDK, engineering teams can build resilient streaming interfaces, enforce schema validation, and deploy multi-step agents in record time.

Transform your team workflows with Zlyqor. Zlyqor consolidates developer sprint tracking, project roadmaps, team communication, and automated AI meeting summaries into one high-performance workspace. Start your free trial today and empower your engineering organization to ship faster.

Frequently Asked Questions

What is the difference between streamText and generateText?

streamText returns a readable stream that delivers tokens progressively to the client as they generate, providing real-time responsiveness. generateText awaits the complete model output before returning the finalized string, making it better suited for background batch jobs and headless tasks.

How does useChat handle conversation history?

The useChat hook maintains an internal message array containing user inputs, assistant outputs, and tool call states. When the user sends a new message, useChat transmits the entire message array to the designated API route, ensuring multi-turn conversational context is preserved.

Can the Vercel AI SDK work with local open-source models?

Yes. The SDK supports local models via community providers like ollama-ai-provider or any OpenAI-compatible server endpoint. You configure the custom baseURL pointing to your local instance while utilizing standard SDK hooks.

How does generateObject ensure JSON schema compliance?

generateObject instructs the model to format responses using constrained grammar rules or provider-native JSON schema modes. It parses output through a Zod validator and returns TypeScript-inferred types, automatically triggering repair prompts if formatting errors occur.

Does the Vercel AI SDK require hosting on Vercel?

No. The Vercel AI SDK is an open-source TypeScript library that runs in any Node.js, Next.js, Docker container, or self-hosted server environment, including AWS, Google Cloud, and private virtual machines.

#vercel-ai-sdk#next.js#streaming#typescript#tool-calling#ai-agents

One AI engineering post, weekly

LLM benchmarks, prompt techniques, and token-cost breakdowns, delivered to your inbox.

What should we test or explain next?

Comments

Have a question or something to add? Sign in to join the discussion.

Mahmudul Haque Qudrati — CEO & ML Engineer at Pristren

Mahmudul Haque Qudrati

CEO & ML Engineer

Visionary technologist, software engineer, and machine learning specialist. Founder and CEO of Pristren, directing engineering teams that ship production-grade AI/ML pipelines, mission-critical full-stack applications, and developer tooling. Creator of Zlyqor, the unified team workspace platform. Author of 540+ technical guides and benchmark research reports on large language models, agentic workflows, Model Context Protocol (MCP), and modern web stacks.

PristrenZlyqor