> Discover all available pages from the documentation index: https://mastra.zisheng.pro/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 Reference：

- [Agent.generateLegacy()](https://mastra.zisheng.pro/reference/agents/generateLegacy)
- [Agent.streamLegacy()](https://mastra.zisheng.pro/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 Reference：

- [Agent.generate()](https://mastra.zisheng.pro/reference/agents/generate)
- [Agent.stream()](https://mastra.zisheng.pro/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` — 添加模型后，会创建一个子 Agent 来整理主 Agent 的响应。主 Agent 会调用 Tool 并返回文本，子 Agent 则返回符合所提供 Schema 的对象。它可替代 `experimental_output`。

  - `errorStrategy` — 决定输出与 Schema 不匹配时如何处理：

    - '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 Reference：

- [Agent.generateLegacy()](https://mastra.zisheng.pro/reference/agents/generateLegacy)
- [Agent.streamLegacy()](https://mastra.zisheng.pro/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 Reference：

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