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

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

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.

AgentGenerateOptions

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.

context?:

CoreMessage[]

Messages de contexte supplémentaires à fournir à l'Agent.

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.

StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>

schema:

z.ZodSchema<S>

Schéma Zod servant à valider la sortie.

model:

MastraLanguageModel

Modèle à utiliser pour l'Agent de structuration interne.

errorStrategy?:

'strict' | 'warn' | 'fallback'

Stratégie appliquée en cas d'échec de l'analyse ou de la validation. Utilise 'strict' par défaut.

fallbackValue?:

<S extends ZodTypeAny>

Valeur de repli lorsque errorStrategy vaut 'fallback'.

instructions?:

string

Instructions personnalisées de l'Agent de structuration.

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.

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.

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.

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.

output?:

Zod schema | JsonSchema7

Définit la structure attendue de la sortie. Peut être un objet JSON Schema ou un schéma Zod.

memory?:

object

Configuration de la mémoire. Il s’agit du moyen recommandé pour la gérer.

object

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.

resource:

string

Identifiant de l'utilisateur ou de la ressource associée au fil.

options?:

MemoryConfig

Configuration du comportement de la mémoire, comme l'historique des messages et le rappel sémantique. Consultez MemoryConfig ci-dessous.

maxSteps?:

number

Nombre maximal d'étapes d'exécution autorisées.

maxRetries?:

number

Nombre maximal de nouvelles tentatives. Définissez 0 pour les désactiver.

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

runId?:

string

Identifiant unique de cette exécution de génération. Utile pour le suivi et le débogage.

telemetry?:

TelemetrySettings

Paramètres de collecte de la télémétrie pendant la génération.

TelemetrySettings

isEnabled?:

boolean

Active ou désactive la télémétrie. Désactivée par défaut pendant la phase expérimentale.

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.

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.

functionId?:

string

Identifiant de cette fonction. Utilisé pour regrouper les données de télémétrie par fonction.

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.

toolChoice?:

'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }

Contrôle la manière dont l'Agent utilise les Tools pendant la génération.

'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }

'auto':

string

Laisse le modèle décider s'il doit utiliser des Tools (par défaut).

'none':

string

N'utilise aucun Tool.

'required':

string

Exige que le modèle utilise au moins un Tool.

{ type: 'tool'; toolName: string }:

object

Exige que le modèle utilise un Tool précis, désigné par son nom.

toolsets?:

ToolsetsInput

Ensembles de Tools supplémentaires à mettre à la disposition de l'Agent pendant la génération.

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.

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.

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.

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.

Record<string, Record<string, JSONValue>>

openai?:

Record<string, JSONValue>

Options propres à OpenAI. Exemple : { reasoningEffort: 'high' }

anthropic?:

Record<string, JSONValue>

Options propres à Anthropic. Exemple : { maxTokens: 1000 }

google?:

Record<string, JSONValue>

Options propres à Google. Exemple : { safetySettings: [...] }

[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.

requestContext?:

RequestContext

Contexte de requête destiné à l'injection de dépendances et aux informations contextuelles.

maxTokens?:

number

Nombre maximal de tokens à générer.

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.

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'.

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).

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).

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.

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.

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.

Array<ToolCall>

toolName:

string

Nom du Tool invoqué.

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 pour obtenir des instructions détaillées.

Exemple de migration rapide

Avant (ancienne API)

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

Après (nouvelle API)

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

Exemple d'utilisation avancé

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
• Nouvelle méthode .generate()
• Génération de réponses
• Diffusion des réponses en continu