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

# Agent.generate()

La méthode `.generate()` permet à un agent de générer des réponses sans streaming avec des fonctionnalités avancées. Elle accepte des messages et des options de génération facultatives.

## Exemple d’utilisation

Appelez l’agent avec un message pour générer une réponse :

```ts
const result = await agent.generate('message for agent')
```

## Paramètres

**messages** (`string | string[] | CoreMessage[] | AiMessageType[] | UIMessageWithMetadata[]`): Les messages à envoyer à l’agent. Il peut s’agir d’une chaîne unique, d’un tableau de chaînes ou d’objets de message structurés.

**options** (`AgentExecutionOptions<Output, Format>`): Configuration facultative du processus de génération.

**options.maxSteps** (`number`): Nombre maximal d’étapes à exécuter.

**options.stopWhen** (`LoopOptions['stopWhen']`): Conditions d’arrêt de l’exécution (par exemple, nombre d’étapes ou limite de tokens).

**options.onIterationComplete** (`(context: IterationCompleteContext) => { continue?: boolean; feedback?: string } | void | Promise<{ continue?: boolean; feedback?: string } | void>`): Fonction de rappel appelée à la fin de chaque itération. Utilisez-la pour suivre la progression, fournir un retour afin de guider l’agent ou arrêter l’exécution de manière anticipée. Elle reçoit le contexte de l’itération, notamment le texte actuel, les appels d’outils et le motif de fin.

**options.onIterationComplete.context.iteration** (`number`): Numéro de l’itération actuelle (à partir de 1).

**options.onIterationComplete.context.maxIterations** (`number | undefined`): Nombre maximal d’itérations autorisées (s’il est défini).

**options.onIterationComplete.context.text** (`string`): Réponse textuelle de cette itération.

**options.onIterationComplete.context.isFinal** (`boolean`): Indique s’il s’agit de la dernière itération.

**options.onIterationComplete.context.finishReason** (`string`): Motif de fin de cette itération (par exemple, 'stop', 'length' ou 'tool-calls').

**options.onIterationComplete.context.toolCalls** (`ToolCall[]`): Appels d’outils effectués pendant cette itération.

**options.onIterationComplete.context.messages** (`MastraDBMessage[]`): Tous les messages accumulés jusqu’ici.

**options.onIterationComplete.return.continue** (`boolean`): Définissez cette valeur sur false pour arrêter l’exécution de manière anticipée.

**options.onIterationComplete.return.feedback** (`string`): Message de retour destiné à guider la prochaine itération de l’agent.

**options.isTaskComplete** (`IsTaskCompleteConfig`): Configuration de l’évaluation de l’achèvement de la tâche, qui vérifie si celle-ci est terminée. Utilise les évaluateurs de Mastra pour vérifier automatiquement si la réponse de l’agent satisfait aux critères d’achèvement.

**options.isTaskComplete.scorers** (`MastraScorer[]`): Tableau d’évaluateurs qui mesurent l’achèvement de la tâche. Chaque évaluateur renvoie 0 (échec) ou 1 (réussite).

**options.isTaskComplete.strategy** (`'all' | 'any'`): Stratégie de combinaison des résultats des évaluateurs. 'all' exige la réussite de tous les évaluateurs, tandis que 'any' en exige au moins un.

**options.isTaskComplete.onComplete** (`(result: IsTaskCompleteRunResult) => void | Promise<void>`): Fonction de rappel appelée lorsque la vérification de l’achèvement de la tâche se termine. Elle reçoit le résultat accompagné du score de chaque évaluateur.

**options.isTaskComplete.parallel** (`boolean`): Indique si les évaluateurs doivent être exécutés en parallèle.

**options.isTaskComplete.timeout** (`number`): Durée maximale, en millisecondes, d’attente de la fin de tous les évaluateurs.

**options.delegation** (`DelegationConfig`): Configuration de la délégation aux sous-agents. Utilisez-la pour contrôler et surveiller la délégation de tâches par l’agent à d’autres agents, notamment pour modifier ou refuser les délégations et fournir un retour afin de guider le superviseur.

**options.delegation.onDelegationStart** (`(context: DelegationStartContext) => DelegationStartResult | void | Promise<DelegationStartResult | void>`): Appelée avant la délégation à un sous-agent. Utilisez-la pour modifier les paramètres de délégation, refuser entièrement la délégation ou modifier context.requestContext afin d’ajouter des entrées au contexte de requête de l’exécution du sous-agent.

