Classe Agent

La classe Agent a été mise à jour avec une réorganisation des méthodes vocales, de nouveaux modes d’accès aux propriétés et des API de streaming simplifiées.

Modifications

De getAgents à listAgents

La méthode mastra.getAgents() a été renommée mastra.listAgents(). Cette modification respecte la convention de nommage utilisée dans l’ensemble de l’API, selon laquelle les méthodes d’accès plurielles utilisent le préfixe list.

Pour effectuer la migration, remplacez tous les appels à mastra.getAgents() par mastra.listAgents().

- const agents = mastra.getAgents();
+ const agents = mastra.listAgents();

Codemod

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

npm

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

pnpm

pnpm dlx @mastra/codemod@latest v1/mastra-plural-apis .

Yarn

yarn dlx @mastra/codemod@latest v1/mastra-plural-apis .

Bun

bun x @mastra/codemod@latest v1/mastra-plural-apis .

De RuntimeContext à RequestContext

La classe RuntimeContext a été renommée RequestContext dans l’ensemble du code. Ce nouveau nom indique que la classe contient des données propres à la requête et respecte les conventions des frameworks web.

Pour effectuer la migration, remplacez tous les imports et noms de paramètres RuntimeContext/runtimeContext par RequestContext/requestContext.

- import { RuntimeContext } from '@mastra/core/runtime-context';
+ import { RequestContext } from '@mastra/core/request-context';

- const runtimeContext = new RuntimeContext();
- runtimeContext.set('userTier', 'enterprise');
+ const requestContext = new RequestContext();
+ requestContext.set('userTier', 'enterprise');

- await agent.generate(messages, { runtimeContext });
+ await agent.generate(messages, { requestContext });

Codemod

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

npx @mastra/codemod@latest v1/runtime-context .

De l’accès direct aux propriétés aux méthodes d’accès

L’accès direct aux propriétés agent.llm, agent.tools et agent.instructions est obsolète. Cette modification offre une meilleure encapsulation et renforce la cohérence avec la conception générale de l’API.

Pour effectuer la migration, remplacez l’accès aux propriétés par les méthodes d’accès correspondantes.

- const llm = agent.llm;
- const tools = agent.tools;
- const instructions = agent.instructions;
+ const llm = agent.getLLM();
+ const tools = agent.getTools();
+ const instructions = agent.getInstructions();

Codemod

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

npx @mastra/codemod@latest v1/agent-property-access .

Déplacement des méthodes vocales vers l’espace de noms agent.voice

Les méthodes liées à la voix ont été déplacées de la classe Agent vers l’espace de noms agent.voice, qui regroupe les API vocales.

Pour effectuer la migration, modifiez les appels aux méthodes vocales afin d’utiliser l’espace de noms agent.voice.

- await agent.speak('Hello');
- await agent.listen();
- const speakers = agent.getSpeakers();
+ await agent.voice.speak('Hello');
+ await agent.voice.listen();
+ const speakers = agent.voice.getSpeakers();

Codemod

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

npx @mastra/codemod@latest v1/agent-voice .

De agent.fetchMemory() à (await agent.getMemory()).recall()

La méthode fetchMemory() a été remplacée par une API qui rend explicite l’accès asynchrone à la Memory.

Pour effectuer la migration, remplacez les appels à fetchMemory() par la nouvelle API.

- const messages = await agent.fetchMemory({ threadId: 'thread-123' });
+ const memory = await agent.getMemory();
+ const result = await memory.recall({ threadId: 'thread-123' });
+ const messages = result.messages;

Noms des méthodes de Processor : de get* à list*

Les méthodes des Processors de l’Agent ont été renommées du modèle get* au modèle list* pour assurer leur cohérence avec l’ensemble de l’API. Cette modification respecte la convention selon laquelle les méthodes list* renvoient des collections.

Pour effectuer la migration, mettez à jour les noms des méthodes de Processor.

- const inputProcessors = await agent.getInputProcessors(runtimeContext);
- const outputProcessors = await agent.getOutputProcessors(runtimeContext);
+ const inputProcessors = await agent.listInputProcessors(requestContext);
+ const outputProcessors = await agent.listOutputProcessors(requestContext);

Codemod

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

npx @mastra/codemod@latest v1/agent-processor-methods .

Les schémas de sortie structurée Zod v3 et v4 restent pris en charge

Mastra v1 continue d’accepter les schémas Zod v3 et Zod v4 dans les API publiques de l’Agent qui prennent en charge les schémas de sortie structurée. Cela inclut des méthodes telles que agent.generateLegacy() et agent.streamLegacy(), ainsi que les types d’options associés.

Si vous transmettez déjà des schémas Zod aux API de l’Agent, aucune migration n’est nécessaire pour la compatibilité des versions de Zod. Conservez vos imports de schémas existants :

