Migrer d’AI SDK v4 vers v5

Vous recherchez la documentation d’intégration ? Consultez Utiliser AI SDK.

Suivez le guide de migration AI SDK v5 officiel pour connaître toutes les modifications avec rupture de compatibilité du cœur d’AI SDK, les mises à jour de packages et les changements d’API.

Ce guide couvre uniquement les aspects de la migration propres à Mastra.

• Compatibilité des données : les nouvelles données stockées au format v5 ne fonctionneront plus si vous repassez de v5 à v4.
• Recommandation de sauvegarde : conservez des sauvegardes de base de données datant d’avant la mise à niveau vers v5.

Mémoire et stockage

Mastra gère automatiquement les données AI SDK v4 grâce à sa classe interne MessageList, qui prend en charge la conversion de format, notamment de v4 vers v5. Aucune migration de base de données n’est requise. Vos messages existants sont convertis à la volée et continuent de fonctionner après la mise à niveau.

Conversion du format de messages

Lorsque vous devez convertir manuellement des messages entre les formats AI SDK et Mastra, utilisez l’utilitaire convertMessages() :

import { convertMessages } from '@mastra/core/agent'

// Convert AI SDK v4 messages to v5
const aiv5Messages = convertMessages(aiv4Messages).to('AIV5.UI')

// Convert Mastra messages to AI SDK v5
const aiv5Messages = convertMessages(mastraMessages).to('AIV5.Core')

// Supported output formats:
// 'Mastra.V2', 'AIV4.UI', 'AIV5.UI', 'AIV5.Core', 'AIV5.Model'

Cet utilitaire est utile lorsque vous souhaitez récupérer les messages directement depuis votre base de données de stockage et les convertir pour les utiliser dans AI SDK.

Inférence de types pour les Tools

Lorsque vous utilisez des Tools avec TypeScript dans AI SDK v5, Mastra fournit des assistants d’inférence de types qui garantissent la sûreté des types pour les entrées et sorties de vos Tools.

InferUITool

L’assistant de type InferUITool déduit les types d’entrée et de sortie d’un seul Tool Mastra :

app/types.ts

import { InferUITool, createTool } from '@mastra/core/tools'
import { z } from 'zod'

const weatherTool = createTool({
  id: 'get-weather',
  description: 'Get the current weather',
  inputSchema: z.object({
    location: z.string().describe('The city and state'),
  }),
  outputSchema: z.object({
    temperature: z.number(),
    conditions: z.string(),
  }),
  execute: async inputData => {
    return {
      temperature: 72,
      conditions: 'sunny',
    }
  },
})

// Infer the types from the tool
type WeatherUITool = InferUITool<typeof weatherTool>
// This creates:
// {
//   input: { location: string };
//   output: { temperature: number; conditions: string };
// }

InferUITools

L’assistant de type InferUITools déduit les types d’entrée et de sortie de plusieurs Tools :

app/mastra/tools.ts

import { InferUITools, createTool } from '@mastra/core/tools'
import { z } from 'zod'

// Using weatherTool from the previous example
const tools = {
  weather: weatherTool,
  calculator: createTool({
    id: 'calculator',
    description: 'Perform basic arithmetic',
    inputSchema: z.object({
      operation: z.enum(['add', 'subtract', 'multiply', 'divide']),
      a: z.number(),
      b: z.number(),
    }),
    outputSchema: z.object({
      result: z.number(),
    }),
    execute: async inputData => {
      // implementation...
      return { result: 0 }
    },
  }),
}

// Infer types from the tool set
export type MyUITools = InferUITools<typeof tools>
// This creates:
// {
//   weather: { input: { location: string }; output: { temperature: number; conditions: string } };
//   calculator: { input: { operation: "add" | "subtract" | "multiply" | "divide"; a: number; b: number }; output: { result: number } };
// }

Ces assistants de type offrent une prise en charge complète de TypeScript lorsque vous utilisez des Tools Mastra avec les composants d’interface AI SDK v5, en garantissant la sûreté des types dans toute votre application.