vercel-ai-sdk-v5

horuz-ai 的头像作者 horuz-ai

用于生产聊天机器人的专家级 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 + 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

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