> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt # Classe Agent La classe `Agent` constitue la base de la création d’Agents IA dans Mastra. Elle fournit des méthodes permettant de générer des réponses et de diffuser des interactions en continu. Elle prend également en charge les fonctionnalités vocales. ## Exemples d’utilisation ### Instructions de base sous forme de chaîne Transmettre les instructions sous forme de chaîne ou de tableau de chaînes est la méthode la plus simple pour configurer un Agent. Cette approche convient aux cas d’utilisation simples qui nécessitent de fournir un prompt sans configuration supplémentaire. ```typescript import { Agent } from '@mastra/core/agent' // String instructions export const agent = new Agent({ id: 'test-agent', name: 'Test Agent', instructions: 'You are a helpful assistant that provides concise answers.', model: 'openai/gpt-5.6-sol', }) // System message object export const agent2 = new Agent({ id: 'test-agent-2', name: 'Test Agent 2', instructions: { role: 'system', content: 'You are an expert programmer', }, model: 'openai/gpt-5.6-sol', }) // Array of system messages export const agent3 = new Agent({ id: 'test-agent-3', name: 'Test Agent 3', instructions: [ { role: 'system', content: 'You are a helpful assistant' }, { role: 'system', content: 'You have expertise in TypeScript' }, ], model: 'openai/gpt-5.6-sol', }) ``` ### Configurations propres aux Providers Chaque Provider de modèle propose également différentes options, notamment la mise en cache des prompts et la configuration du raisonnement. Vous pouvez définir `providerOptions` au niveau des instructions afin d’appliquer une stratégie de cache différente à chaque instruction système ou prompt. ```typescript import { Agent } from '@mastra/core/agent' export const agent = new Agent({ id: 'core-message-agent', name: 'Core Message Agent', instructions: { role: 'system', content: 'You are a helpful assistant specialized in technical documentation.', providerOptions: { openai: { reasoningEffort: 'low', }, }, }, model: 'openai/gpt-5.6-sol', }) ``` ### Formats d’instructions mixtes ```typescript import { Agent } from '@mastra/core/agent' // This could be customizable based on the user const preferredTone = { role: 'system', content: 'Always maintain a professional and empathetic tone.', } export const agent = new Agent({ id: 'multi-message-agent', name: 'Multi Message Agent', instructions: [ { role: 'system', content: 'You are a customer service representative.' }, preferredTone, { role: 'system', content: 'Escalate complex issues to human agents when needed.', providerOptions: { anthropic: { cacheControl: { type: 'ephemeral' } }, }, }, ], model: 'anthropic/claude-sonnet-4-6', }) ``` ## Chaînes de modèle Pour la configuration la plus simple, transmettez `model` sous forme de chaîne au format `provider/model`. Séparez le nom du Provider de celui du modèle par une barre oblique. Mastra lit dans l’environnement les identifiants correspondant au Provider ; ce format ne nécessite donc ni package ni import de Provider. Chaînes et identifiants des Providers courants : - **OpenAI** : `openai/gpt-5.6-sol` utilise `OPENAI_API_KEY`. - **Anthropic** : `anthropic/claude-sonnet-4-6` utilise `ANTHROPIC_API_KEY`. - **Google** : `google/gemini-2.5-pro` utilise `GOOGLE_API_KEY` ou `GOOGLE_GENERATIVE_AI_API_KEY`. Consultez les [modèles](https://mastra.zisheng.pro/fr/models) pour découvrir les ID de modèle pris en charge et les [variables d’environnement](https://mastra.zisheng.pro/fr/models/environment-variables) pour obtenir la liste complète des Providers. ## Signaux de thread Utilisez les signaux d’Agent pour envoyer en temps réel des entrées et du contexte à un thread de mémoire. Les API de message sont destinées aux entrées rédigées par l’utilisateur. `sendSignal()` est l’API de bas niveau du contexte généré par le système. Lorsque le thread cible est actif, `sendMessage()` distribue le message dans la boucle active de l’Agent. Lorsque le thread est inactif, Mastra démarre par défaut un flux dont le message constitue la première entrée. ```typescript const subscription = await agent.subscribeToThread({ resourceId: 'user-123', threadId: 'thread-abc', }) void (async () => { for await (const chunk of subscription.stream) { console.log(chunk) } })() agent.sendMessage('Use the latest customer note too.', { resourceId: 'user-123', threadId: 'thread-abc', ifIdle: { streamOptions: { maxSteps: 3, }, }, }) ``` Utilisez `attributes` pour identifier différents utilisateurs dans un thread partagé. Les attributs sont rendus au format XML afin que le modèle puisse distinguer les auteurs des messages : ```typescript agent.sendMessage( { contents: 'Can we simplify the API surface?', attributes: { name: 'Devin', from: 'slack' }, }, { resourceId: 'user-123', threadId: 'thread-abc' }, ) ``` Le modèle reçoit le contenu suivant : ```xml Can we simplify the API surface? ``` Utilisez `ifActive.attributes` et `ifIdle.attributes` lorsque le message doit transporter un contexte différent selon que le thread est actif ou non : ```typescript agent.sendMessage( { contents: 'Also cover the edge cases.', attributes: { source: 'chat' }, }, { resourceId: 'user-123', threadId: 'thread-abc', ifActive: { attributes: { delivery: 'while-active' } }, ifIdle: { attributes: { delivery: 'new-message' } }, }, ) ``` Lorsque le thread est actif, le modèle voit : ```xml Also cover the edge cases. ``` Lorsque le thread est inactif, le modèle voit : ```xml Also cover the edge cases. ``` L’interface utilisateur voit le contenu du message et peut également lire `attributes` et `metadata` dans le message de signal afin de personnaliser le rendu, par exemple en affichant les noms des utilisateurs, leurs avatars ou les badges de leur plateforme. ### `sendMessage(message, options)` Envoie un message utilisateur à une exécution active ou à un thread de mémoire. Utilisez cette méthode lorsque l’Agent actif doit recevoir le message immédiatement. **message** (`string | Array | { contents: string | Array; attributes?: Record; metadata?: Record; providerOptions?: ProviderMetadata }`): Entrée rédigée par l’utilisateur. Les chaînes simples et les parties dépourvues d’attributs sont envoyées au modèle comme une entrée utilisateur normale. Lorsque attributes est présent, Mastra rend le message comme un élément XML \ incluant les attributs. **options** (`object`): Comportement de ciblage et de distribution du message. **options.runId** (`string`): ID d’exécution à cibler directement. Utilisez cette option si vous connaissez déjà l’ID de l’exécution active. **options.resourceId** (`string`): ID de ressource du thread de mémoire. Obligatoire avec threadId pour les messages ciblant un thread. **options.threadId** (`string`): ID du thread à cibler. Obligatoire avec resourceId pour les messages ciblant un thread. **options.ifActive** (`object`): Contrôle le comportement lorsque le thread cible est actif. **options.ifActive.behavior** (`'deliver' | 'persist' | 'discard'`): Contrôle le comportement lorsque le thread cible est actif. Utilise par défaut deliver. **options.ifActive.attributes** (`Record`): Attributs fusionnés dans le message lorsque Mastra l’accepte pendant que le thread cible est actif. **options.ifIdle** (`object`): Contrôle le comportement lorsque le thread cible est inactif. **options.ifIdle.behavior** (`'wake' | 'persist' | 'discard'`): Contrôle le comportement lorsque le thread cible est inactif. Utilise par défaut wake. **options.ifIdle.streamOptions** (`AgentExecutionOptions`): Options du flux qui démarre lorsque ifIdle.behavior vaut wake. Mastra utilise les valeurs resourceId et threadId de premier niveau pour le contexte de mémoire. **options.ifIdle.attributes** (`Record`): Attributs fusionnés dans le message lorsque Mastra l’accepte pendant que le thread cible est inactif. Définissez `ifIdle.behavior` sur `wake` et transmettez `ifIdle.streamOptions` lorsqu’un thread inactif doit démarrer un nouveau flux avec des options d’exécution personnalisées : ```typescript agent.sendMessage('Continue with the next step.', { resourceId: 'user-123', threadId: 'thread-abc', ifIdle: { behavior: 'wake', streamOptions: { maxSteps: 3, }, }, }) ``` Renvoie `{ accepted: Promise, signal: CreatedAgentSignal, persisted?: Promise }`. `accepted` est résolue au moment de la décision, dès que Mastra détermine le traitement du message : `{ action: 'wake', runId, output }` lorsque ce processus exécute l’Agent (il a démarré l’exécution ou obtenu le bail nécessaire), `{ action: 'deliver', runId }` lorsque le message est transmis à une exécution existante (y compris lorsque ce processus perd une course de réveil interprocessus), ou `{ action: 'persist' }` / `{ action: 'discard' }` lorsqu’aucune exécution n’a eu lieu. `runId` est l’ID de référence de l’exécution qui a traité le message ; il n’est présent que pour `wake` et `deliver`. Pour `persist`/`discard`, utilisez `result.signal.id` afin de corréler le message stocké. `accepted` est résolue pour le routage (une erreur de génération lors d’une exécution `wake` remonte par `output.consumeStream()`) et n’est rejetée que si le message n’a pas pu être routé ni démarré, par exemple en cas d’Agent mal configuré. `persisted` n’est présent que pour le comportement `persist` et est résolu lorsque Mastra termine l’écriture du message dans la mémoire. Pour l’action `wake`, `output` correspond au flux de l’Agent destiné à être consommé dans le processus. ### `queueMessage(message, options)` Place un message utilisateur dans la file d’attente du prochain tour d’un thread. Si le thread est actif, Mastra attend la fin de l’exécution active, puis démarre une nouvelle exécution avec le message en attente. Si le thread est inactif, Mastra démarre immédiatement une exécution. ```typescript agent.queueMessage('Also check whether the tests need updates.', { resourceId: 'user-123', threadId: 'thread-abc', }) ``` `queueMessage()` accepte la même structure de `message` et d’`options` que `sendMessage()` et renvoie `{ accepted: Promise, signal: CreatedAgentSignal, persisted?: Promise }`, avec la même sémantique d’`accepted` que `sendMessage()`. ### `sendSignal(signal, options)` Envoie un signal à une exécution active ou à un thread de mémoire. **signal** (`{ type: 'user' | 'state' | 'reactive' | 'notification' | 'user-message' | 'system-reminder'; tagName?: string; contents: string | Array; attributes?: Record; metadata?: Record; providerOptions?: ProviderMetadata }`): Contexte du signal à envoyer au thread. type correspond à la catégorie sémantique du signal. tagName contrôle le tag XML présenté au modèle. Par exemple, { type: 'notification', tagName: 'github-review' } est rendu sous la forme \...\. Les anciennes charges utiles user-message et system-reminder sont toujours acceptées et normalisées. Les valeurs type inconnues sont rejetées ; utilisez tagName pour les tags XML personnalisés. **options** (`object`): Comportement de ciblage et de distribution du signal. **options.runId** (`string`): ID d’exécution à cibler directement. Utilisez cette option si vous connaissez déjà l’ID de l’exécution active. **options.resourceId** (`string`): ID de ressource du thread de mémoire. Obligatoire avec threadId pour les signaux ciblant un thread. **options.threadId** (`string`): ID du thread à cibler. Obligatoire avec resourceId pour les signaux ciblant un thread. **options.ifActive** (`object`): Contrôle le comportement lorsque le thread cible est actif. **options.ifActive.behavior** (`'deliver' | 'persist' | 'discard'`): Contrôle le comportement lorsque le thread cible est actif. Utilise par défaut deliver. **options.ifActive.attributes** (`Record`): Attributs fusionnés dans le signal lorsque Mastra l’accepte pendant que le thread cible est actif. **options.ifIdle** (`object`): Contrôle le comportement lorsque le thread cible est inactif. **options.ifIdle.behavior** (`'wake' | 'persist' | 'discard'`): Contrôle le comportement lorsque le thread cible est inactif. Utilise par défaut wake. **options.ifIdle.streamOptions** (`AgentExecutionOptions`): Options du flux qui démarre lorsque ifIdle.behavior vaut wake. Mastra utilise les valeurs resourceId et threadId de premier niveau pour le contexte de mémoire. **options.ifIdle.attributes** (`Record`): Attributs fusionnés dans le signal lorsque Mastra l’accepte pendant que le thread cible est inactif. Renvoie `{ accepted: Promise, signal: CreatedAgentSignal, persisted?: Promise }`. `accepted` est résolue au moment de la décision, dès que Mastra détermine le traitement du signal : `{ action: 'wake', runId, output }` lorsque ce processus exécute l’Agent (il a démarré l’exécution ou obtenu le bail nécessaire), `{ action: 'deliver', runId }` lorsque le signal est transmis à une exécution existante (y compris lorsque ce processus perd une course de réveil interprocessus), ou `{ action: 'persist' }` / `{ action: 'discard' }` lorsqu’aucune exécution n’a eu lieu. `action` reflète le `behavior` retenu parmi `ifActive`/`ifIdle`. `runId` est l’ID de référence de l’exécution qui a traité le signal ; il n’est présent que pour `wake` et `deliver`. Pour `persist`/`discard`, utilisez `result.signal.id` afin de corréler le signal stocké. `accepted` est résolue pour le routage (une erreur de génération lors d’une exécution `wake` remonte par `output.consumeStream()`) et n’est rejetée que si le signal n’a pas pu être routé ni démarré, par exemple en cas d’Agent mal configuré. `persisted` n’est présent que pour le comportement `persist` et est résolu lorsque Mastra termine l’écriture du signal dans la mémoire. Pour l’action `wake`, `output` correspond au flux de l’Agent destiné à être consommé dans le processus. Dans les handlers serverless, attendez `accepted` et transmettez la sortie `wake` à l’équivalent de `waitUntil` sur votre plateforme, afin que le processus retenu puisse consommer le flux après le renvoi de la réponse HTTP. ```typescript const result = agent.sendSignal(signal, { resourceId, threadId }) ctx.waitUntil( result.accepted.then(async accepted => { if (accepted.action === 'wake') { await accepted.output.consumeStream() } }), ) ``` ### `sendStateSignal(state, options)` Envoie à une exécution active ou à un thread de mémoire un contexte d’état nommé et limité au thread. Utilisez cette méthode lorsqu’un producteur externe possède un contexte durable qui évolue au fil du temps, tel que l’état du Browser, l’état d’Editor ou la sortie d’un observateur. ```typescript const result = await agent.sendStateSignal( { id: 'browser', mode: 'snapshot', cacheKey: 'browser:https://example.com:3-tabs', contents: 'Browser is open. Active tab URL: https://example.com. 3 open tabs.', value: { activeUrl: 'https://example.com', tabCount: 3, open: true, }, }, { resourceId: 'user-123', threadId: 'thread-abc', }, ) ``` **state** (`object`): Signal d’état à envoyer au thread. **state.id** (`string`): Nom du canal d’état, tel que browser ou editor. **state.cacheKey** (`string`): Clé appartenant au producteur que Mastra utilise pour ignorer les états en double d’un même canal et d’un même mode. **state.contents** (`string | Array`): Représentation de l’état présentée au LLM. **state.mode** (`'snapshot' | 'delta'`): Indique si l’état est un instantané de référence ou un événement de modification. Utilise par défaut snapshot. **state.value** (`unknown`): Valeur structurée de l’instantané pour mode: 'snapshot'. **state.delta** (`unknown`): Valeur structurée de la modification pour mode: 'delta'. **state.attributes** (`Record`): Attributs rendus dans le tag du signal d’état. **state.metadata** (`Record`): Métadonnées applicatives stockées avec le signal d’état. **state.tagName** (`string`): Nom du tag XML présenté au modèle. Utilise par défaut state. **options** (`object`): Comportement de ciblage et de distribution du signal d’état. Accepte les mêmes options que sendSignal(). Renvoie `{ accepted: Promise, signal: CreatedAgentSignal, persisted?: Promise, skipped?: false }` lorsque Mastra accepte un nouvel état. Renvoie `{ skipped: true, reason: 'unchanged' }` lorsque le même `cacheKey` et le même mode sont déjà actifs pour le canal d’état. `accepted` est résolue au moment de la décision, dès que Mastra détermine le traitement du signal : `{ action: 'wake', runId, output }` lorsque ce processus exécute l’Agent (il a démarré l’exécution ou obtenu le bail nécessaire), `{ action: 'deliver', runId }` lorsque le signal est transmis à une exécution existante (y compris lorsque ce processus perd une course de réveil interprocessus), ou `{ action: 'persist' }` / `{ action: 'discard' }` lorsqu’aucune exécution n’a eu lieu. `runId` est l’ID de référence de l’exécution qui a traité le signal ; il n’est présent que pour `wake` et `deliver`. Pour `persist`/`discard`, utilisez `result.signal.id` afin de corréler le signal stocké. Pour l’action `wake`, `output` correspond au flux de l’Agent destiné à être consommé dans le processus. ### `sendNotificationSignal(notification, options)` Crée ou regroupe un enregistrement dans la boîte de réception des notifications et résout la politique de distribution des notifications. Envoie un signal de notification lorsque la décision est immédiate. ```typescript const result = await agent.sendNotificationSignal( { source: 'github', kind: 'ci-status', priority: 'high', summary: 'CI failed on main: 3 tests failed.', dedupeKey: 'github:acme/app:main:ci', }, { resourceId: 'user-123', threadId: 'thread-abc', }, ) ``` **notification** (`object`): Enregistrement de la boîte de réception des notifications à créer ou à regrouper. **notification.source** (`string`): Système externe ayant produit la notification, tel que github, slack ou email. **notification.kind** (`string`): Type de notification au sein de la source, tel que ci-status, mention ou direct-message. **notification.summary** (`string`): Résumé présenté au LLM et utilisé comme contenu du signal de notification. **notification.priority** (`'low' | 'medium' | 'high' | 'urgent'`): Priorité utilisée par la politique de distribution des notifications. Utilise par défaut medium. **notification.payload** (`unknown`): Charge utile structurée stockée dans l’enregistrement de la boîte de réception pour les Tools ou le code applicatif. **notification.dedupeKey** (`string`): Clé utilisée pour regrouper les notifications en attente en double provenant de la même source et du même thread. **notification.coalesceKey** (`string`): Clé utilisée pour combiner les notifications en attente associées provenant de la même source et du même thread. **notification.attributes** (`Record`): Attributs supplémentaires copiés dans le signal de notification émis. **notification.metadata** (`Record`): Métadonnées applicatives stockées dans l’enregistrement de la boîte de réception. **options** (`object`): Thread cible et comportement de réveil de la notification. **options.resourceId** (`string`): ID de ressource de la boîte de réception des notifications et du thread de mémoire cible. **options.threadId** (`string`): ID du thread de la boîte de réception des notifications et du thread de mémoire cible. **options.ifIdle** (`object`): Contrôle le comportement lorsque le thread cible est inactif. **options.ifIdle.streamOptions** (`AgentExecutionOptions`): Options du flux qui démarre lorsqu’une notification immédiate réveille un thread inactif. Renvoie `{ record: NotificationRecord, decision: NotificationDeliveryDecision, runId?: string, signal?: CreatedAgentSignal, persisted?: Promise, accepted?: Promise }`. `record` correspond à l’enregistrement stocké dans la boîte de réception. `decision` est le résultat de la politique de distribution. `signal` et `runId` sont présents lorsque l’entrée émet immédiatement un signal, notamment le résumé immédiat émis pour les notifications actives de priorité élevée. `persisted` est présent lorsque le signal émis est persisté sans réveiller de thread inactif. `accepted` est présent lorsqu’un signal est émis et est résolu au moment de la décision, dès que Mastra détermine son traitement : `{ action: 'wake', runId, output }` lorsque ce processus exécute l’Agent (il a démarré l’exécution ou obtenu le bail nécessaire), `{ action: 'deliver', runId }` lorsque le signal est transmis à une exécution existante, ou `{ action: 'persist' }` / `{ action: 'discard' }` lorsqu’aucune exécution n’a eu lieu. Dans le résultat accepté, `runId` n’est présent que pour `wake` et `deliver`. Pour l’action `wake`, `output` correspond au flux de l’Agent destiné à être consommé dans le processus. La distribution par défaut tient compte de la priorité. Les notifications `urgent` sont distribuées immédiatement. Les notifications `high` le sont immédiatement lorsque le thread est inactif. Lorsque le thread est actif, Mastra émet immédiatement un résumé et conserve `deliverAt` pour une distribution complète ultérieure, lorsque le thread sera inactif. Les notifications `medium` sont distribuées immédiatement lorsque le thread est inactif et regroupées en résumés lorsqu’il est actif. Les notifications `low` sont regroupées en résumés dans les threads actifs comme inactifs. Les résumés de faible priorité destinés aux threads inactifs parviennent aux abonnés sans réveiller la boucle du modèle. Pour découvrir le flux complet, consultez la section [Signaux](https://mastra.zisheng.pro/fr/docs/long-running-agents/signals). Configurez `notifications.deliveryPolicy` sur l’Agent lorsque certaines notifications doivent attendre une autre fenêtre de distribution ou un regroupement de résumés : ```typescript export const supportAgent = new Agent({ id: 'support-agent', name: 'Support Agent', instructions: 'Help the user triage updates.', model: 'openai/gpt-5.6-sol', notifications: { deliveryPolicy: { priorities: { urgent: 'deliver', }, decide: ({ record }) => { if (record.priority === 'low') { return { action: 'summarize', summaryAt: new Date(Date.now() + 30 * 60 * 1000), } } }, }, }, }) ``` ### `subscribeToThread(options)` S’abonne aux chunks bruts du flux d’un thread de mémoire. Utilisez cette méthode avant d’appeler `sendMessage()`, `queueMessage()` ou `sendSignal()`. Elle vous permet d’effectuer le rendu de la sortie du flux et d’observer les échos des signaux, notamment lorsqu’un signal abandonne l’exécution active. **options** (`object`): Cible de l’abonnement au thread. **options.resourceId** (`string`): ID de ressource du thread de mémoire. **options.threadId** (`string`): ID du thread auquel s’abonner. Renvoie un objet `AgentThreadSubscription` comprenant les membres suivants : **stream** (`AsyncIterable`): Chunks bruts du flux de l’Agent pour le thread auquel le client est abonné. **activeRunId** (`() => string | null`): Renvoie l’ID de l’exécution active du thread, ou null lorsqu’aucune exécution n’est active. **abort** (`() => boolean`): Abandonne l’exécution active du thread. Renvoie true lorsqu’une exécution a été abandonnée. **unsubscribe** (`() => void`): Arrête l’abonnement sans abandonner l’exécution active. ## Paramètres du constructeur **id** (`string`): Identifiant unique de l’Agent. **name** (`string`): Nom d’affichage de l’Agent. **description** (`string`): Description facultative de l’objectif et des fonctionnalités de l’Agent. **metadata** (`Record | ({ requestContext: RequestContext }) => Record | Promise>`): Métadonnées facultatives permettant de classer ou de filtrer l’Agent dans les clients. Il peut s’agir d’un objet statique ou d’une fonction qui résout les métadonnées depuis le contexte de requête. **instructions** (`SystemMessage | ({ requestContext: RequestContext }) => SystemMessage | Promise`): Instructions qui guident le comportement de l’Agent. Elles peuvent prendre la forme d’une chaîne, d’un tableau de chaînes, d’un objet de message système, d’un tableau de messages système ou d’une fonction qui renvoie dynamiquement l’un de ces types. Types SystemMessage : string | string\[] | CoreSystemMessage | CoreSystemMessage\[] | SystemModelMessage | SystemModelMessage\[] **model** (`MastraLanguageModel | ({ requestContext: RequestContext }) => MastraLanguageModel | Promise`): Modèle de langage utilisé par l’Agent. Transmettez une chaîne de routeur de modèle au format provider/model, une configuration de modèle ou une instance de Provider, ou une fonction qui résout le modèle à l’exécution. Consultez la section Chaînes de modèle pour découvrir les Providers et variables d’environnement courants. **agents** (`Record | ({ requestContext: RequestContext }) => Record | Promise>`): Sous-Agents auxquels l’Agent peut accéder. Ils peuvent être fournis de manière statique ou résolus dynamiquement. **tools** (`ToolsInput | ({ requestContext: RequestContext, mastra?: Mastra }) => ToolsInput | Promise`): Tools auxquels l’Agent peut accéder. Ils peuvent être fournis de manière statique ou résolus dynamiquement à partir du contexte de requête et de l’instance Mastra associée, lorsqu’elle est disponible. **hooks** (`ToolHooks`): Hooks exécutés avant et après chaque appel de Tool effectué par cet Agent. Les hooks propres à l’exécution transmis à generate() ou stream() remplacent les hooks correspondants définis ici. Consultez la section Hooks des Tools ci-dessous. **hooks.beforeToolCall** (`(context: ToolHookContext) => void | ToolBeforeHookResult | Promise`): S’exécute avant un Tool. Reçoit { toolName, input, context, metadata }. Renvoyez { proceed: false, output } pour ignorer l’appel du Tool et utiliser output comme résultat. **hooks.afterToolCall** (`(context: ToolAfterHookContext) => void | Promise`): S’exécute après un Tool. Reçoit { toolName, input, context, metadata, output, error }. Lorsque le Tool lève une erreur, output vaut undefined et error est défini à la place. **transform** (`ToolPayloadTransformPolicy`): Politique partagée de transformation des charges utiles des Tools avant leur réception par les flux d’affichage ou les messages de transcription visibles par l’utilisateur. Utilisez le transform propre à chaque Tool dans createTool() pour définir des règles locales au Tool. **workflows** (`Record | ({ requestContext: RequestContext }) => Record | Promise>`): Workflows que l’Agent peut exécuter. Ils peuvent être statiques ou résolus dynamiquement. **defaultOptions** (`AgentExecutionOptions | ({ requestContext: RequestContext }) => AgentExecutionOptions | Promise`): Options par défaut utilisées lors de l’appel à stream() et generate(). **defaultGenerateOptionsLegacy** (`AgentGenerateOptions | ({ requestContext: RequestContext }) => AgentGenerateOptions | Promise`): Options par défaut utilisées lors de l’appel à generateLegacy(). **defaultStreamOptionsLegacy** (`AgentStreamOptions | ({ requestContext: RequestContext }) => AgentStreamOptions | Promise`): Options par défaut utilisées lors de l’appel à streamLegacy(). **mastra** (`Mastra`): Référence à l’instance d’exécution Mastra (injectée automatiquement). **scorers** (`MastraScorers | ({ requestContext: RequestContext }) => MastraScorers | Promise`): Configuration du Scoring pour l’évaluation et la télémétrie à l’exécution. Elle peut être statique ou fournie dynamiquement. **memory** (`MastraMemory | ({ requestContext: RequestContext }) => MastraMemory | Promise`): Module de mémoire utilisé pour stocker et récupérer le contexte avec état. **notifications** (`object`): Configuration de la distribution des notifications pour les signaux de notification durables. **notifications.deliveryPolicy** (`NotificationDeliveryPolicyConfig`): Contrôle la distribution des enregistrements de notification. Configurez une décision par défaut, des décisions propres à chaque priorité ou à chaque source, ou une fonction decide() personnalisée. **voice** (`CompositeVoice`): Paramètres Voice pour les entrées et sorties vocales. **inputProcessors** (`(Processor | ProcessorWorkflow)[] | ({ requestContext: RequestContext }) => (Processor | ProcessorWorkflow)[] | Promise<(Processor | ProcessorWorkflow)[]>`): Processeurs d’entrée qui peuvent modifier ou valider les messages avant leur traitement par l’Agent. Il peut s’agir d’objets Processor individuels ou de Workflows créés avec createWorkflow() au moyen de ProcessorStepSchema. **outputProcessors** (`(Processor | ProcessorWorkflow)[] | ({ requestContext: RequestContext }) => (Processor | ProcessorWorkflow)[] | Promise<(Processor | ProcessorWorkflow)[]>`): Processeurs de sortie qui peuvent modifier ou valider les messages de l’Agent avant leur envoi au client. Il peut s’agir d’objets Processor individuels ou de Workflows. **maxProcessorRetries** (`number`): Nombre maximal de fois où un processeur peut demander de réessayer l’étape du LLM. **requestContextSchema** (`StandardJSONSchemaV1`): Schéma JSON standard servant à valider les valeurs du contexte de requête. Lorsqu’il est fourni, le contexte est validé au début de generate() ou stream(), et une MastraError est levée si la validation échoue. **editor** (`false | { instructions?: boolean; tools?: boolean | { description?: boolean } }`): Contrôle les champs que l’Editor peut remplacer pour cet Agent défini dans le code. Omettez cette option pour autoriser la modification des instructions et des Tools. Consultez la section Remplacements d’Editor ci-dessous. ## Options de mémoire de `generate()` Transmettez `memory` lorsque vous appelez `agent.generate()` afin de choisir le thread de conversation que l’exécution doit lire et dans lequel elle doit écrire. La structure courante est `memory: { resource: string, thread: string }`, où `resource` identifie le propriétaire et `thread` la conversation. Consultez la section [Threads et ressources](https://mastra.zisheng.pro/fr/docs/memory/message-history) pour découvrir le modèle conceptuel. ```typescript const response = await agent.generate('What did we decide about retries?', { memory: { resource: 'user-123', thread: 'support-thread-456', }, }) ``` Utilisez un objet thread lorsque vous devez créer ou mettre à jour les métadonnées du thread pendant l’appel : ```typescript const response = await agent.generate('Continue the support conversation.', { memory: { resource: 'user-123', thread: { id: 'support-thread-456', title: 'Billing support', metadata: { category: 'billing' }, }, }, }) ``` ## Hooks des Tools Utilisez `hooks` pour exécuter une logique autour de chaque appel de Tool effectué par l’Agent, notamment les Tools attribués, les Tools de mémoire, les ensembles de Tools, les Tools clients et les Tools du Workspace. ```typescript import { Agent } from '@mastra/core/agent' export const agent = new Agent({ id: 'support-agent', name: 'support-agent', instructions: 'Help users with their questions.', model: 'openai/gpt-5.6-sol', hooks: { beforeToolCall: ({ toolName, input }) => { console.log(`Running ${toolName}`, input) }, afterToolCall: ({ toolName, output, error }) => { console.log(`Finished ${toolName}`, { output, error }) }, }, }) ``` `beforeToolCall` peut court-circuiter l’appel du Tool en renvoyant `{ proceed: false, output }`. L’Agent ignore l’exécution et utilise `output` comme résultat du Tool : ```typescript const result = await agent.generate('Clean up old records', { hooks: { beforeToolCall: ({ toolName }) => { if (toolName === 'deleteRecord') { return { proceed: false, output: { blocked: true } } } }, }, }) ``` Les `metadata` du contexte de hook comprennent `agentId` et `agentName`. Les hooks propres à l’exécution transmis à `generate()` ou `stream()` remplacent les hooks correspondants définis au niveau de l’Agent. Lorsqu’un [Workspace](https://mastra.zisheng.pro/fr/reference/workspace/workspace-class) définit également `tools.hooks`, les hooks du Workspace s’exécutent dans le wrapper de hooks de l’Agent. ## Remplacements d’Editor Lorsque vous enregistrez le [`MastraEditor`](https://mastra.zisheng.pro/fr/reference/editor/mastra-editor), le champ `editor` contrôle les parties d’un Agent défini dans le code qui peuvent être modifiées au moyen d’Editor. Les champs appartenant au code sont en lecture seule dans Studio et sont retirés des remplacements enregistrés. **editor** (`false | { instructions?: boolean; tools?: boolean | { description?: boolean } }`): Omettez cette option pour autoriser la modification des instructions et des Tools. Définissez-la sur false pour verrouiller l’Agent. Définissez instructions: true pour autoriser la modification des instructions. Définissez tools: true pour autoriser la modification de l’appartenance et de la description des Tools, ou tools: { description: true } pour n’autoriser que la modification des descriptions. Les valeurs `id`, `name` et `model` de l’Agent proviennent toujours du code et ne peuvent pas être remplacées au moyen d’Editor. Consultez [Editor](https://mastra.zisheng.pro/fr/docs/editor/overview) pour découvrir son utilisation. ## Valeur renvoyée **agent** (`Agent`): Nouvelle instance d’Agent avec la configuration indiquée.