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

code

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

Key Imports

typescript

// 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:

code

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

typescript

// 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

typescript

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

3. Handle Disconnects

typescript

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

4. Type-Safe Tools

typescript

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