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

Contrôle du format

Legacy APIs

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

// 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)

// 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 » :

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

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

  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

    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.

  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.

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

• onChunk : callback pour chaque segment de streaming.

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

• onError : callback d’erreur.

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

• onAbort : callback d’annulation.

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

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

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

• abortSignal : AbortSignal pour l’annulation.

  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.

  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.

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

Options héritées déplacées

• temperature and other modelSettings.

  Unifiées dans modelSettings

  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.

  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.

  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.

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

• memoryOptions

  Utilisez plutôt memory.

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

Standard APIs

• ModelMessage[]

  toolChoice utilise le type ToolChoice d’AI SDK v5.

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