> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/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/ja/reference/agents/generateLegacy)
- [Agent.streamLegacy()](https://mastra.zisheng.pro/ja/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/ja/reference/agents/generate)
- [Agent.stream()](https://mastra.zisheng.pro/ja/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` - カスタム System Message（instructions とは別）。

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

- `structuredOutput` - モデルの上書きとカスタムオプションに対応した、拡張された構造化出力。

  - `jsonPromptInjection` - モデルへ response\_format を渡すデフォルト動作を上書きします。モデルに構造化出力を返させるため、Prompt にコンテキストを注入します。

  - `model` - モデルを追加すると、メイン Agent のレスポンスを構造化する Subagent が作成されます。メイン 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` - 柔軟な停止条件（Step 数、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` - 各 Streaming Chunk の Callback。

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

- `onError` - Error Callback。

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

- `onAbort` - Abort Callback。

  ```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` - 複数 Step の実行で、各 Step の前に呼び出す Callback。

  ```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`

  Tool 呼び出しとオブジェクトの戻り値に対応するには、代わりに `structuredOutput` を使用します。

  ```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/ja/reference/agents/generateLegacy)
- [Agent.streamLegacy()](https://mastra.zisheng.pro/ja/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/ja/reference/agents/generate)
- [Agent.stream()](https://mastra.zisheng.pro/ja/reference/streaming/agents/stream)