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

# VNext에서 표준 API로 마이그레이션

현재`v0.20.0`\~을 위한`@mastra/core`, 다음 변경 사항이 적용됩니다.

## 레거시 API(AI SDK v4)

기존 메서드의 이름이 변경되었으며 **AI SDK v4** 및 `v1` Model과의 이전 버전 호환성을 유지합니다.

- `.stream()` → `.streamLegacy()`
- `.generate()` → `.generateLegacy()`

## 표준 API(AI SDK v5)

이제 **AI SDK v5** 및 `v2` Model과 완벽하게 호환되는 모든 기능을 갖춘 최신 API입니다.

- `.streamVNext()` → `.stream()`
- `.generateVNext()` → `.generate()`

## 마이그레이션 경로

이미 `.streamVNext()` 및 `.generateVNext()`를 사용하고 있다면 찾기/바꾸기를 사용하여 각 메서드를 `.stream()` 및 `.generate()`로 변경하세요. 이전 `.stream()` 및 `.generate()`를 사용하고 있다면 업그레이드 여부를 결정하세요. 업그레이드하지 않으려면 찾기/바꾸기를 사용하여 `.streamLegacy()` 및 `.generateLegacy()`로 변경하세요. 필요에 맞는 마이그레이션 경로를 선택하세요.

### AI SDK v4 Model을 계속 사용하세요.

- 모든 `.stream()` 및 `.generate()` 호출의 이름을 각각 `.streamLegacy()` 및 `.generateLegacy()`로 변경하세요.

> 추가 변경이 필요하지 않습니다.

### AI SDK v5 Model을 계속 사용하세요.

- 모든 `.streamVNext()` 및 `.generateVNext()` 호출의 이름을 각각 `.stream()` 및 `.generate()`로 변경하세요.

> 추가 변경이 필요하지 않습니다.

### AI SDK v4에서 v5로 업그레이드

- 모든 Model 제공자 패키지를 메이저 버전으로 업그레이드하세요.

> 이렇게 하면 이제 모든 Model이 v5 Model이 됩니다. 아래 가이드에 따라 주요 차이점을 이해하고 이에 따라 코드를 업데이트하세요.

## 주요 차이점

업데이트된 `.stream()` 및 `.generate()` 메서드는 동작, 호환성, 반환 타입 및 사용 가능한 옵션이 레거시 메서드와 다릅니다. 이 섹션에서는 마이그레이션할 때 알아야 할 가장 중요한 변경 사항을 설명합니다.

### Model 버전 지원

**레거시 API**

- `.generateLegacy()`
- `.streamLegacy()`

지원만 가능**AI SDK v4** models (`specificationVersion: 'v1'`)

**표준 API**

- `.generate()`
- `.stream()`

지원만 가능**AI SDK v5** models (`specificationVersion: 'v2'`)

> 이는 명확한 오류 메시지와 함께 런타임에 적용됩니다.

### 반환 유형

**레거시 API**

- `.generateLegacy()` 반환: `GenerateTextResult` 또는 `GenerateObjectResult`

- `.streamLegacy()` 반환: `StreamTextResult` 또는 `StreamObjectResult` 자세한 내용은 다음 API 참조를 참조하세요.

