> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

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

통합 문서를 찾고 계신가요? [AI SDK 사용하기](https://mastra.zisheng.pro/ko/guides/build-your-ui/ai-sdk-ui)를 참조하세요. AI SDK 핵심의 모든 호환성 중단 변경 사항, 패키지 업데이트, API 변경 사항은 공식 [AI SDK v5 마이그레이션 가이드](https://v5.ai-sdk.dev/docs/migration-guides/migration-guide-5-0)를 따르세요. 이 가이드에서는 마이그레이션의 Mastra 관련 측면만 다룹니다.

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

## Memory 및 스토리지

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

## 메시지 형식 변환

AI SDK와 Mastra 형식 간에 메시지를 수동으로 변환해야 하는 경우`convertMessages()` utility:

```typescript
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의 입력 및 출력 타입을 추론합니다.

```typescript
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의 입력 및 출력 타입을 추론합니다.

```typescript
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 지원을 제공하여 애플리케이션 전체에서 유형 안전성을 보장합니다.