Skip to content
The Complete Guide to the Vercel AI SDK
On Trove · from Matan Marudi

The Complete Guide to the Vercel AI SDK

A comprehensive guide to building AI-powered applications and agents with the Vercel AI SDK (v6) using TypeScript.

Read a preview

You can read the contents and the first 2,000 characters.
Free accounts get the whole book.

  • By Matan Marudi
  • 29 chapters
  • Updated Nov 3, 2026
  • 26 readers

What’s inside

  • Navigation — Decision Matrix
  • What the Vercel AI SDK Is and Why It Exists
  • The Library Landscape & Getting Started
  • Generating and Streaming Text
  • Generating Structured Data
  • Tool Calling

What is The Complete Guide to the Vercel AI SDK?

A comprehensive guide to building AI-powered applications and agents with the Vercel AI SDK (v6) using TypeScript, covering text and structured generation, tool calling, agents (ToolLoopAgent), streaming chat, multimodal I/O, the AI Gateway, provider integration, and production patterns. Load when building AI features in JavaScript/TypeScript or migrating across SDK versions.

Read more

markdown · Listed Jun 17, 2026

From the first page

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.

Preview · 2,000 of 554,363 characters

Replicating Anthropic's Self-Service Analytics: A Practitioner's Implementation Guide
Vercel Frontend Engineering Guidelines
Bambu Lab P2S & P1S Complete Reference: Settings, Calibration & Enclosed Printing for Claude Code
FluxCD Official Documentation: The Complete Guide to GitOps on Kubernetes

Contents

  1. 01The Complete Guide to the Vercel AI SDKp.1
    1. Prefacep.1
    2. Table of Contentsp.1
  2. 02Navigation — Decision Matrixp.2
  3. 03What the Vercel AI SDK Is and Why It Existsp.3
    1. The problem: provider lock-in and fragmented APIsp.3
    2. What the AI SDK solvesp.3
    3. The two layers: AI SDK Core and AI SDK UIp.3
    4. Supported runtimes and frameworksp.3
    5. What's new in AI SDK 5 and 6p.3
    6. Key takeawaysp.3
  4. 04The Library Landscape & Getting Startedp.4
    1. The package ecosystemp.4
    2. The AI Gateway as the default providerp.4
    3. Installationp.4
    4. Environment and API-key setupp.4
    5. Your first `generateText` callp.4
    6. A minimal Next.js streaming routep.4
    7. Streaming from non-Next.js serversp.4
    8. How the pieces fit together and what to installp.4
    9. +1 more section
  5. 05Generating and Streaming Textp.5
    1. `generateText` — single-shot generationp.5
    2. `streamText` — incremental generationp.5
    3. Handling long generationsp.5
    4. When to stream and when not top.5
    5. Key takeawaysp.5
  6. 06Generating Structured Datap.6
    1. Generating a structured objectp.6
    2. Output strategiesp.6
    3. Improving accuracy: property descriptions, names, and reasoningp.6
    4. Streaming structured outputp.6
    5. Streaming objects to the client with `useObject`p.6
    6. Structured output via tools vs. `output`p.6
    7. Validating and repairing output, and error handlingp.6
    8. Key takeawaysp.6
  7. 07Tool Callingp.7
    1. What a tool isp.7
    2. How the model decides to call a toolp.7
    3. Single vs. multi-step calls with `stopWhen`p.7
    4. Accessing tool calls and resultsp.7
    5. Response messagesp.7
    6. `toolChoice`p.7
    7. Tool execution optionsp.7
    8. Streaming tool callsp.7
    9. +10 more sections
  8. 08Model Context Protocol (MCP) and Tool Contextp.8
    1. What MCP isp.8
    2. Initializing an MCP clientp.8
    3. Using MCP toolsp.8
    4. Closing the clientp.8
    5. Resources, prompts, and elicitationp.8
    6. MCP Appsp.8
    7. Runtime and tool contextp.8
    8. Best practices and security for remote toolsp.8
    9. +1 more section
