從 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()
• Agent.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()
• 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 - 加入模型後，會建立 subagent，將主要 Agent 的回應結構化。主要 Agent 會呼叫 Tool 並傳回文字，而 subagent 則傳回符合你所提供 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 - 每個串流區塊的 callback。

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

• onError - 錯誤 callback。

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

• onAbort - 中止 callback。

  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 - 多步驟執行中每個步驟之前的 callback。

  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。

  已移至記憶體物件。

  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 參考：

• 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 參考：

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