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

# Agent.generateLegacy() (ancienne API)

> **Attention:** **Obsolète** : cette méthode est obsolète et fonctionne uniquement avec les anciens adaptateurs de modèle. Pour les adaptateurs actuels, utilisez plutôt [`.generate()`](https://mastra.zisheng.pro/fr/reference/agents/generate).

La méthode `.generateLegacy()` est l'ancienne version de l'API de génération des Agents. Elle s'utilise avec les anciens adaptateurs de modèle pour produire du texte ou des réponses structurées. Cette méthode accepte des messages et des options de génération facultatives.

## Exemple d'utilisation

```typescript
await agent.generateLegacy('message for agent')
```

## Prise en charge des nouvelles tentatives par les Processors

`generateLegacy()` n'exécute ni les Processors d'erreur ni `maxProcessorRetries`. Elle utilise à la place l'ancien chemin de génération du SDK AI.

Les juges des Scorers dotés d'anciens adaptateurs de modèle appellent `generateLegacy()`. Ils ne bénéficient pas du budget coordonné de `StreamErrorRetryProcessor` disponible pour les juges qui utilisent l'API de génération actuelle de Mastra. Utilisez un adaptateur actuel lorsque vous avez besoin des nouvelles tentatives déclenchées par les Processors d'erreur. L'ancienne option `maxRetries` reste distincte et utilise `2` par défaut.

## Paramètres

**messages** (`string | string[] | CoreMessage[] | AiMessageType[] | UIMessageWithMetadata[]`): Messages à envoyer à l'Agent. Il peut s'agir d'une chaîne, d'un tableau de chaînes ou d'objets de message structurés au contenu multimodal (texte, images, etc.).

**options** (`AgentGenerateOptions`): Configuration facultative du processus de génération.

**options.abortSignal** (`AbortSignal`): Objet signal permettant d'annuler l'exécution de l'Agent. Lorsque le signal est déclenché, toutes les opérations en cours sont interrompues.

**options.context** (`CoreMessage[]`): Messages de contexte supplémentaires à fournir à l'Agent.

**options.structuredOutput** (`StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>`): Active la génération de sorties structurées avec une meilleure expérience de développement. Crée et utilise automatiquement un StructuredOutputProcessor en interne.

**options.structuredOutput.schema** (`z.ZodSchema<S>`): Schéma Zod servant à valider la sortie.

**options.structuredOutput.model** (`MastraLanguageModel`): Modèle à utiliser pour l'Agent de structuration interne.

**options.structuredOutput.errorStrategy** (`'strict' | 'warn' | 'fallback'`): Stratégie appliquée en cas d'échec de l'analyse ou de la validation. Utilise 'strict' par défaut.

**options.structuredOutput.fallbackValue** (`<S extends ZodTypeAny>`): Valeur de repli lorsque errorStrategy vaut 'fallback'.

**options.structuredOutput.instructions** (`string`): Instructions personnalisées de l'Agent de structuration.

**options.outputProcessors** (`Processor[]`): Remplace les Processors de sortie définis sur l'Agent. Ces Processors peuvent modifier ou valider les messages de l'Agent avant leur renvoi à l'utilisateur. Ils doivent implémenter l'une des fonctions processOutputResult ou processOutputStream, ou les deux.

**options.inputProcessors** (`Processor[]`): Remplace les Processors d'entrée définis sur l'Agent. Ces Processors peuvent modifier ou valider les messages avant leur traitement par l'Agent. Ils doivent implémenter la fonction processInput.

**options.experimental\_output** (`Zod schema | JsonSchema7`): Remarque : il est préférable d'utiliser la propriété structuredOutput. Active la génération de sorties structurées avec la génération de texte et les appels de Tool. Le modèle génère des réponses conformes au schéma fourni.

**options.instructions** (`string`): Instructions personnalisées qui remplacent celles par défaut de l'Agent pour cette génération. Utiles pour modifier dynamiquement le comportement de l'Agent sans créer de nouvelle instance.

**options.output** (`Zod schema | JsonSchema7`): Définit la structure attendue de la sortie. Peut être un objet JSON Schema ou un schéma Zod.

**options.memory** (`object`): Configuration de la mémoire. Il s’agit du moyen recommandé pour la gérer.

**options.memory.thread** (`string | { id: string; metadata?: Record<string, any>, title?: string }`): Fil de conversation, sous forme d’identifiant textuel ou d’objet contenant un id et des metadata facultatives.

**options.memory.resource** (`string`): Identifiant de l'utilisateur ou de la ressource associée au fil.

**options.memory.options** (`MemoryConfig`): Configuration du comportement de la mémoire, comme l'historique des messages et le rappel sémantique. Consultez MemoryConfig ci-dessous.

**options.maxSteps** (`number`): Nombre maximal d'étapes d'exécution autorisées.

**options.maxRetries** (`number`): Nombre maximal de nouvelles tentatives. Définissez 0 pour les désactiver.

**options.onStepFinish** (`GenerateTextOnStepFinishCallback<any> | never`): Fonction de rappel appelée après chaque étape d'exécution. Elle reçoit les détails de l'étape sous forme de chaîne JSON. Indisponible pour les sorties structurées

**options.runId** (`string`): Identifiant unique de cette exécution de génération. Utile pour le suivi et le débogage.

**options.telemetry** (`TelemetrySettings`): Paramètres de collecte de la télémétrie pendant la génération.

**options.telemetry.isEnabled** (`boolean`): Active ou désactive la télémétrie. Désactivée par défaut pendant la phase expérimentale.

**options.telemetry.recordInputs** (`boolean`): Active ou désactive l'enregistrement des entrées. Activé par défaut. Vous pouvez le désactiver afin d'éviter d'enregistrer des informations sensibles.

**options.telemetry.recordOutputs** (`boolean`): Active ou désactive l'enregistrement des sorties. Activé par défaut. Vous pouvez le désactiver afin d'éviter d'enregistrer des informations sensibles.

**options.telemetry.functionId** (`string`): Identifiant de cette fonction. Utilisé pour regrouper les données de télémétrie par fonction.

**options.temperature** (`number`): Contrôle le caractère aléatoire de la sortie du modèle. Des valeurs élevées (par exemple 0,8) la rendent plus aléatoire, tandis que des valeurs faibles (par exemple 0,2) la rendent plus ciblée et déterministe.

**options.toolChoice** (`'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }`): Contrôle la manière dont l'Agent utilise les Tools pendant la génération.

**options.toolChoice.'auto'** (`string`): Laisse le modèle décider s'il doit utiliser des Tools (par défaut).

**options.toolChoice.'none'** (`string`): N'utilise aucun Tool.

**options.toolChoice.'required'** (`string`): Exige que le modèle utilise au moins un Tool.

**options.toolChoice.{ type: 'tool'; toolName: string }** (`object`): Exige que le modèle utilise un Tool précis, désigné par son nom.

**options.toolsets** (`ToolsetsInput`): Ensembles de Tools supplémentaires à mettre à la disposition de l'Agent pendant la génération.

**options.clientTools** (`ToolsInput`): Tools exécutés côté 'client' de la requête. La fonction d'exécution ne figure pas dans leur définition.

**options.hooks** (`ToolHooks`): Hooks propres à l'exécution, lancés avant et après les appels de Tool. Remplace pour cette exécution les hooks correspondants au niveau de l'Agent. beforeToolCall peut renvoyer { proceed: false, output } pour ignorer l'appel de Tool.

**options.savePerStep** (`boolean`): Enregistre les messages de manière incrémentielle après chaque étape de génération (par défaut : false). Désactivé en interne lorsque la mémoire observationnelle est activée.

**options.providerOptions** (`Record<string, Record<string, JSONValue>>`): Options supplémentaires propres au Provider, transmises au Provider LLM sous-jacent. La structure est { providerName: { optionKey: value } }. Mastra étendant le SDK AI, consultez la documentation du SDK AI pour découvrir toutes les options des Providers.

**options.providerOptions.openai** (`Record<string, JSONValue>`): Options propres à OpenAI. Exemple : { reasoningEffort: 'high' }

**options.providerOptions.anthropic** (`Record<string, JSONValue>`): Options propres à Anthropic. Exemple : { maxTokens: 1000 }

**options.providerOptions.google** (`Record<string, JSONValue>`): Options propres à Google. Exemple : { safetySettings: \[...] }

**options.providerOptions.\[providerName]** (`Record<string, JSONValue>`): Autres options propres au Provider. La clé est le nom du Provider et la valeur est un enregistrement d'options propres à celui-ci.

**options.requestContext** (`RequestContext`): Contexte de requête destiné à l'injection de dépendances et aux informations contextuelles.

**options.maxTokens** (`number`): Nombre maximal de tokens à générer.

**options.topP** (`number`): Échantillonnage par noyau. Il s'agit d'un nombre compris entre 0 et 1. Il est recommandé de définir soit temperature, soit topP, mais pas les deux.

**options.topK** (`number`): Échantillonne uniquement parmi les K meilleures options pour chaque token suivant. Permet d'éliminer les réponses de faible probabilité de la 'longue traîne'.

**options.presencePenalty** (`number`): Paramètre de pénalité de présence. Influe sur la probabilité que le modèle répète des informations déjà présentes dans le prompt. Nombre entre -1 (augmente les répétitions) et 1 (pénalité maximale, réduit les répétitions).

**options.frequencyPenalty** (`number`): Paramètre de pénalité de fréquence. Influe sur la probabilité que le modèle emploie plusieurs fois les mêmes mots ou expressions. Nombre entre -1 (augmente les répétitions) et 1 (pénalité maximale, réduit les répétitions).

**options.stopSequences** (`string[]`): Séquences d'arrêt. Si elles sont définies, le modèle cesse de générer du texte dès que l'une d'elles est produite.

**options.seed** (`number`): Graine entière à utiliser pour l'échantillonnage aléatoire. Si elle est définie et prise en charge par le modèle, les appels produisent des résultats déterministes.

**options.headers** (`Record<string, string | undefined>`): En-têtes HTTP supplémentaires à envoyer avec la requête. Uniquement applicable aux Providers accessibles via HTTP.

## Valeurs renvoyées

**text** (`string`): Réponse textuelle générée. Présente lorsque la sortie est 'text' (aucun schéma fourni).

**object** (`object`): Réponse structurée générée. Présente lorsqu'un schéma est fourni via output, structuredOutput ou experimental\_output.

**toolCalls** (`Array<ToolCall>`): Appels de Tool effectués pendant la génération. Présents dans les modes texte et objet.

**toolCalls.toolName** (`string`): Nom du Tool invoqué.

**toolCalls.args** (`any`): Arguments transmis au Tool.

## Migration vers la nouvelle API

> **Info:** La nouvelle méthode `.generate()` offre des fonctionnalités améliorées, notamment la compatibilité avec le SDK AI v5+, une meilleure gestion des sorties structurées et une meilleure prise en charge de la diffusion en continu. Consultez le [guide de migration](https://mastra.zisheng.pro/fr/guides/migrations/vnext-to-standard-apis) pour obtenir des instructions détaillées.

### Exemple de migration rapide

#### Avant (ancienne API)

```typescript
const result = await agent.generateLegacy('message', {
  temperature: 0.7,
  maxSteps: 3,
})
```

#### Après (nouvelle API)

```typescript
const result = await agent.generate('message', {
  modelSettings: {
    temperature: 0.7,
  },
  maxSteps: 3,
})
```

## Exemple d'utilisation avancé

```typescript
import { z } from 'zod'
import { ModerationProcessor, TokenLimiterProcessor } from '@mastra/core/processors'

await agent.generateLegacy(
  [
    { role: 'user', content: 'message for agent' },
    {
      role: 'user',
      content: [
        {
          type: 'text',
          text: 'message for agent',
        },
        {
          type: 'image',
          imageUrl: 'https://example.com/image.jpg',
          mimeType: 'image/jpeg',
        },
      ],
    },
  ],
  {
    temperature: 0.7,
    maxSteps: 3,
    memory: {
      thread: 'user-123',
      resource: 'test-app',
    },
    toolChoice: 'auto',
    providerOptions: {
      openai: {
        reasoningEffort: 'high',
      },
    },
    // Structured output with better DX
    structuredOutput: {
      schema: z.object({
        sentiment: z.enum(['positive', 'negative', 'neutral']),
        confidence: z.number(),
      }),
      model: 'openai/gpt-5.6-sol',
      errorStrategy: 'warn',
    },
    // Output processors for response validation
    outputProcessors: [
      new ModerationProcessor({ model: 'openai/gpt-5-mini' }),
      new TokenLimiterProcessor({ maxTokens: 1000 }),
    ],
  },
)
```

## Voir aussi

- [Guide de migration](https://mastra.zisheng.pro/fr/guides/migrations/vnext-to-standard-apis)
- [Nouvelle méthode .generate()](https://mastra.zisheng.pro/fr/reference/agents/generate)
- [Génération de réponses](https://mastra.zisheng.pro/fr/docs/agents/overview)
- [Diffusion des réponses en continu](https://mastra.zisheng.pro/fr/docs/agents/overview)