The Complete Guide to the Vercel AI SDK

The Complete Guide to the Vercel AI SDK

Building AI Applications and Agents with TypeScript — from First Token to Production

Load this book when:

• You are building an AI feature in TypeScript/JavaScript with the Vercel AI SDK (ai package) — chat, text/structured generation, tool calling, agents, embeddings, or multimodal I/O.
• You are deciding between provider SDKs and need one provider-agnostic API, or routing models through the Vercel AI Gateway.
• You are building agents (the agent loop, ToolLoopAgent, loop control, memory, subagents, approvals, durable workflows).
• You are building a streaming chat or generative UI with useChat / useObject / useCompletion (React, Vue, Svelte) and a Next.js / Express / Hono / Fastify / Nest.js backend.
• You are integrating MCP servers, structured output (Output.*), middleware, telemetry, or testing AI code.
• You are migrating an existing app across AI SDK v3 → v6 and need the renames and breaking-change checklist.

Targets the AI SDK 6 generation of the ai package (current API names throughout).

---

Preface

The Vercel AI SDK is a provider-agnostic TypeScript toolkit for building AI-powered applications and agents. It runs everywhere modern JavaScript runs — React, Next.js, Vue, Svelte, Node.js, and the edge — and it has become one of the most widely used ways to talk to large language models from JavaScript, with millions of weekly downloads.

Its promise is simple: write your AI logic once, against one unified API, and swap models and providers with a string. Underneath that promise is a deep, fast-moving toolkit covering text and structured generation, tool calling, autonomous agents, multimodal input and output, streaming chat interfaces, and a model gateway. This book is the map.

Who this book is for. TypeScript and JavaScript developers building real AI features: chatbots, RAG systems, structured-extraction pipelines, and autonomous agents. You should be comfortable with async/await, modern ES modules, and — for the UI chapters — React and Next.js. You do not need prior machine-learning experience.

What it covers. This book targets the current generation of the SDK (versions 5 and 6, the ai package). It is built directly on the official documentation and supplemented with production best practices, common pitfalls, and version-migration notes drawn from Vercel's engineering guidance and the wider community. Where behavior is version-specific, the text says so.

How to read it. The book is organized in six parts that move from fundamentals to production:

• Part I — Foundations orients you: what the SDK is, how the packages fit together, and your first running call.
• Part II — AI SDK Core is the engine room: text and structured generation, tool calling, MCP, prompts and settings, embeddings, multimodal I/O, providers, middleware, and operations.
• Part III — Building Agents covers the agent loop, loop control, workflow patterns, and advanced agents (memory, subagents, approvals, skills, durable workflows).
• Part IV — AI SDK UI builds the front end: useChat, persistence and resumable streams, tool UIs, generative interfaces, and framework integration.
• Part V — Providers & the AI Gateway covers the Gateway as your default abstraction and deep-dives the major providers.
• Part VI — Production & Projects brings it together with a best-practices chapter and five end-to-end builds, followed by an error reference and a migration guide.

Read Parts I and II in order if you are new to the SDK; after that, each chapter stands on its own and cross-references the others by name. Every code example is grounded in the current API — no invented functions, no aspirational pseudo-code.

A note on versions: the SDK moves fast. Several APIs were renamed between v5 and v6 (for example generateObject gave way to Output.object, and the agent class became ToolLoopAgent). This book uses the current names throughout and flags the important changes in Appendix B.

---

Currency & scope. Last verified: 2026-06-14, against AI SDK 6 (latest [email protected] at time of writing). The ai package moves fast; treat any specific API name, default, model id, or providerOptions value as accurate for the v6 line and re-verify against ai-sdk.dev before relying on it past a major version bump. Refresh cadence: review on every AI SDK major release and at least quarterly (fast-moving / tactical surface — Writing Books for AI Agents, RULE 14.4). Audience: public marketplace reference book; built on and attributed to Vercel's official AI SDK documentation and the AI SDK 6 announcement.

Companion: authored to the standards in Writing Books for AI Agents (CandleKeep ID cmqdpn0oo01e4rv0z0kitugn2, Ch 14 currency, Ch 17 self-audit). Version horizon: v6 ([email protected]) is the current stable line; an AI SDK v7 line is in active docs (native WorkflowAgent, @ai-sdk/workflow). Re-audit this book against v7 on its stable release before treating any v6-specific durable-agent or message API as current.

Table of Contents

Part I — Foundations

• Chapter 1 — What the Vercel AI SDK Is and Why It Exists
• Chapter 2 — The Library Landscape & Getting Started

Part II — AI SDK Core

• Chapter 3 — Generating and Streaming Text
• Chapter 4 — Generating Structured Data
• Chapter 5 — Tool Calling
• Chapter 6 — Model Context Protocol (MCP) and Tool Context
• Chapter 7 — Prompt Engineering, Settings, and Reasoning
• Chapter 8 — Embeddings and Reranking
• Chapter 9 — Multimodal Generation: Images, Speech, Transcription, Video, and Files
• Chapter 10 — Provider and Model Management
• Chapter 11 — Language Model Middleware
• Chapter 12 — Error Handling, Testing, Telemetry, and DevTools

Part III — Building Agents

• Chapter 13 — Agent Fundamentals: The Agent Loop and Loop Control
• Chapter 14 — Workflow Patterns
• Chapter 15 — Advanced Agents: Memory, Subagents, Approvals, Skills, and DurableAgent (Workflow DevKit)

Part IV — AI SDK UI

• Chapter 16 — Building Chatbots with useChat
• Chapter 17 — Persistence, Resumable Streams, and Transports
• Chapter 18 — Tool Usage and Human-in-the-Loop in the UI
• Chapter 19 — Generative User Interfaces
• Chapter 20 — Completion, Object Generation, and Custom Data Streaming
• Chapter 21 — Framework and Server Integration

Part V — Providers & the AI Gateway

• Chapter 22 — The Vercel AI Gateway
• Chapter 23 — Provider Deep-Dives

Part VI — Production & Projects

• Chapter 24 — Production Best Practices
• Chapter 25 — End-to-End Projects

Appendices

• Appendix A — Error Reference
• Appendix B — Migration Guide (v3 → v6)

---

---