Classe Mastra

La classe Mastra a été restructurée afin de limiter les imports de premier niveau et de remplacer l’accès direct aux propriétés par des méthodes de récupération.

Modifications

Des imports de premier niveau aux imports de sous-chemins

Le fichier d’index principal de @mastra/core n’exporte désormais que Mastra et Config. Tous les autres exports ont été déplacés vers des imports de sous-chemins. Cette modification améliore le tree-shaking et réduit la taille des bundles en permettant aux outils de regroupement d’éliminer le code inutilisé.

Pour effectuer la migration, mettez à jour tous les imports depuis @mastra/core afin d’utiliser le sous-chemin approprié.

- import { Mastra, Agent, Workflow, createTool } from '@mastra/core';
+ import { Mastra, type Config } from '@mastra/core';
+ import { Agent } from '@mastra/core/agent';
+ import { Workflow } from '@mastra/core/workflows';
+ import { createTool } from '@mastra/core/tools';

Codemod

Vous pouvez utiliser la CLI codemod de Mastra pour mettre à jour votre code automatiquement :

npx @mastra/codemod@latest v1/mastra-core-imports .

De experimental_auth à auth

La configuration d’authentification expérimentale est devenue stable. Cette modification indique que l’API d’authentification est désormais stable et prête pour la production.

Pour effectuer la migration, renommez la clé experimental_auth en auth dans votre configuration Mastra.

  const mastra = new Mastra({
-   experimental_auth: {
+   auth: {
      provider: workos,
    },
  });

Codemod

Vous pouvez utiliser la CLI codemod de Mastra pour mettre à jour votre code automatiquement :

npx @mastra/codemod@latest v1/experimental-auth .

Paramètre id obligatoire pour toutes les primitives Mastra

Tous les stockages, magasins vectoriels, Agents, Workflows, mcpServers, processeurs, scorers et Tools exigent désormais un paramètre id lors de leur initialisation. Cela permet de standardiser l’API Mastra et d’éviter les conflits d’ID.

Toutes ces primitives disposent également désormais des fonctions get, list et add.

Pour effectuer la migration, ajoutez un paramètre id à toutes les instanciations de stockage et de magasin vectoriel. Lorsque vous utilisez plusieurs fois la même classe de stockage ou de vecteurs, veillez à attribuer un ID unique à chaque instance.

- const storage = new LibSQLStore({
-   url: ':memory:',
- });
+ const storage = new LibSQLStore({
+   id: 'my-app-storage',
+   url: ':memory:',
+ });

- const vector = new PgVector({
-   connectionString: process.env.DATABASE_URL,
- });
+ const vector = new PgVector({
+   id: 'my-app-vector',
+   connectionString: process.env.DATABASE_URL,
+ });

Lorsque vous utilisez des instances distinctes à des fins différentes, choisissez des ID uniques et explicites :

  const agentMemory = new Memory({
    storage: new LibSQLStore({
-     url: 'file:./agent.db',
+     id: 'weather-agent-memory-storage',
+     url: 'file:./agent.db',
    }),
  });

  const mastra = new Mastra({
    storage: new LibSQLStore({
+     id: 'mastra-storage',
      url: ':memory:',
    }),
  });

Passage des API de primitives au pluriel de get<primitives> à list<primitive>

Les fonctions get* qui renvoyaient toutes les instances d’une primitive ont été renommées list* afin de mieux refléter leur rôle.

- const agents = mastra.getAgents();
+ const agents = mastra.listAgents();
- const vectors = mastra.getVectors();
+ const vectors = mastra.listVectors();
- const workflows = mastra.getWorkflows();
+ const workflows = mastra.listWorkflows();
- const scorers = mastra.getScorers();
+ const scorers = mastra.listScorers();
- const mcpServers = mastra.getMCPServers();
+ const mcpServers = mastra.listMCPServers();
- const logsByRunId = await mastra.getLogsByRunId({ runId: 'id', transportId: 'id' });
+ const logsByRunId = await mastra.listLogsByRunId({ runId: 'id', transportId: 'id' });
- const logs = await mastra.getLogs('transportId');
+ const logs = await mastra.listLogs('transportId');

Codemod

Vous pouvez utiliser la CLI codemod de Mastra pour mettre à jour votre code automatiquement :

npx @mastra/codemod@latest v1/mastra-plural-apis .

Chaque primitive possède une fonction getById et une fonction get

mastra.getMCPServer('myServer') // Works (registry key)
mastra.getMCPServerById('my-mcp-server') // Works (intrinsic ID)

L’enregistrement des Tools utilise désormais leurs ID intrinsèques

Lorsque des Tools provenant d’Agents ou de serveurs MCP sont enregistrés automatiquement auprès de l’instance Mastra, ils utilisent désormais l’id intrinsèque du Tool plutôt que la clé de l’objet de configuration. Cela évite les collisions lorsque plusieurs Agents ou serveurs MCP possèdent des Tools associés à la même clé de configuration.

Pour effectuer la migration, mettez à jour tout code qui référence les Tools par leurs clés de configuration afin d’utiliser plutôt l’ID intrinsèque du Tool.

  const agent = new Agent({
    id: 'agent1',
    tools: {
      searchTool: weatherSearchTool,
    },
  });

- mastra.getTool('searchTool');
+ mastra.getTool(weatherSearchTool.id);