**options.delegation.onDelegationComplete** (`(context: DelegationCompleteContext) => { feedback?: string } | void | Promise<{ feedback?: string } | void>`): Appelée lorsqu’une délégation à un sous-agent se termine. Le contexte comprend une méthode bail() permettant d’arrêter la suite de l’exécution, et vous pouvez renvoyer { feedback } pour guider l’action suivante du superviseur. Le retour est enregistré dans la mémoire du superviseur sous forme de message de l’assistant.

**options.delegation.messageFilter** (`(context: MessageFilterContext) => MastraDBMessage[] | Promise<MastraDBMessage[]>`): Fonction de rappel appelée avant la délégation à un sous-agent. Utilisez-la pour filtrer les messages transmis au sous-agent.

**options.scorers** (`MastraScorers | Record<string, { scorer: MastraScorer['name']; sampling?: ScoringSamplingConfig }>`): Évaluateurs à exécuter sur les résultats de l’exécution.

**options.scorers.scorer** (`string`): Nom de l’évaluateur à utiliser.

**options.scorers.sampling** (`ScoringSamplingConfig`): Configuration de l’échantillonnage pour l’évaluateur.

**options.scorers.sampling.type** (`'none' | 'ratio'`): Type de stratégie d’échantillonnage. Utilisez 'none' pour désactiver l’échantillonnage ou 'ratio' pour un échantillonnage fondé sur un pourcentage.

**options.scorers.sampling.rate** (`number`): Taux d’échantillonnage (0-1). Obligatoire lorsque le type est 'ratio'.

**options.returnScorerData** (`boolean`): Indique si la réponse doit inclure les données d’évaluation détaillées.

**options.onChunk** (`(chunk: ChunkType) => Promise<void> | void`): Fonction de rappel appelée pour chaque fragment pendant la génération.

**options.onError** (`({ error }: { error: Error | string }) => Promise<void> | void`): Fonction de rappel appelée lorsqu’une erreur survient pendant la génération.

**options.onAbort** (`(event: any) => Promise<void> | void`): Fonction de rappel appelée lorsque la génération est interrompue.

**options.activeTools** (`Array<keyof ToolSet> | undefined`): Tableau des noms d’outils qui doivent être actifs pendant l’exécution. Si la valeur est undefined, tous les outils disponibles sont actifs.

**options.abortSignal** (`AbortSignal`): Objet signal qui permet d’interrompre l’exécution de l’agent. Lorsque le signal est interrompu, toutes les opérations en cours prennent fin, y compris les exécutions de sous-agents en cours auxquelles l’agent a délégué des tâches.

**options.prepareStep** (`PrepareStepFunction`): Fonction de rappel appelée avant chaque étape d’une exécution en plusieurs étapes.

**options.requireToolApproval** (`boolean`): Lorsque cette valeur est true, tous les appels d’outils nécessitent une approbation explicite avant leur exécution. La méthode generate() renvoie finishReason: 'suspended' et inclut un suspendPayload contenant les détails de l’appel d’outil (toolCallId, toolName, args). Utilisez approveToolCallGenerate() ou declineToolCallGenerate() pour poursuivre. Consultez Approbation de l’agent pour plus de détails.

**options.autoResumeSuspendedTools** (`boolean`): Lorsque cette valeur est true, reprend automatiquement les outils suspendus quand l’utilisateur envoie un nouveau message dans le même fil. L’agent extrait resumeData du message de l’utilisateur en fonction du resumeSchema de l’outil. Nécessite la configuration de la mémoire.

**options.toolCallConcurrency** (`number`): Nombre maximal d’appels d’outils à exécuter simultanément. La valeur par défaut est 1 lorsqu’une approbation peut être nécessaire, et 10 dans les autres cas.

**options.context** (`ModelMessage[]`): Messages de contexte supplémentaires à fournir à l’agent.

**options.structuredOutput** (`StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>`): Options permettant d’affiner la génération de votre sortie structurée.

**options.structuredOutput.schema** (`StandardJSONSchemaV1`): Schéma JSON standard définissant la structure de sortie attendue.

**options.structuredOutput.model** (`MastraLanguageModel`): Modèle de langage à utiliser pour générer la sortie structurée. S’il est fourni, il permet à l’agent de répondre en plusieurs étapes avec des appels d’outils, du texte et une sortie structurée