import { z as z3 } from 'zod/v3'
import { z as z4 } from 'zod/v4'

await agent.generateLegacy({
  prompt: 'Summarize this ticket',
  output: z3.object({ summary: z3.string() }),
})

await agent.streamLegacy({
  prompt: 'Extract contact info',
  output: z4.object({ email: z4.string().email() }),
})

Mettez uniquement vos imports à jour si vous souhaitez uniformiser la version de Zod dans l’ensemble de votre application.

Renommage des méthodes d’options par défaut selon la version d’AI SDK

Les méthodes d’options par défaut ont été renommées pour distinguer les anciennes API AI SDK v4 des API AI SDK v5+. Le nom de la méthode indique désormais la version d’AI SDK ciblée.

Pour effectuer la migration, mettez à jour les noms des méthodes selon la version d’AI SDK que vous utilisez.

  // For legacy AI SDK v4
- const options = await agent.getDefaultGenerateOptions();
- const streamOptions = await agent.getDefaultStreamOptions();
+ const options = await agent.getDefaultGenerateOptionsLegacy();
+ const streamOptions = await agent.getDefaultStreamOptionsLegacy();

  // For new AI SDK v5+ (default)
  const streamOptions = await agent.getDefaultStreamOptions();

De modelSettings.abortSignal à abortSignal au niveau supérieur

L’option abortSignal a été déplacée de modelSettings vers le niveau supérieur des options de stream et de génération. Le contrôle de l’exécution se trouve désormais en dehors des paramètres propres au modèle.

Pour effectuer la migration, déplacez abortSignal de modelSettings vers le niveau supérieur.

  agent.stream('Hello', {
-   modelSettings: {
-     abortSignal: abortController.signal,
-   },
+   abortSignal: abortController.signal,
  });

Codemod

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

npx @mastra/codemod@latest v1/agent-abort-signal .

De output à structuredOutput.schema

Les options obsolètes output et experimental_output ont été supprimées. Cette modification unifie la sortie structurée autour d’une API unique et stable.

Pour effectuer la migration, remplacez output ou experimental_output par structuredOutput.schema.

  agent.stream('Hello', {
-   output: z.object({ result: z.string() }),
+   structuredOutput: {
+     schema: z.object({ result: z.string() }),
+   },
  });

Le champ id de l’Agent est désormais obligatoire

Le champ id est désormais obligatoire lors de la création d’un Agent. Auparavant, les Agents pouvaient être créés sans ID explicite, mais ce n’est plus pris en charge.

Pour effectuer la migration, ajoutez un champ id à toutes les configurations d’Agent.

  const agent = new Agent({
+   id: 'my-agent',
    name: 'My Agent',
    instructions: 'You are a helpful assistant',
    model: 'openai/gpt-5.6-sol',
  });

L’id peut être identique au name, ou vous pouvez utiliser un autre identifiant. L’ID est utilisé lors de l’appel à mastra.getAgentById() et doit être unique au sein de votre instance Mastra.

// Register agent with Mastra
const mastra = new Mastra({
  agents: {
    myAgent: agent, // key can differ from id
  },
})

// Retrieve by ID
const agent = mastra.getAgentById('my-agent')

Les réponses des API de stream masquent désormais les données sensibles

Le serveur Mastra masque désormais automatiquement les informations sensibles dans les réponses diffusées de l’Agent. Cela évite l’exposition accidentelle des prompts système, des définitions de Tools et des clés d’API dans les fragments de flux step-start, step-finish et finish.

Données masquées :

• request.body contenant les payloads des requêtes au LLM (prompts système, schémas de Tools)
• metadata.request dans les résultats d’étape
• output.steps[].request dans les données d’étape imbriquées

Ce comportement est activé par défaut. Si vous devez accéder aux données complètes de la requête, par exemple pour le débogage ou des services internes, vous pouvez désactiver le masquage lorsque vous utilisez directement des adaptateurs de serveur, tels que @mastra/hono ou @mastra/express.

Suppressions

Méthodes generateVNext et streamVNext

Les méthodes obsolètes generateVNext() et streamVNext() ont été supprimées. Elles étaient auparavant utilisées pour assurer la compatibilité avec AI SDK v5+, dont l’implémentation est désormais celle utilisée par défaut.

Pour effectuer la migration, utilisez les méthodes standard generate() et stream().

- const result = await agent.generateVNext('Hello');
- const stream = await agent.streamVNext('Hello');
+ const result = await agent.generate('Hello');
+ const stream = await agent.stream('Hello');

Codemod

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

npx @mastra/codemod@latest v1/agent-generate-stream-v-next .

Suppression du paramètre format de stream() et generate()

