从 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()
• Agent.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()
• Agent.stream()

格式控制

旧版 API

没有 format 选项：始终返回 AI SDK v4 类型

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

标准 API

使用 format 选项选择输出：

• 'mastra'（默认）
• 'aisdk'（兼容 AI SDK v5）

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

标准 API 中的新选项

标准 .stream() 和 generate() 提供以下选项，但旧版方法不提供：

• format — 在 'mastra' 与 'aisdk' 输出格式之间选择：

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

• system — 自定义系统消息（与 instructions 分开）。

  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' — 返回你提供的回退值

    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 上限等）。

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

• providerOptions — Provider 特有选项（例如 OpenAI 特有设置）

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

• onChunk — 每个流式数据块的回调。

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

• onError — 错误回调。

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

• onAbort — 中止回调。

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

• activeTools — 指定此次执行中启用哪些 Tool。

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

• abortSignal — 用于取消的 AbortSignal。

  const controller = new AbortController()
  const result = await agent.stream(messages, {
    abortSignal: controller.signal,
  })
  
  // Later: controller.abort();

• prepareStep — 多步骤执行中每个步骤之前的回调。

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

• requireToolApproval — 要求审批所有 Tool 调用。

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

已迁移的旧版选项

• temperature 和其他 modelSettings。

  统一放入 modelSettings

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

• resourceId 和 threadId。

  已移至 memory 对象。

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

已弃用或移除的选项

• experimental_output

  请改用 structuredOutput，以支持 Tool 调用和对象返回值。

  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。

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

• memoryOptions

  请改用 memory。

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

类型变更

旧版 API

• CoreMessage[]

更多信息请参阅以下 API Reference：

• Agent.generateLegacy()
• Agent.streamLegacy()

标准 API

• ModelMessage[]

  toolChoice 使用 AI SDK v5 的 ToolChoice 类型。

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

更多信息请参阅以下 API Reference：

• Agent.generate()
• Agent.stream()