**options.structuredOutput.errorStrategy** (`'strict' | 'warn' | 'fallback'`): Stratégie de gestion des erreurs de validation du schéma. 'strict' lève des erreurs, 'warn' consigne des avertissements et 'fallback' utilise des valeurs de secours.

**options.structuredOutput.fallbackValue** (`<S extends ZodTypeAny>`): Valeur de secours à utiliser lorsque la validation du schéma échoue et que errorStrategy vaut 'fallback'.

**options.structuredOutput.instructions** (`string`): Instructions supplémentaires pour le modèle de sortie structurée.

**options.structuredOutput.jsonPromptInjection** (`boolean | 'system' | 'inline' | 'auto'`): Contrôle la manière dont le schéma JSON est transmis au modèle. Définissez cette option sur 'auto' pour utiliser la sortie structurée native lorsqu’elle est prise en charge, et l’injection dans le prompt dans le cas contraire.

**options.structuredOutput.logger** (`IMastraLogger`): Instance facultative de journalisation structurée pendant la génération de la sortie.

**options.structuredOutput.providerOptions** (`ProviderOptions`): Options propres au fournisseur transmises à l’agent interne de structuration. Utilisez-les pour contrôler le comportement du modèle, comme l’effort de raisonnement des modèles de réflexion (par exemple, { openai: { reasoningEffort: 'low' } }).

**options.outputProcessors** (`OutputProcessorOrWorkflow[]`): Processeurs de sortie à utiliser pour cette exécution (remplacent ceux par défaut de l’agent).

**options.maxProcessorRetries** (`number`): Nombre maximal de fois où les processeurs peuvent déclencher une nouvelle tentative pour cette génération. Remplace la valeur maxProcessorRetries par défaut de l’agent.

**options.inputProcessors** (`InputProcessorOrWorkflow[]`): Processeurs d’entrée à utiliser pour cette exécution (remplacent ceux par défaut de l’agent).

**options.instructions** (`string | string[] | CoreSystemMessage | SystemModelMessage | CoreSystemMessage[] | SystemModelMessage[]`): Instructions personnalisées qui remplacent les instructions par défaut de l’agent pour cette exécution. Il peut s’agir d’une chaîne unique, d’un objet de message ou d’un tableau de l’un ou l’autre.

**options.system** (`string | string[] | CoreSystemMessage | SystemModelMessage | CoreSystemMessage[] | SystemModelMessage[]`): Messages système personnalisés à inclure dans le prompt. Il peut s’agir d’une chaîne unique, d’un objet de message ou d’un tableau de l’un ou l’autre. Les messages système fournissent du contexte ou des instructions de comportement supplémentaires qui complètent les instructions principales de l’agent.

**options.output** (`Zod schema | JsonSchema7`): \*\*Obsolète.\*\* Utilisez structuredOutput sans modèle pour obtenir le même résultat. 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 pour la persistance et la récupération des conversations.

**options.memory.thread** (`string | { id: string; metadata?: Record<string, any>, title?: string }`): Identifiant du fil assurant la continuité de la conversation. Peut être un ID sous forme de chaîne ou un objet contenant un ID ainsi que des métadonnées et un titre facultatifs.

**options.memory.resource** (`string`): Identifiant de ressource servant à organiser les conversations par utilisateur, session ou contexte.

**options.memory.options** (`MemoryConfig`): Options supplémentaires de configuration de la mémoire, notamment lastMessages, readOnly, semanticRecall, workingMemory et filterIncompleteToolCalls.

**options.memory.onTitleGenerated** (`(title: string) => void | Promise<void>`): Fonction de rappel déclenchée de manière asynchrone lorsqu’un titre de fil est généré et conservé dans le stockage. La génération du titre s’exécute en arrière-plan et peut se terminer après le retour de generate(). Elle n’est déclenchée que lorsque generateTitle est activé dans les options de mémoire et que le fil ne possède aucun titre.

**options.onFinish** (`LoopConfig['onFinish']`): Fonction de rappel déclenchée à la fin de la génération.

**options.onStepFinish** (`LoopConfig['onStepFinish']`): Fonction de rappel déclenchée après chaque étape de génération.

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

**options.telemetry.isEnabled** (`boolean`): Indique si la collecte de télémétrie est activée.