Le paramètre format a été supprimé des méthodes agent.stream() et agent.generate(). Les transformations des flux AI SDK sont désormais gérées par le package @mastra/ai-sdk. Cette modification améliore le tree-shaking en déplaçant le code propre à AI SDK vers un package dédié.

Pour effectuer la migration, utilisez la fonction toAISdkStream() du package @mastra/ai-sdk afin de convertir le format AI SDK.

- const stream = await agent.stream(messages, {
-   format: 'aisdk',
- });

+ import { toAISdkStream } from '@mastra/ai-sdk';
+ 
+ const stream = await agent.stream(messages);
+ const aiSdkStream = toAISdkStream(stream, { from: 'agent' });

Méthode agent.toStep()

La méthode toStep() a été supprimée de la classe Agent. Les Agents peuvent désormais être ajoutés directement aux étapes des Workflows sans conversion explicite.

Pour effectuer la migration, ajoutez directement les Agents aux étapes des Workflows. Les Workflows gèrent automatiquement la transformation.

- const step = agent.toStep();
- const workflow = new Workflow({
-   steps: [step],
- });

+ const workflow = new Workflow({
+   steps: [agent],
+ });

Suppression du paramètre générique TMetrics de l’Agent

Le paramètre générique TMetrics a été supprimé d’AgentConfig et du constructeur Agent. Les métriques et les Scorers sont désormais configurés avec l’API des Scorers au lieu de faire partie du système de types de l’Agent.

Pour effectuer la migration, supprimez le paramètre générique TMetrics et configurez les Scorers avec la nouvelle API.

- const agent = new Agent<AgentId, Tools, Metrics>({
+ const agent = new Agent<AgentId, Tools>({
    // ...
  });

Modification du format des réponses tripwire

Le format des réponses tripwire est passé de champs tripwire et tripwireReason distincts à un seul objet tripwire contenant toutes les données associées.

Pour effectuer la migration, mettez votre code à jour afin d’accéder aux données tripwire depuis la nouvelle structure de l’objet.

  const result = await agent.generate('Hello');

- if (result.tripwire) {
-   console.log(result.tripwireReason);
- }
+ if (result.tripwire) {
+   console.log(result.tripwire.reason);
+   // New fields available:
+   // result.tripwire.retry - whether this step should be retried
+   // result.tripwire.metadata - additional metadata from the processor
+   // result.tripwire.processorId - which processor triggered the tripwire
+ }

Pour les réponses diffusées :

  for await (const chunk of stream.fullStream) {
    if (chunk.type === 'tripwire') {
-     console.log(chunk.payload.tripwireReason);
+     console.log(chunk.payload.reason);
+     // New fields available:
+     // chunk.payload.retry
+     // chunk.payload.metadata
+     // chunk.payload.processorId
    }
  }

Les résultats des étapes incluent désormais aussi les informations tripwire :

  const result = await agent.generate('Hello');

  for (const step of result.steps) {
-   // No tripwire info on steps
+   if (step.tripwire) {
+     console.log('Step was blocked:', step.tripwire.reason);
+   }
  }

Format des messages de prepareStep

Le callback prepareStep reçoit désormais les messages au format MastraDBMessage au lieu du format de message de modèle AI SDK v5+. Cette modification harmonise prepareStep avec la nouvelle méthode de Processor processInputStep, qui s’exécute à chaque étape de la boucle agentique.

Si vous avez besoin de l’ancien format AI SDK v5+, utilisez messageList.get.all.aiV5.model() :

  agent.generate('Hello', {
    prepareStep: async ({ messages, messageList }) => {
-     // messages was AI SDK v5+ ModelMessage format
-     console.log(messages[0].content);
+     // messages is now MastraDBMessage format
+     // Use messageList to get AI SDK v5+ format if needed:
+     const aiSdkMessages = messageList.get.all.aiV5.model();

      return { toolChoice: 'auto' };
    },
  });

Déplacement de threadId et resourceId vers l’option memory

Les options threadId et resourceId ont été supprimées d’agent.stream() et agent.generate(). Utilisez plutôt l’option memory, qui fournit une API plus claire pour configurer la Memory.

Pour effectuer la migration, déplacez threadId et resourceId dans l’option memory :

  await agent.stream('Hello', {
-   threadId: 'thread-123',
-   resourceId: 'user-456',
+   memory: {
+     thread: 'thread-123',
+     resource: 'user-456',
+   },
  });

L’option memory permet également de transmettre les métadonnées du thread lors de la création de nouveaux threads :

await agent.stream('Hello', {
  memory: {
    thread: {
      id: 'thread-123',
      title: 'Support conversation',
      metadata: { category: 'billing' },
    },
    resource: 'user-456',
  },
})