vercel-ai-sdk-v5
用于生产聊天机器人的专家级 Vercel AI SDK v5 模式。用于:(1)使用 Drizzle/PostgreSQL 的聊天持久化,(2)使用类型化工具部分的生成式 UI,(3)人工参与工具确认,(4)带协调的自定义数据流,(5)具有扩展思维/推理的 Anthropic 提供商,(6)带令牌跟踪的类型安全消息元数据。仅涵盖高级模式 - 假设基本 AI SDK 知识。不适用于 AI SDK v6。
📖 中文导读:用于生产聊天机器人的专家级 Vercel AI SDK v5 模式。用于:(1)使用 Drizzle/PostgreSQL 的聊天持久化,(2)使用类型化工具部分的生成式 UI,(3)人工参与工具确认,(4)带协调的自定义数据流,(5)具有扩展思维/推理的 Anthropic 提供商,(6)带令牌跟踪的类型安全消息元数据。仅涵盖高级模式 - 假设基本 AI SDK 知识。不适用于 AI SDK v6。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
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 +
onToolCallhandler
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(notchats) - Foreign keys:
agentId(notchatId) - 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 generictool-call - Data parts need
idfor reconciliation - same ID updates existing part - Transient parts only in
onData- never inmessage.parts sendStart: falsewhen using custom start - avoid duplicate start eventsresult.consumeStream()- call without await for disconnect handling