**options.telemetry.recordInputs** (`boolean`): Indique si les données d’entrée doivent être enregistrées dans la télémétrie.

**options.telemetry.recordOutputs** (`boolean`): Indique si les données de sortie doivent être enregistrées dans la télémétrie.

**options.telemetry.functionId** (`string`): Identifiant de la fonction en cours d’exécution.

**options.modelSettings** (`CallSettings`): Model-specific settings like temperature, maxOutputTokens, topP, etc. These settings control how the language model generates responses.

**options.modelSettings.temperature** (`number`): Controls randomness in generation (0-2). Higher values make output more random.

**options.modelSettings.maxOutputTokens** (`number`): Maximum number of tokens to generate in the response. Note: Use maxOutputTokens (not maxTokens) as per AI SDK v5 convention.

**options.modelSettings.maxRetries** (`number`): Maximum number of retry attempts for failed requests.

**options.modelSettings.topP** (`number`): Nucleus sampling parameter (0-1). Controls diversity of generated text.

**options.modelSettings.topK** (`number`): Top-k sampling parameter. Limits vocabulary to k most likely tokens.

**options.modelSettings.presencePenalty** (`number`): Penalty for token presence (-2 to 2). Reduces repetition.

**options.modelSettings.frequencyPenalty** (`number`): Penalty for token frequency (-2 to 2). Reduces repetition of frequent tokens.

**options.modelSettings.stopSequences** (`string[]`): Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.

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

**options.toolChoice.'auto'** (`string`): Laisse le modèle décider quand utiliser des outils (par défaut).

**options.toolChoice.'none'** (`string`): Désactive complètement l’utilisation des outils.

**options.toolChoice.'required'** (`string`): Force le modèle à utiliser au moins un outil.

**options.toolChoice.{ type: 'tool'; toolName: string }** (`object`): Force le modèle à utiliser un outil précis.

**options.toolsets** (`ToolsetsInput`): Ensembles d’outils supplémentaires utilisables pour cette exécution.

**options.clientTools** (`ToolsInput`): Outils côté client disponibles pendant l’exécution.

**options.hooks** (`ToolHooks`): Hooks propres à l’exécution, exécutés avant et après les appels d’outils. Ils remplacent, pour cette exécution, les hooks correspondants définis au niveau de l’agent. beforeToolCall peut renvoyer { proceed: false, output } pour ignorer l’appel d’outil.

**options.savePerStep** (`boolean`): Enregistre progressivement les messages à la fin de chaque étape de génération (valeur par défaut : false). Désactivé en interne lorsque la mémoire observationnelle est activée.

**options.providerOptions** (`Record<string, Record<string, JSONValue>>`): Options propres au fournisseur transmises au modèle de langage.

**options.providerOptions.openai** (`Record<string, JSONValue>`): Options propres à OpenAI, telles que reasoningEffort, responseFormat, etc.

**options.providerOptions.anthropic** (`Record<string, JSONValue>`): Options propres à Anthropic, telles que maxTokens, etc.

**options.providerOptions.google** (`Record<string, JSONValue>`): Options propres à Google.

**options.providerOptions.\[providerName]** (`Record<string, JSONValue>`): Toute option propre au fournisseur.

**options.runId** (`string`): Identifiant unique de cette exécution.

**options.requestContext** (`RequestContext`): Contexte de requête contenant la configuration et l’état dynamiques.

**options.tracingContext** (`TracingContext`): Contexte de traçage permettant de créer des spans enfants et d’ajouter des métadonnées. Injecté automatiquement lors de l’utilisation du système de traçage de Mastra.

**options.tracingContext.currentSpan** (`Span`): Span actuel permettant de créer des spans enfants et d’ajouter des métadonnées. Utilisez-le pour créer des spans enfants personnalisés ou mettre à jour les attributs des spans pendant l’exécution.

**options.tracingOptions** (`TracingOptions`): Options de configuration du Tracing.

**options.tracingOptions.metadata** (`Record<string, any>`): Métadonnées à ajouter au span racine de la trace. Utiles pour ajouter des attributs personnalisés tels que des ID utilisateur, des ID de session ou des indicateurs de fonctionnalité.

**options.tracingOptions.requestContextKeys** (`string[]`): Clés RequestContext supplémentaires à extraire comme métadonnées pour cette trace. Prend en charge la notation à points pour les valeurs imbriquées (par exemple, 'user.id').

