从 AI SDK v4 迁移到 v5

🌐 Migrate from AI SDK v4 to v5

正在寻找集成文档？请参阅 使用 AI SDK。

🌐 Looking for integration docs? See Using AI SDK.

请遵循官方 AI SDK v5 迁移指南 了解所有 AI SDK 核心破坏性更改、软件包更新和 API 变更。

🌐 Follow the official AI SDK v5 Migration Guide for all AI SDK core breaking changes, package updates, and API changes.

本指南仅涵盖迁移过程中与Mastra相关的特定方面。

🌐 This guide covers only the Mastra-specific aspects of the migration.

• 数据兼容性：如果从 v5 降级到 v4，使用 v5 格式存储的新数据将无法使用
• 备份建议：保留升级到v5之前的数据库备份

内存和存储

🌐 Memory and Storage

Mastra 会自动使用其内部的 MessageList 类处理 AI SDK v4 数据，该类管理格式转换——包括从 v4 到 v5 的转换。无需进行数据库迁移；升级后，你现有的消息会被即时转换，并继续正常工作。

🌐 Mastra automatically handles AI SDK v4 data using its internal MessageList class, which manages format conversion—including v4 to v5. No database migrations are required; your existing messages are translated on the fly and continue working after you upgrade.

消息格式转换

🌐 Message Format Conversion

对于需要在 AI SDK 和 Mastra 格式之间手动转换消息的情况，请使用 convertMessages() 工具：

🌐 For cases where you need to manually convert messages between AI SDK and Mastra formats, use the convertMessages() utility:

import { convertMessages } from "@mastra/core/agent";

// Convert AI SDK v4 messages to v5
const aiv5Messages = convertMessages(aiv4Messages).to("AIV5.UI");

// Convert Mastra messages to AI SDK v5
const aiv5Messages = convertMessages(mastraMessages).to("AIV5.Core");

// Supported output formats:
// 'Mastra.V2', 'AIV4.UI', 'AIV5.UI', 'AIV5.Core', 'AIV5.Model'

当你想直接从存储数据库获取消息并将其转换以用于 AI SDK 时，这个工具非常有用。

🌐 This utility is helpful when you want to fetch messages directly from your storage DB and convert them for use in AI SDK.

工具的类型推断

🌐 Type Inference for Tools

在 AI SDK v5 中使用 TypeScript 的工具时，Mastra 提供了类型推断辅助工具，以确保你的工具输入和输出的类型安全。

🌐 When using tools with TypeScript in AI SDK v5, Mastra provides type inference helpers to ensure type safety for your tool inputs and outputs.

InferUITool

InferUITool 类型辅助工具可以推断单个 Mastra 工具的输入和输出类型：

🌐 The InferUITool type helper infers the input and output types of a single Mastra tool:

app/types.ts

import { InferUITool, createTool } from "@mastra/core/tools";
import { z } from "zod";

const weatherTool = createTool({
  id: "get-weather",
  description: "Get the current weather",
  inputSchema: z.object({
    location: z.string().describe("The city and state"),
  }),
  outputSchema: z.object({
    temperature: z.number(),
    conditions: z.string(),
  }),
  execute: async (inputData) => {
    return {
      temperature: 72,
      conditions: "sunny",
    };
  },
});

// Infer the types from the tool
type WeatherUITool = InferUITool<typeof weatherTool>;
// This creates:
// {
//   input: { location: string };
//   output: { temperature: number; conditions: string };
// }

InferUITools

InferUITools 类型辅助工具可以推断多个工具的输入和输出类型：

🌐 The InferUITools type helper infers the input and output types of multiple tools:

app/mastra/tools.ts

import { InferUITools, createTool } from "@mastra/core/tools";
import { z } from "zod";

// Using weatherTool from the previous example
const tools = {
  weather: weatherTool,
  calculator: createTool({
    id: "calculator",
    description: "Perform basic arithmetic",
    inputSchema: z.object({
      operation: z.enum(["add", "subtract", "multiply", "divide"]),
      a: z.number(),
      b: z.number(),
    }),
    outputSchema: z.object({
      result: z.number(),
    }),
    execute: async (inputData) => {
      // implementation...
      return { result: 0 };
    },
  }),
};

// Infer types from the tool set
export type MyUITools = InferUITools<typeof tools>;
// This creates:
// {
//   weather: { input: { location: string }; output: { temperature: number; conditions: string } };
//   calculator: { input: { operation: "add" | "subtract" | "multiply" | "divide"; a: number; b: number }; output: { result: number } };
// }

这些类型辅助工具在将 Mastra 工具与 AI SDK v5 UI 组件一起使用时提供完整的 TypeScript 支持，确保整个应用的类型安全。

🌐 These type helpers provide full TypeScript support when using Mastra tools with AI SDK v5 UI components, ensuring type safety across your application.