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

# 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()`.

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

> **Codemod:** Vous pouvez utiliser la CLI codemod de Mastra pour mettre votre code à jour automatiquement :
>
> **npm**:
>
> ```bash
> npx @mastra/codemod@latest v1/mastra-plural-apis .
> ```
>
> **pnpm**:
>
> ```bash
> pnpm dlx @mastra/codemod@latest v1/mastra-plural-apis .
> ```
>
> **Yarn**:
>
> ```bash
> yarn dlx @mastra/codemod@latest v1/mastra-plural-apis .
> ```
>
> **Bun**:
>
> ```bash
> 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`.

```diff
- 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 :
>
> ```bash
> 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.

```diff
- 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 :
>
> ```bash
> 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`.

```diff
- 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 :
>
> ```bash
> 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.

```diff
- 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.

```diff
- 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 :
>
> ```bash
> 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 :

```ts
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.

```diff
// 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.

```diff
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 :
>
> ```bash
> 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`.

```diff
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.

```diff
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.

```typescript
// 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()`.

```diff
- 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 :
>
> ```bash
> 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.

```diff
- 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.

```diff
- 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.

```diff
- 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.

```diff
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 :

```diff
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 :

```diff
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()` :

```diff
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` :

```diff
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 :

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