**options.tracingOptions.traceId** (`string`): ID de trace à utiliser pour cette exécution (1 à 32 caractères hexadécimaux). S’il est fourni, cette trace fera partie de la trace indiquée.

**options.tracingOptions.parentSpanId** (`string`): ID du span parent à utiliser pour cette exécution (1 à 16 caractères hexadécimaux). S’il est fourni, le span racine sera créé en tant qu’enfant de ce span.

**options.tracingOptions.tags** (`string[]`): Tags à appliquer à cette trace. Libellés textuels permettant de classer et de filtrer les traces.

**options.versions** (`VersionOverrides`): Remplacements de version propres à chaque appel pour la délégation aux sous-agents. Ils sont fusionnés par-dessus les versions définies au niveau de l’instance Mastra et propagés automatiquement dans les appels de sous-agents via requestContext. Nécessite le package editor. Consultez Gestion des versions de l’éditeur.

**options.versions.agents** (`Record<string, VersionSelector>`): Table de correspondance entre les ID d’agents et leurs sélecteurs de version.

**options.versions.agents.versionId** (`string`): Cible une version précise par son ID.

**options.versions.agents.status** (`'draft' | 'published'`): Cible la version la plus récente ayant ce statut de publication.

**options.includeRawChunks** (`boolean`): Indique si les fragments bruts doivent être inclus dans la sortie du stream. Cette option n’est pas disponible chez tous les fournisseurs de modèles.

## Structure de la réponse

`Agent.generate()` renvoie les données finales collectées pendant l’exécution. `steps` est un tableau d’objets représentant les étapes. Les tableaux d’outils du résultat, notamment `toolCalls` et `toolResults` au niveau supérieur ainsi que les tableaux imbriqués `step.toolCalls` et `step.toolResults`, utilisent le format de fragments de Mastra.

Cela signifie que les données des outils sont encapsulées dans `payload` :

```ts
const response = await agent.generate('Check the weather in Lagos')

for (const toolCall of response.toolCalls) {
  console.log(toolCall.type) // 'tool-call'
  console.log(toolCall.runId)
  console.log(toolCall.from)
  console.log(toolCall.payload.toolName)
  console.log(toolCall.payload.args)
}

for (const step of response.steps) {
  for (const toolResult of step.toolResults) {
    console.log(toolResult.type) // 'tool-result'
    console.log(toolResult.payload.toolName)
    console.log(toolResult.payload.result)
  }
}
```

