name

vercel-ai-sdk-v5

description

Expert-level Vercel AI SDK v5 patterns for production chatbots. Use for: (1) Chat persistence with Drizzle/PostgreSQL, (2) Generative UI with typed tool parts, (3) Human-in-the-loop tool confirmations, (4) Custom data streaming with reconciliation, (5) Anthropic provider with extended thinking/reasoning, (6) Type-safe message metadata with token tracking. Covers advanced patterns only - assumes basic AI SDK knowledge. NOT for AI SDK v6.

Vercel AI SDK v5

Production patterns for AI chatbots with persistence, generative UI, and streaming.

Quick Reference

Need	Reference
Database schema & persistence	`references/persistence.md`
Tools & generative UI	`references/tools-and-generative-ui.md`
Custom data streaming	`references/streaming.md`
Type definitions	`references/types.md`
Anthropic + reasoning	`references/anthropic-config.md`
Working examples	`cookbook/` directory

Core Architecture

Message Flow

Client (useChat) → API Route (streamText) → DB (Drizzle)
     ↑                    ↓
     └── UIMessageStream ←┘

Key Imports

// Core
import { streamText, convertToModelMessages, UIMessage } from 'ai'
import { createUIMessageStream, createUIMessageStreamResponse } from 'ai'

// Client
import { useChat } from '@ai-sdk/react'
import { DefaultChatTransport } from 'ai'

// Provider
import { anthropic } from '@ai-sdk/anthropic'

Decision Tree

Streaming Response Type

Simple text streaming → streamText().toUIMessageStreamResponse()
Need custom data parts → createUIMessageStream() + writer.write()
Need both → createUIMessageStream() + writer.merge(result.toUIMessageStream())

Tool Execution Location

Has server-side data/secrets → Server tool with execute
Needs client confirmation → Client tool (no execute) + addToolOutput
Auto-runs on client → Client tool + onToolCall handler

Data Attachment

Message-level info (tokens, model, timestamps) → messageMetadata
Dynamic content in message → Data parts with writer.write()
Temporary status (not persisted) → Transient data parts

Naming Convention

This skill uses agents instead of chats for all database tables, routes, and methods:

Table: agents (not chats)
Foreign keys: agentId (not chatId)
Actions: createAgent(), loadAgent(), deleteAgent()

File Organization

Follow feature-based architecture:

features/
└── agents/
    ├── data/
    │   └── get-agent.ts
    ├── actions/
    │   └── create-agent.ts
    ├── types/
    │   └── message.ts
    └── components/
        ├── server/
        │   └── agent-messages.tsx
        └── client/
            └── chat-input.tsx

db/
├── schema.ts      # Table definitions
├── relations.ts   # Drizzle relations
└── actions.ts     # DB operations (upsert, load, delete)

Essential Patterns

1. Send Only Last Message

// Client
transport: new DefaultChatTransport({
  api: '/api/agent',
  prepareSendMessagesRequest: ({ messages, id }) => ({
    body: { message: messages.at(-1), agentId: id }
  })
})

// Server: Load history, append new message
const previous = await loadAgent(agentId)
const messages = [...previous, message]

2. Persist on Finish

return result.toUIMessageStreamResponse({
  originalMessages: messages,
  onFinish: async ({ messages }) => {
    await upsertMessages({ agentId, messages })
  }
})

3. Handle Disconnects

const result = streamText({ ... })
result.consumeStream() // No await - ensures completion even on disconnect
return result.toUIMessageStreamResponse({ ... })

4. Type-Safe Tools

const tools = { myTool: tool({ ... }) } satisfies ToolSet
type MyTools = InferUITools<typeof tools>
type MyUIMessage = UIMessage<MyMetadata, MyDataParts, MyTools>

Common Gotchas

Tool part types are tool-${toolName} not generic tool-call
Data parts need id for reconciliation - same ID updates existing part
Transient parts only in onData - never in message.parts
sendStart: false when using custom start - avoid duplicate start events
result.consumeStream() - call without await for disconnect handling