- [Agent.generateLegacy()](https://mastra.zisheng.pro/ko/reference/agents/generateLegacy)

- [Agent.streamLegacy()](https://mastra.zisheng.pro/ko/reference/streaming/agents/streamLegacy) **표준 API**

- `.generate()`

  - `format: 'mastra'`(기본값): `MastraModelOutput.getFullOutput()` 반환
  - `format: 'aisdk'`: `AISDKV5OutputStream.getFullOutput()` 반환
  - 내부적으로 `.stream()`을 호출하고 `.getFullOutput()`을 기다림

- `.stream()`

  - `format: 'mastra'`(기본값): 반환`MastraModelOutput<OUTPUT>`
  - `format: 'aisdk'`: 반품`AISDKV5OutputStream<OUTPUT>`

자세한 내용은 다음 API 참조를 참조하세요.

- [Agent.생성()](https://mastra.zisheng.pro/ko/reference/agents/generate)
- [Agent.스트림()](https://mastra.zisheng.pro/ko/reference/streaming/agents/stream)

### 형식 제어

#### 레거시 API

`format` 옵션 없음: 항상 AI SDK v4 타입 반환

```typescript
// Mastra native format (default)
const result = await agent.stream(messages)
```

#### 표준 API

출력을 선택하려면 `format` 옵션을 사용하세요.

- `'mastra'`(기본)
- `'aisdk'`(AI SDK v5 호환)

```typescript
// AI SDK v5 compatibility
const result = await agent.stream(messages, {
  format: 'aisdk',
})
```

### 표준 API의 새로운 옵션

다음 옵션은 표준 `.stream()` 및 `generate()`에서는 사용할 수 있지만 레거시 메서드에서는 **사용할 수 없습니다**.

- `format`- 'mastra' 또는 'aisdk' 출력 형식 중에서 선택하세요:

  ```typescript
  const result = await agent.stream(messages, {
    format: 'aisdk', // or 'mastra' (default)
  })
  ```

- `system`- 사용자 정의 시스템 메시지(지침과 별도)

  ```typescript
  const result = await agent.stream(messages, {
    system: 'You are a helpful assistant',
  })
  ```

- `structuredOutput`- Model 재정의 및 사용자 정의 옵션으로 구조화된 출력이 향상되었습니다.

  - `jsonPromptInjection`- response\_format을 Model에 전달하는 기본 동작을 재정의하는 데 사용됩니다. 그러면 Model이 구조화된 출력을 반환하도록 강제하기 위해 Prompt에 컨텍스트가 주입됩니다.

  - `model`- Model이 추가되면 주 Agent의 응답을 구조화하기 위한 하위 Agent가 생성됩니다. 주 Agent는 Tool을 호출하고 텍스트를 반환하며, 하위 Agent는 제공된 스키마를 준수하는 개체를 반환합니다. 이는 다음을 대체합니다.`experimental_output`.

  - `errorStrategy`- 출력이 스키마와 일치하지 않을 때 발생하는 상황을 결정합니다.

    - 'warn' - 경고를 기록합니다.
    - 'error' - 오류 발생
    - 'fallback' - 제공한 대체 값을 반환합니다.

    ```typescript
    const result = await agent.generate(messages, {
      structuredOutput: {
        schema: z.object({
          name: z.string(),
          age: z.number(),
        }),
        model: 'openai/gpt-5.6-sol', // Optional model override for structuring
        errorStrategy: 'fallback',
        fallbackValue: { name: 'unknown', age: 0 },
        instructions: 'Extract user information', // Override default structuring instructions
      },
    })
    ```

- `stopWhen`- 유연한 정지 조건(걸음 수, 토큰 제한 등).

  ```typescript
  const result = await agent.stream(messages, {
    stopWhen: ({ steps, totalTokens }) => steps >= 5 || totalTokens >= 10000,
  })
  ```

- `providerOptions`- 공급자별 옵션(예: OpenAI별 설정)

  ```typescript
  const result = await agent.stream(messages, {
    providerOptions: {
      openai: {
        store: true,
        metadata: { userId: '123' },
      },
    },
  })
  ```

- `onChunk`- 각 스트리밍 청크에 대한 콜백.

  ```typescript
  const result = await agent.stream(messages, {
    onChunk: chunk => {
      console.log('Received chunk:', chunk)
    },
  })
  ```

- `onError`- 콜백 오류.

  ```typescript
  const result = await agent.stream(messages, {
    onError: error => {
      console.error('Stream error:', error)
    },
  })
  ```

- `onAbort`- 콜백을 중단합니다.

  ```typescript
  const result = await agent.stream(messages, {
    onAbort: () => {
      console.log('Stream aborted')
    },
  })
  ```

- `activeTools`- 이 실행에 대해 활성화된 Tool을 지정합니다.

  ```typescript
  const result = await agent.stream(messages, {
    activeTools: ['search', 'calculator'], // Only these tools will be available
  })
  ```

- `abortSignal`- 취소를 위한 AbortSignal.

  ```typescript
  const controller = new AbortController()
  const result = await agent.stream(messages, {
    abortSignal: controller.signal,
  })

  // Later: controller.abort();
  ```

- `prepareStep`- 다단계 실행의 각 단계 전에 콜백합니다.

  ```typescript
  const result = await agent.stream(messages, {
    prepareStep: ({ step, state }) => {
      console.log('About to execute step:', step)
      return {/* modified state */}
    },
  })
  ```

- `requireToolApproval`- 모든 Tool 호출에는 승인이 필요합니다.

  ```typescript
  const result = await agent.stream(messages, {
    requireToolApproval: true,
  })
  ```

### 이동된 레거시 옵션

- `temperature`그리고 기타`modelSettings`.

  통합`modelSettings`

  ```typescript
  const result = await agent.stream(messages, {
    modelSettings: {
      temperature: 0.7,
      maxTokens: 1000,
      topP: 0.9,
    },
  })
  ```

- `resourceId`그리고`threadId`.

  Memory 개체로 이동되었습니다.

  ```typescript
  const result = await agent.stream(messages, {
    memory: {
      resource: 'user-123',
      thread: 'thread-456',
    },
  })
  ```

### 더 이상 사용되지 않거나 제거된 옵션

- `experimental_output`

  Tool 호출과 객체 반환을 허용하려면 대신 `structuredOutput`을 사용하세요.

  ```typescript
  const result = await agent.generate(messages, {
    structuredOutput: {
      schema: z.object({
        summary: z.string(),
      }),
      model: 'openai/gpt-5.6-sol',
    },
  })
  ```

- `output`

  `output` 속성 대신 `structuredOutput`을 사용하는 것이 권장됩니다. 동일한 결과를 얻으려면 Model을 생략하고 `structuredOutput.schema`만 전달하세요. Model이 `response_format`을 기본적으로 지원하지 않는다면 선택적으로 `jsonPromptInjection: true`를 추가하세요.

  ```typescript
  const result = await agent.generate(messages, {
    structuredOutput: {
      schema: z.object({
        name: z.string(),
      }),
    },
  })
  ```

- `memoryOptions`

  사용`memory` instead.

  ```typescript
  const result = await agent.generate(messages, {
    memory: {},
  })
  ```

### 유형 변경

**레거시 API**

- `CoreMessage[]`

자세한 내용은 다음 API 참조를 참조하세요.

- [Agent.generateLegacy()](https://mastra.zisheng.pro/ko/reference/agents/generateLegacy)

- [Agent.streamLegacy()](https://mastra.zisheng.pro/ko/reference/streaming/agents/streamLegacy) **표준 API**

- `ModelMessage[]`

  `toolChoice`AI SDK v5를 사용합니다.`ToolChoice` type.

  ```typescript
  type ToolChoice<TOOLS extends Record<string, unknown>> =
    | 'auto'
    | 'none'
    | 'required'
    | {
        type: 'tool'
        toolName: Extract<keyof TOOLS, string>
      }
  ```

자세한 내용은 다음 API 참조를 참조하세요.

- [Agent.생성()](https://mastra.zisheng.pro/ko/reference/agents/generate)
- [Agent.스트림()](https://mastra.zisheng.pro/ko/reference/streaming/agents/stream)