Pour la version en streaming de ce même format de fragment, consultez la [référence ChunkType](https://mastra.zisheng.pro/fr/reference/streaming/ChunkType).

## Valeurs renvoyées

**result** (`Awaited<ReturnType<MastraModelOutput<Output>['getFullOutput']>>`): Renvoie la sortie complète du processus de génération, notamment le texte, l’objet (en cas de sortie structurée), les appels d’outils, leurs résultats, les statistiques d’utilisation et les informations sur les étapes.

**text** (`string`): Réponse textuelle générée par l’agent.

**object** (`Output | undefined`): Objet de sortie structurée si structuredOutput a été fourni, validé par rapport au schéma.

**toolCalls** (`ToolCallChunk[]`): Tableau des fragments d’appels d’outils effectués pendant la génération.

**toolCalls.type** (`'tool-call'`): Identifiant du type de fragment.

**toolCalls.runId** (`string`): Identifiant de l’exécution.

**toolCalls.from** (`ChunkFrom`): Source du fragment, par exemple AGENT ou WORKFLOW.

**toolCalls.payload** (`ToolCallPayload`): Données de l’appel d’outil.

**toolCalls.payload.toolCallId** (`string`): Identifiant unique de l’appel d’outil.

**toolCalls.payload.toolName** (`string`): Nom de l’outil appelé.

**toolCalls.payload.args** (`Record<string, unknown>`): Arguments transmis à l’outil.

**toolCalls.payload.providerExecuted** (`boolean`): Indique si le fournisseur du modèle a exécuté l’outil directement.

**toolResults** (`ToolResultChunk[]`): Tableau des fragments de résultats issus des exécutions d’outils.

**toolResults.type** (`'tool-result'`): Identifiant du type de fragment.

**toolResults.runId** (`string`): Identifiant de l’exécution.

**toolResults.from** (`ChunkFrom`): Source du fragment, par exemple AGENT ou WORKFLOW.

**toolResults.payload** (`ToolResultPayload`): Données du résultat de l’outil.

**toolResults.payload.toolCallId** (`string`): Identifiant unique de l’appel d’outil.

**toolResults.payload.toolName** (`string`): Nom de l’outil qui a produit le résultat.

**toolResults.payload.result** (`unknown`): Valeur renvoyée par l’outil.

**toolResults.payload.isError** (`boolean`): Indique si l’exécution de l’outil a échoué.

**usage** (`TokenUsage`): Statistiques d’utilisation des tokens pour la génération.

**steps** (`object[]`): Tableau des étapes d’exécution, utile pour déboguer les générations en plusieurs étapes.

**steps.text** (`string`): Texte généré pendant cette étape.

**steps.toolCalls** (`ToolCallChunk[]`): Appels d’outils émis pendant cette étape.

**steps.toolResults** (`ToolResultChunk[]`): Résultats d’outils émis pendant cette étape.

**steps.finishReason** (`string`): Motif de fin de cette étape.

**steps.usage** (`LanguageModelUsage`): Utilisation des tokens pour cette étape.

**steps.request** (`{ body?: unknown }`): Métadonnées de la requête pour cette étape.

**steps.response** (`object`): Métadonnées de la réponse pour cette étape.

**finishReason** (`string`): Motif de fin de la génération. Les valeurs possibles comprennent 'stop' (fin normale), 'tool-calls' (fin avec des appels d’outils), 'suspended' (en attente de l’approbation d’un outil) ou 'error' (une erreur s’est produite).

**response** (`object`): Métadonnées de réponse du fournisseur du modèle. Utiles pour accéder aux en-têtes de limite de débit et aux ID de requête.

**response.id** (`string`): ID de réponse du fournisseur du modèle.

**response.timestamp** (`Date`): Horodatage de la génération de la réponse.

**response.modelId** (`string`): Identifiant du modèle utilisé pour cette réponse.

**response.headers** (`Record<string, string>`): En-têtes de réponse HTTP du fournisseur du modèle. Contiennent des informations sur les limites de débit (par exemple, anthropic-ratelimit-requests-remaining et x-ratelimit-remaining-tokens) ainsi que d’autres métadonnées propres au fournisseur.

**response.messages** (`ResponseMessage[]`): Messages de réponse au format du modèle.

**response.uiMessages** (`UIMessage[]`): Messages de réponse au format de l’interface utilisateur, avec toutes les métadonnées ajoutées par les processeurs de sortie.

**request** (`object`): Requête envoyée au modèle.

**request.body** (`unknown`): Corps de la requête envoyé au fournisseur du modèle.

**warnings** (`LanguageModelWarning[]`): Tous les avertissements émis par le fournisseur du modèle pendant la génération.

**providerMetadata** (`Record<string, unknown>`): Métadonnées propres au fournisseur renvoyées avec la réponse.

**reasoning** (`ReasoningChunk[]`): Détails du raisonnement des modèles qui prennent en charge le raisonnement (par exemple, la série OpenAI o1).

**reasoningText** (`string`): Texte de raisonnement combiné provenant des modèles de raisonnement.

**sources** (`SourceChunk[]`): Sources citées par le modèle pendant la génération.

**files** (`FileChunk[]`): Fichiers générés par le modèle.

**suspendPayload** (`object`): Présent lorsque finishReason vaut 'suspended'. Contient les détails de l’appel d’outil nécessaires pour approuver ou refuser l’appel en attente.

**suspendPayload.toolCallId** (`string`): Identifiant unique de l’appel d’outil en attente.

**suspendPayload.toolName** (`string`): Nom de l’outil qui nécessite une approbation.

**suspendPayload.args** (`Record<string, any>`): Arguments qui seront transmis à l’outil.

**runId** (`string`): Identifiant unique de cette exécution. Obligatoire lors de l’appel de approveToolCallGenerate() ou declineToolCallGenerate() pour reprendre une exécution suspendue.

**traceId** (`string`): ID de trace associé à cette exécution lorsque le Tracing est activé. Utilisez-le pour corréler les journaux et déboguer le flux d’exécution.

**spanId** (`string`): ID du span racine associé à cette exécution lorsque le Tracing est activé. Utilisez-le pour effectuer des recherches et des corrélations au niveau du span.

**messages** (`MastraDBMessage[]`): Tous les messages de cette exécution, notamment l’entrée, l’historique de la mémoire et la réponse.

**rememberedMessages** (`MastraDBMessage[]`): Uniquement les messages chargés depuis la mémoire (historique de la conversation).

**error** (`Error`): Objet d’erreur si la génération a échoué.

**tripwire** (`StepTripwireData`): Données du mécanisme de sécurité si le contenu a été bloqué par un processeur.

**scoringData** (`object`): Données d’évaluation lorsque returnScorerData est activé.

## Autres exemples

### Avec les paramètres du modèle

Exemple de limitation des tokens de sortie et de réglage de la température :

```ts
const limitedResult = await agent.generate('Write a short poem about coding', {
  modelSettings: {
    maxOutputTokens: 50,
    temperature: 0.7,
  },
})
```

### Avec la mémoire

Donnez à votre agent accès à l’historique de la conversation et à sa persistance en configurant les options de mémoire. L’agent peut ainsi mémoriser les interactions précédentes et conserver le contexte d’un message à l’autre.

```ts
const memoryResult = await agent.generate('Remember my favorite color is blue', {
  memory: {
    thread: 'user-123-thread',
    resource: 'user-123',
  },
})
```

### Accéder aux en-têtes de réponse

Certains fournisseurs de modèles renvoient des informations utiles dans les en-têtes de réponse, telles que le nombre de tokens restants ou l’état de la limite de débit. Vous pouvez accéder à ces en-têtes depuis l’objet de résultat une fois la génération terminée.

```ts
const result = await agent.generate('Hello!')
const remainingRequests = result.response?.headers?.['anthropic-ratelimit-requests-remaining']
const remainingTokens = result.response?.headers?.['x-ratelimit-remaining-tokens']
console.log(`Remaining requests: ${remainingRequests}, Remaining tokens: ${remainingTokens}`)
```

### Analyser des images

Les agents peuvent analyser et décrire des images en traitant à la fois leur contenu visuel et le texte qu’elles contiennent. Pour activer l’analyse d’images, transmettez un objet avec `type: 'image'` et l’URL de l’image dans le tableau `content`. Vous pouvez associer le contenu de l’image à des prompts textuels pour guider l’analyse de l’agent.

```typescript
const response = await agent.generate([
  {
    role: 'user',
    content: [
      {
        type: 'image',
        image: 'https://placebear.com/cache/395-205.jpg',
        mimeType: 'image/jpeg',
      },
      {
        type: 'text',
        text: 'Describe the image in detail, and extract all the text in the image.',
      },
    ],
  },
])

console.log(response.text)
```

### Utiliser `maxSteps`

Le paramètre `maxSteps` contrôle le nombre maximal d’appels séquentiels au LLM qu’un agent peut effectuer. Chaque étape génère une réponse et exécute les éventuels appels d’outils avant de traiter le résultat. Limiter le nombre d’étapes aide à éviter les boucles infinies et à réduire la latence. Cela permet également de contrôler l’utilisation des tokens par les agents qui utilisent des outils. La valeur par défaut est 5, mais elle peut être augmentée :

```typescript
const response = await agent.generate('Help me organize my day', {
  maxSteps: 10,
})

console.log(response.text)
```

### Utiliser `onStepFinish`

Vous pouvez suivre la progression des opérations en plusieurs étapes à l’aide de la fonction de rappel `onStepFinish`. Cela est utile pour le débogage ou pour communiquer la progression aux utilisateurs.

`onStepFinish` n’est disponible que lors du streaming ou de la génération de texte sans sortie structurée.

```typescript
const response = await agent.generate('Help me organize my day', {
  onStepFinish: ({ text, toolCalls, toolResults, finishReason, usage }) => {
    console.log({ text, toolCalls, toolResults, finishReason, usage })
  },
})
```

### Utiliser `onTitleGenerated`

Lorsque `generateTitle` est activé dans les options de mémoire, la génération du titre s’exécute de manière asynchrone une fois la réponse terminée. Utilisez `onTitleGenerated` pour réagir lorsque le titre est prêt, par exemple en l’envoyant au client via SSE.

```typescript
const response = await agent.generate('What is quantum computing?', {
  memory: {
    thread: threadId,
    resource: userId,
    onTitleGenerated: title => {
      console.log('Thread title:', title)
    },
  },
})
```