> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# Migrer de VNext vers les API standard

À partir de `v0.20.0` pour `@mastra/core`, les modifications suivantes s’appliquent.

## API héritées (AI SDK v4)

Les méthodes d’origine ont été renommées et conservent la rétrocompatibilité avec **AI SDK v4** et les modèles `v1`.

- `.stream()` → `.streamLegacy()`
- `.generate()` → `.generateLegacy()`

## API standard (AI SDK v5)

Ce sont maintenant les API actuelles, avec une compatibilité complète avec **AI SDK v5** et les modèles `v2`.

- `.streamVNext()` → `.stream()`
- `.generateVNext()` → `.generate()`

## Chemins de migration

Si vous utilisez déjà `.streamVNext()` et `.generateVNext()`, utilisez rechercher/remplacer pour changer les méthodes respectivement en `.stream()` et `.generate()`.

Si vous utilisez les anciennes méthodes `.stream()` et `.generate()`, décidez si vous souhaitez effectuer la mise à niveau. Si ce n’est pas le cas, utilisez rechercher/remplacer pour passer à `.streamLegacy()` et `.generateLegacy()`.

Choisissez le chemin de migration qui correspond à vos besoins :

### Continuer à utiliser les modèles AI SDK v4

- Renommez tous vos appels `.stream()` et `.generate()` respectivement en `.streamLegacy()` et `.generateLegacy()`.

> Aucune autre modification n’est requise.

### Continuer à utiliser les modèles AI SDK v5

- Renommez tous vos appels `.streamVNext()` et `.generateVNext()` respectivement en `.stream()` et `.generate()`.

> Aucune autre modification n’est requise.

### Passer d’AI SDK v4 à v5

- Mettez à niveau tous vos packages de fournisseurs de modèles d’une version majeure.

> Cela garantit qu’il s’agit désormais tous de modèles v5. Suivez le guide ci-dessous pour comprendre les différences principales et mettre votre code à jour en conséquence.

## Différences principales

Les méthodes `.stream()` et `.generate()` mises à jour diffèrent de leurs équivalents hérités par leur comportement, leur compatibilité, leurs types de retour et les options disponibles. Cette section souligne les modifications les plus importantes à comprendre lors de la migration.

### Prise en charge des versions de modèle

**Legacy APIs**

- `.generateLegacy()`
- `.streamLegacy()`

Prend uniquement en charge les modèles **AI SDK v4** (`specificationVersion: 'v1'`)

**Standard APIs**

- `.generate()`
- `.stream()`

Prend uniquement en charge les modèles **AI SDK v5** (`specificationVersion: 'v2'`)

> Cela est appliqué à l’exécution avec des messages d’erreur explicites.

### Types de retour

**Legacy APIs**

- `.generateLegacy()` Retourne : `GenerateTextResult` ou `GenerateObjectResult`

- `.streamLegacy()` Retourne : `StreamTextResult` ou `StreamObjectResult`

Consultez les références d’API suivantes pour plus d’informations :

- [Agent.generateLegacy()](https://mastra.zisheng.pro/fr/reference/agents/generateLegacy)
- [Agent.streamLegacy()](https://mastra.zisheng.pro/fr/reference/streaming/agents/streamLegacy)

**Standard APIs**

- `.generate()`

  - `format: 'mastra'` (par défaut) : retourne `MastraModelOutput.getFullOutput()`
  - `format: 'aisdk'` : retourne `AISDKV5OutputStream.getFullOutput()`
  - Appelle en interne `.stream()` et attend `.getFullOutput()`

- `.stream()`

  - `format: 'mastra'` (par défaut) : retourne `MastraModelOutput<OUTPUT>`
  - `format: 'aisdk'` : retourne `AISDKV5OutputStream<OUTPUT>`

Consultez les références d’API suivantes pour plus d’informations :

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

### Contrôle du format

#### Legacy APIs

Pas d’option `format` : retourne toujours des types AI SDK v4

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

#### Standard APIs

Utilisez l’option `format` pour choisir la sortie :

- `'mastra'` (default)
- `'aisdk'` (AI SDK v5 compatible)

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

### Nouvelles options des API standard

Les options suivantes sont disponibles dans les méthodes standard `.stream()` et `generate()`, mais **PAS** dans leurs équivalents hérités :

- `format` : choisissez le format de sortie « mastra » ou « aisdk » :

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

- `system` : message système personnalisé, distinct des instructions.

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

- `structuredOutput` : sortie structurée améliorée avec remplacement de modèle et options personnalisées.

  - `jsonPromptInjection` : permet de remplacer le comportement par défaut qui transmet response\_format au modèle. Cette option injecte du contexte dans le prompt pour contraindre le modèle à retourner des sorties structurées.

  - `model` : si un modèle est ajouté, un sous-agent est créé afin de structurer la réponse de l’Agent principal. L’Agent principal appelle des Tools et retourne du texte, tandis que le sous-agent retourne un objet conforme au schéma fourni. Cette option remplace `experimental_output`.

  - `errorStrategy` : détermine ce qui se passe lorsque la sortie ne correspond pas au schéma :

    - 'warn' : consigne un avertissement
    - 'error' : lève une erreur
    - 'fallback' : retourne une valeur de secours que vous fournissez

    ```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` : conditions d’arrêt flexibles, telles que le nombre d’étapes ou la limite de tokens.

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

- `providerOptions` : options propres au fournisseur, par exemple des paramètres propres à OpenAI.

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

- `onChunk` : callback pour chaque segment de streaming.

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

- `onError` : callback d’erreur.

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

- `onAbort` : callback d’annulation.

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

- `activeTools` : indiquez quels Tools sont actifs pour cette exécution.

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

- `abortSignal` : AbortSignal pour l’annulation.

  ```typescript
  const controller = new AbortController()
  const result = await agent.stream(messages, {
    abortSignal: controller.signal,
  })

  // Later: controller.abort();
  ```

- `prepareStep` : callback avant chaque étape d’une exécution à plusieurs étapes.

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

- `requireToolApproval` : exige une approbation pour tous les appels de Tools.

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

### Options héritées déplacées

- `temperature` and other `modelSettings`.

  Unifiées dans `modelSettings`

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

- `resourceId` and `threadId`.

  Déplacées dans l’objet memory.

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

### Options obsolètes ou supprimées

- `experimental_output`

  Utilisez plutôt `structuredOutput` afin d’autoriser les appels de Tools et le retour d’un objet.

  ```typescript
  const result = await agent.generate(messages, {
    structuredOutput: {
      schema: z.object({
        summary: z.string(),
      }),
      model: 'openai/gpt-5.6-sol',
    },
  })
  ```

- `output`

  La propriété `output` est obsolète au profit de `structuredOutput`. Pour obtenir les mêmes résultats, omettez le modèle et transmettez seulement `structuredOutput.schema`. Vous pouvez ajouter `jsonPromptInjection: true` si votre modèle ne prend pas nativement en charge `response_format`.

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

- `memoryOptions`

  Utilisez plutôt `memory`.

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

### Modifications de types

**Legacy APIs**

- `CoreMessage[]`

Consultez les références d’API suivantes pour plus d’informations :

- [Agent.generateLegacy()](https://mastra.zisheng.pro/fr/reference/agents/generateLegacy)
- [Agent.streamLegacy()](https://mastra.zisheng.pro/fr/reference/streaming/agents/streamLegacy)

**Standard APIs**

- `ModelMessage[]`

  `toolChoice` utilise le type `ToolChoice` d’AI SDK v5.

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

Consultez les références d’API suivantes pour plus d’informations :

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