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

# 從 VNext 遷移至標準 API

自 `@mastra/core` 的 `v0.20.0` 起，適用下列變更。

## 舊版 API（AI SDK v4）

原始方法已重新命名，並維持與 **AI SDK v4** 及 `v1` 模型的回溯相容性。

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

## 標準 API（AI SDK v5）

這些現在是目前使用的 API，完整相容於 **AI SDK v5** 與 `v2` 模型。

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

## 遷移路徑

如果已使用 `.streamVNext()` 與 `.generateVNext()`，請使用尋找／替換，分別將方法改為 `.stream()` 與 `.generate()`。

如果使用舊的 `.stream()` 與 `.generate()`，請決定是否要升級。如果不升級，請使用尋找／替換，將它們分別改為 `.streamLegacy()` 與 `.generateLegacy()`。

請選擇符合需求的遷移路徑：

### 繼續使用 AI SDK v4 模型

- 將所有 `.stream()` 與 `.generate()` 呼叫分別重新命名為 `.streamLegacy()` 與 `.generateLegacy()`。

> 不需進行其他變更。

### 繼續使用 AI SDK v5 模型

- 將所有 `.streamVNext()` 與 `.generateVNext()` 呼叫分別重新命名為 `.stream()` 與 `.generate()`。

> 不需進行其他變更。

### 從 AI SDK v4 升級至 v5

- 將所有模型 Provider 套件升級一個主要版本。

> 這可確保它們現在全都是 v5 模型。請依照下方指南瞭解主要差異，並據此更新程式碼。

## 主要差異

更新後的 `.stream()` 與 `.generate()` 方法在行為、相容性、傳回型別和可用選項方面，都與舊版方法不同。本節會說明遷移時必須瞭解的最重要變更。

### 模型版本支援

**舊版 API**

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

只支援 **AI SDK v4** 模型（`specificationVersion: 'v1'`）

**標準 API**

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

只支援 **AI SDK v5** 模型（`specificationVersion: 'v2'`）

> 這項限制會在執行階段強制執行，並提供清楚的錯誤訊息。

### 傳回型別

**舊版 API**

- `.generateLegacy()` 傳回：`GenerateTextResult` 或 `GenerateObjectResult`

- `.streamLegacy()` 傳回：`StreamTextResult` 或 `StreamObjectResult`

如需詳細資訊，請參閱下列 API 參考文件：

- [Agent.generateLegacy()](https://mastra.zisheng.pro/zh-TW/reference/agents/generateLegacy)
- [Agent.streamLegacy()](https://mastra.zisheng.pro/zh-TW/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.generate()](https://mastra.zisheng.pro/zh-TW/reference/agents/generate)
- [Agent.stream()](https://mastra.zisheng.pro/zh-TW/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` - 自訂系統訊息（與 instructions 分開）。

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

- `structuredOutput` - 強化的結構化輸出，支援覆寫模型與自訂選項。

  - `jsonPromptInjection` - 用來覆寫將 response\_format 傳給模型的預設行為。這會將內容插入提示詞，引導模型傳回結構化輸出。

  - `model` - 新增模型後，會建立 subagent，將主要 Agent 的回應結構化。主要 Agent 會呼叫 Tool 並傳回文字，而 subagent 會傳回符合所提供結構描述的物件。這會取代 `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` - 彈性的停止條件（步數、token 上限等）。

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

- `providerOptions` - Provider 專屬選項（例如 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`

  請改用 `structuredOutput`，以允許 Tool 呼叫並傳回物件。

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

- `output`

  `output` 屬性已棄用，請改用 `structuredOutput`。若要達到相同結果，請省略模型，只傳入 `structuredOutput.schema`；如果模型原生不支援 `response_format`，可選擇新增 `jsonPromptInjection: true`。

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

- `memoryOptions`

  請改用 `memory`。

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

### 型別變更

**舊版 API**

- `CoreMessage[]`

如需詳細資訊，請參閱下列 API 參考文件：

- [Agent.generateLegacy()](https://mastra.zisheng.pro/zh-TW/reference/agents/generateLegacy)
- [Agent.streamLegacy()](https://mastra.zisheng.pro/zh-TW/reference/streaming/agents/streamLegacy)

**標準 API**

- `ModelMessage[]`

  `toolChoice` 使用 AI SDK v5 的 `ToolChoice` 型別。

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

如需詳細資訊，請參閱下列 API 參考文件：

- [Agent.generate()](https://mastra.zisheng.pro/zh-TW/reference/agents/generate)
- [Agent.stream()](https://mastra.zisheng.pro/zh-TW/reference/streaming/agents/stream)