从 VNext 迁移到标准 API

🌐 Migrate from VNext to Standard APIs

截至 v0.20.0 对于 @mastra/core，适用以下更改。

🌐 As of v0.20.0 for @mastra/core, the following changes apply.

旧版 API（AI SDK v4）

🌐 Legacy APIs (AI SDK v4)

原方法已被重命名，并保持与 AI SDK v4 和 v1 模型的向后兼容性。

🌐 The original methods have been renamed and maintain backward compatibility with AI SDK v4 and v1 models.

• .stream() → .streamLegacy()
• .generate() → .generateLegacy()

标准 API（AI SDK v5）

🌐 Standard APIs (AI SDK v5)

这些现在是具有完整 AI SDK v5 和 v2 模型兼容性的当前 API。

🌐 These are now the current APIs with full AI SDK v5 and v2 model compatibility.

• .streamVNext() → .stream()
• .generateVNext() → .generate()

迁移路径

🌐 Migration paths

如果你已经在使用 .streamVNext() 和 .generateVNext()，请使用查找/替换将方法分别改为 .stream() 和 .generate()。

🌐 If you're already using .streamVNext() and .generateVNext() use find/replace to change methods to .stream() and .generate() respectively.

如果你正在使用旧的 .stream() 和 .generate()，请决定是否要升级。如果不升级，请使用查找/替换将其更改为 .streamLegacy() 和 .generateLegacy()。

🌐 If you're using the old .stream() and .generate(), decide whether you want to upgrade or not. If you don't, use find/replace to change to .streamLegacy() and .generateLegacy().

选择适合你需求的迁移路径：

🌐 Choose the migration path that fits your needs:

继续使用 AI SDK v4 模型

🌐 Keep using AI SDK v4 models

• 将所有 .stream() 和 .generate() 调用分别重命名为 .streamLegacy() 和 .generateLegacy()。

不需要进一步更改。

继续使用 AI SDK v5 模型

🌐 Keep using AI SDK v5 models

• 将所有 .streamVNext() 和 .generateVNext() 的调用分别重命名为 .stream() 和 .generate()。

不需要进一步更改。

从 AI SDK v4 升级到 v5

🌐 Upgrade from AI SDK v4 to v5

• 将你所有的模型提供商软件包升级一个主要版本。

这将确保它们现在都是 v5 模型。请按照以下指南了解主要区别，并相应地更新你的代码。

主要区别

🌐 Key differences

更新后的 .stream() 和 .generate() 方法在行为、兼容性、返回类型和可用选项方面与其传统版本有所不同。本节重点介绍在迁移时你需要了解的最重要变化。

🌐 The updated .stream() and .generate() methods differ from their legacy counterparts in behavior, compatibility, return types, and available options. This section highlights the most important changes you need to understand when migrating.

模型版本支持

🌐 Model version support

遗留 API

• .generateLegacy()
• .streamLegacy()

仅支持 AI SDK v4 模型（specificationVersion: 'v1'）

🌐 Only support AI SDK v4 models (specificationVersion: 'v1')

标准 API

• .generate()
• .stream()

仅支持 AI SDK v5 模型（specificationVersion: 'v2'）

🌐 Only support AI SDK v5 models (specificationVersion: 'v2')

这将在运行时强制执行，并提供清晰的错误信息。

返回类型

🌐 Return types

遗留 API

• .generateLegacy() 返回：GenerateTextResult 或 GenerateObjectResult
• .streamLegacy() 返回：StreamTextResult 或 StreamObjectResult

有关更多信息，请参阅以下 API 参考资料：

🌐 See the following API references for more information:

• 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 参考资料：

🌐 See the following API references for more information:

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

格式控制

🌐 Format control

遗留 API

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

🌐 No format option: Always return AI SDK v4 types

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

标准 API

使用 format 选项选择输出：

🌐 Use format option to choose output:

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

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

标准 API 中的新选项

🌐 New options in standard APIs

以下选项在标准的 .stream() 和 generate() 中可用，但在其旧版中不可用：

🌐 The following options are available in the standard .stream() and generate(), but NOT in their legacy counterparts:

• format - 选择 'mastra' 或 'aisdk' 输出格式：

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

• system - 自定义系统消息（与指令分开）。

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

• structuredOutput - 增强的结构化输出，支持模型覆盖和自定义选项。

  • jsonPromptInjection - 用于覆盖将 response_format 传递给模型的默认行为。这会将上下文注入提示中，以强制模型返回结构化输出。

  • model - 如果添加了一个模型，这将创建一个子代理来构建主代理的响应。主代理将调用工具并返回文本，子代理将返回符合你提供的模式的对象。这是对 experimental_output 的替代。

  • errorStrategy - 确定当输出与模式不匹配时会发生什么：

    • 'warn' - 记录警告
    • 'error' - 抛出一个错误
    • 'fallback' - 返回你提供的备用值

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

• stopWhen - 灵活的停止条件（步数计数、令牌限制等）。

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

• providerOptions - 特定于提供商的选项（例如，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 - 指定此执行中哪些工具处于活动状态。

  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 - 所有工具调用都需要审批。

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

已移动的旧版选项

🌐 Legacy options that moved

• temperature 和其他 modelSettings。

  在 modelSettings 中统一

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

• resourceId 和 threadId。

  已移至内存对象。

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

已弃用或已移除的选项

🌐 Deprecated or removed options

• experimental_output

  请改用 structuredOutput，以允许工具调用和对象返回。

  const result = await agent.generate(messages, {
    structuredOutput: {
      schema: z.object({
        summary: z.string(),
      }),
      model: "openai/gpt-5.1",
    },
  });

• 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: {},
  });

类型更改

🌐 Type changes

遗留 API

• CoreMessage[]

有关更多信息，请参阅以下 API 参考资料：

🌐 See the following API references for more information:

• 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 参考资料：

🌐 See the following API references for more information:

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