AI SDK v4에서 v5로 마이그레이션

통합 문서를 찾고 계신가요? AI SDK 사용하기를 참조하세요. AI SDK 핵심의 모든 호환성 중단 변경 사항, 패키지 업데이트, API 변경 사항은 공식 AI SDK v5 마이그레이션 가이드를 따르세요. 이 가이드에서는 마이그레이션의 Mastra 관련 측면만 다룹니다.

• 데이터 호환성: v5에서 v4로 다운그레이드하면 v5 형식으로 저장된 새 데이터가 더 이상 작동하지 않습니다.
• 백업 권장사항: v5로 업그레이드하기 전의 DB 백업을 유지하세요.

Memory 및 스토리지

Mastra는 내부 MessageList 클래스를 사용하여 AI SDK v4 데이터를 자동으로 처리합니다. 이 클래스는 v4에서 v5로의 변환을 포함한 형식 변환을 관리합니다. 데이터베이스 마이그레이션은 필요하지 않습니다. 기존 메시지는 즉시 변환되며 업그레이드 후에도 계속 작동합니다.

메시지 형식 변환

AI SDK와 Mastra 형식 간에 메시지를 수동으로 변환해야 하는 경우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'

이 유틸리티는 스토리지 DB에서 직접 메시지를 가져와 AI SDK에서 사용할 수 있도록 변환하려는 경우에 유용합니다.

Tool에 대한 유형 추론

AI SDK v5에서 TypeScript와 함께 Tool을 사용할 때 Mastra는 Tool 입력 및 출력에 대한 유형 안전성을 보장하기 위해 유형 추론 도우미를 제공합니다.

InferUITool

InferUITool 타입 도우미는 단일 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 타입 도우미는 여러 Tool의 입력 및 출력 타입을 추론합니다.

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

이러한 유형 도우미는 AI SDK v5 UI 구성 요소와 함께 Mastra Tool을 사용할 때 완전한 TypeScript 지원을 제공하여 애플리케이션 전체에서 유형 안전성을 보장합니다.