See all 29 parts
  1. 09Prompt Engineering, Settings, and Reasoningp.9
    1. Prompt vs. Messagesp.9
    2. The Message Formatp.9
    3. Prompt Engineering for the SDKp.9
    4. Common Call Settingsp.9
    5. Reasoning Modelsp.9
    6. Key takeawaysp.9
  2. 10Embeddings and Rerankingp.10
    1. Embedding a Single Valuep.10
    2. Embedding Many Valuesp.10
    3. Token Usagep.10
    4. Cosine Similarityp.10
    5. Settingsp.10
    6. Embedding Providers and Modelsp.10
    7. Building a Semantic-Search / RAG Embedding Pipelinep.10
    8. Rerankingp.10
    9. +1 more section
  3. 11Multimodal Generation: Images, Speech, Transcription, Video, and Filesp.11
    1. Image Generationp.11
    2. Realtime (Experimental)p.11
    3. Transcription (Experimental)p.11
    4. Speech (Experimental)p.11
    5. Video Generation (Experimental)p.11
    6. File Uploadsp.11
    7. Key takeawaysp.11
  4. 12Provider and Model Managementp.12
    1. Why centralize provider configurationp.12
    2. How provider packages workp.12
    3. Custom providers with `customProvider`p.12
    4. The provider registryp.12
    5. Combining custom providers, the registry, and middlewarep.12
    6. The AI Gateway as the default providerp.12
    7. Choosing and swapping models cleanlyp.12
    8. Key takeawaysp.12
  5. 13Language Model Middlewarep.13
    1. Applying middleware with `wrapLanguageModel`p.13
    2. Built-in middlewarep.13
    3. The `LanguageModelMiddleware` interfacep.13
    4. Per-request custom metadatap.13
    5. Community middlewarep.13
    6. Skill Uploadsp.13
    7. Key takeawaysp.13
  6. 14Error Handling, Testing, Telemetry, and DevToolsp.14
    1. The error modelp.14
    2. Handling streaming errorsp.14
    3. Retries and `maxRetries`p.14
    4. Testing with mock providersp.14
    5. Telemetryp.14
    6. DevToolsp.14
    7. Event callbacks as cross-cutting observability hooksp.14
    8. Key takeawaysp.14
  7. 15Agent Fundamentals: The Agent Loop and Loop Controlp.15
    1. What Is an Agent in the SDK?p.15
    2. Creating an Agentp.15
    3. Configuration Optionsp.15
    4. Define Agent Behavior with System Instructionsp.15
    5. Using an Agentp.15
    6. End-to-End Type Safetyp.15
    7. The Agent Loopp.15
    8. Loop Controlp.15
    9. +2 more sections
  8. 16Workflow Patternsp.16
    1. Deterministic vs. Agentic Controlp.16
    2. Sequential Processing (Chains)p.16
    3. Routing (Classification)p.16
    4. Parallel Processingp.16
    5. Orchestrator-Workerp.16
    6. Evaluator-Optimizerp.16
    7. When to Hand Control to the Model vs. Encode It Yourselfp.16
    8. Key Takeawaysp.16
  9. 17Advanced Agents: Memory, Subagents, Approvals, Skills, and DurableAgent (Workflow DevKit)p.17
    1. Memoryp.17
    2. Subagentsp.17
    3. Tool Approvals (Human-in-the-Loop)p.17
    4. Compacting Agent Contextp.17
    5. Skills: Adding Specialized Knowledge on Demandp.17
    6. DurableAgent: Durable, Resumable Agents (Workflow DevKit, v6)p.17
    7. Key Takeawaysp.17
  10. 18Building Chatbots with useChatp.18
    1. 16.1 The minimal chatbotp.18
    2. 16.2 The UIMessage model and rendering partsp.18
    3. 16.3 The UIMessage-vs-ModelMessage split on the serverp.18
    4. 16.4 Status: driving the UI through the request lifecyclep.18
    5. 16.5 Stopping and regeneratingp.18
    6. 16.6 Error handlingp.18
    7. 16.7 Directly modifying messagesp.18
    8. 16.8 Event callbacksp.18
    9. +5 more sections
  11. 19Persistence, Resumable Streams, and Transportsp.19
    1. 17.1 The persistence modelp.19
    2. 17.2 Starting and loading a chatp.19
    3. 17.3 Saving on the serverp.19
    4. 17.4 Message IDs and server-side generationp.19
    5. 17.5 Sending only the last messagep.19
    6. 17.6 Handling client disconnectsp.19
    7. 17.7 Resumable streamsp.19
    8. 17.8 Stopping a resumable streamp.19
    9. +2 more sections
  12. 20Tool Usage and Human-in-the-Loop in the UIp.20
    1. 18.1 The three tool execution patternsp.20
    2. 18.2 Tool part statesp.20
    3. 18.3 Rendering tool partsp.20
    4. 18.4 Streaming tool inputsp.20
    5. 18.5 Client-side tool executionp.20
    6. 18.6 Human-in-the-loop: confirmation toolsp.20
    7. 18.7 Human-in-the-loop: server-side tool approvalp.20
    8. 18.8 Dynamic tools and step boundariesp.20
    9. +2 more sections
  13. 21Generative User Interfacesp.21
    1. How Generative UI Worksp.21
    2. Building a Generative UI Chat Interfacep.21
    3. Defining a Toolp.21
    4. The Display Componentp.21
    5. Mapping Tool Parts to Componentsp.21
    6. Adding More Tools and Componentsp.21
    7. Streaming Structured UI State with Data Partsp.21
    8. Rendering Persistent Data Partsp.21
    9. +3 more sections
  14. 22Completion, Object Generation, and Custom Data Streamingp.22
    1. useCompletion: Single-Prompt Completionsp.22
    2. useObject: Streaming Structured Objectsp.22
    3. Streaming Custom Datap.22
    4. UI Error Handling and Warningsp.22
    5. Reading UI Message Streamsp.22
    6. Message Metadatap.22
    7. Key takeawaysp.22
  15. 23Framework and Server Integrationp.23
    1. The Two Families of Response Helpersp.23
    2. Next.js Route Handlers (Recap)p.23
    3. Node.js HTTP Serverp.23
    4. Expressp.23
    5. Honop.23
    6. Fastifyp.23
    7. Nest.jsp.23
    8. Streaming Considerations Across Frameworksp.23
    9. +2 more sections
  16. 24The Vercel AI Gatewayp.24
    1. Why route through a Gatewayp.24
    2. Basic usage: plain model stringsp.24
    3. The `gateway` provider instancep.24
    4. Authentication: API key, access token, or OIDCp.24
    5. The model id format and model routingp.24
    6. Automatic fallbacks and failoverp.24
    7. Per-provider options through the Gatewayp.24
    8. Provider-executed and Gateway-executed toolsp.24
    9. +6 more sections
  17. 25Provider Deep-Divesp.25
    1. How provider packages are structuredp.25
    2. OpenAIp.25
    3. Anthropicp.25
    4. Google Generative AI and Vertexp.25
    5. Amazon Bedrockp.25
    6. Groqp.25
    7. Mistralp.25
    8. xAI Grokp.25
    9. +5 more sections
  18. 26Production Best Practicesp.26
    1. 24.1 Architecture and configurationp.26
    2. 24.2 Streaming and UXp.26
    3. 24.3 Tool calling and agentsp.26
    4. 24.4 Structured outputp.26
    5. 24.5 Cost and performancep.26
    6. 24.6 Securityp.26
    7. 24.7 Reliability and observabilityp.26
    8. 24.8 Production deploymentp.26
    9. +1 more section
  19. 27End-to-End Projectsp.27
    1. Project 1 — RAG Chatbotp.27
    2. Project 2 — Natural-Language-to-SQL over Postgresp.27
    3. Project 3 — Multi-Modal Agentp.27
    4. Project 4 — Slack AI Agentp.27
    5. Project 5 — Computer Usep.27
    6. Key takeawaysp.27
  20. 28Appendix A — Error Referencep.28
    1. Quick referencep.28
    2. Call and transport errorsp.28
    3. Generation result errorsp.28
    4. Tool-calling errorsp.28
    5. Configuration and lookup errorsp.28
    6. Validation and parsing errorsp.28
    7. Streaming and message errorsp.28
    8. Embedding errorsp.28
    9. +1 more section
  21. 29Appendix B — Migration Guide (v3 → v6)p.29
    1. B.1 v3 → v4p.29
    2. B.2 v4 → v5 — the big rebuildp.29
    3. B.3 v5 → v6 — renames and new defaultsp.29
    4. B.4 A pragmatic upgrade checklistp.29
    5. Key takeawaysp.29