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.

src/mastra/agents/string-agent.ts

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.

src/mastra/agents/core-message-agent.ts

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

src/mastra/agents/multi-message-agent.ts

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 pour découvrir les ID de modèle pris en charge et les variables d’environnement 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.

src/mastra/signals.ts

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 :

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 :

<user name="Devin" from="slack">Can we simplify the API surface?</user>

Utilisez ifActive.attributes et ifIdle.attributes lorsque le message doit transporter un contexte différent selon que le thread est actif ou non :

src/mastra/signals.ts

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 :

<user source="chat" delivery="while-active">Also cover the edge cases.</user>

Lorsque le thread est inactif, le modèle voit :

<user source="chat" delivery="new-message">Also cover the edge cases.</user>

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<TextPart | FilePart> | { contents: string | Array<TextPart | FilePart>; attributes?: Record<string, JSONValue>; metadata?: Record<string, unknown>; 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 <user> incluant les attributs.

options?:

object

Comportement de ciblage et de distribution du message.

object

runId?:

string

ID d’exécution à cibler directement. Utilisez cette option si vous connaissez déjà l’ID de l’exécution active.

resourceId?:

string

ID de ressource du thread de mémoire. Obligatoire avec threadId pour les messages ciblant un thread.

threadId?:

string

ID du thread à cibler. Obligatoire avec resourceId pour les messages ciblant un thread.

ifActive?:

object

Contrôle le comportement lorsque le thread cible est actif.

object

behavior?:

'deliver' | 'persist' | 'discard'

Contrôle le comportement lorsque le thread cible est actif. Utilise par défaut deliver.

attributes?:

Record<string, string | number | boolean>

Attributs fusionnés dans le message lorsque Mastra l’accepte pendant que le thread cible est actif.

ifIdle?:

object

Contrôle le comportement lorsque le thread cible est inactif.

object

behavior?:

'wake' | 'persist' | 'discard'

Contrôle le comportement lorsque le thread cible est inactif. Utilise par défaut wake.

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.

attributes?:

Record<string, string | number | boolean>

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 :

src/mastra/signals.ts

agent.sendMessage('Continue with the next step.', {
  resourceId: 'user-123',
  threadId: 'thread-abc',
  ifIdle: {
    behavior: 'wake',
    streamOptions: {
      maxSteps: 3,
    },
  },
})

Renvoie { accepted: Promise<SendAgentSignalAccepted>, signal: CreatedAgentSignal, persisted?: Promise<void> }. 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.

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<SendAgentSignalAccepted>, signal: CreatedAgentSignal, persisted?: Promise<void> }, 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<TextPart | FilePart>; attributes?: Record<string, JSONValue>; metadata?: Record<string, unknown>; 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 <github-review>...</github-review>. 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.

object

runId?:

string

ID d’exécution à cibler directement. Utilisez cette option si vous connaissez déjà l’ID de l’exécution active.

resourceId?:

string

ID de ressource du thread de mémoire. Obligatoire avec threadId pour les signaux ciblant un thread.

threadId?:

string

ID du thread à cibler. Obligatoire avec resourceId pour les signaux ciblant un thread.

ifActive?:

object

Contrôle le comportement lorsque le thread cible est actif.

object

behavior?:

'deliver' | 'persist' | 'discard'

Contrôle le comportement lorsque le thread cible est actif. Utilise par défaut deliver.

attributes?:

Record<string, string | number | boolean>

Attributs fusionnés dans le signal lorsque Mastra l’accepte pendant que le thread cible est actif.

ifIdle?:

object

Contrôle le comportement lorsque le thread cible est inactif.

object

behavior?:

'wake' | 'persist' | 'discard'

Contrôle le comportement lorsque le thread cible est inactif. Utilise par défaut wake.

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.

attributes?:

Record<string, string | number | boolean>

Attributs fusionnés dans le signal lorsque Mastra l’accepte pendant que le thread cible est inactif.

Renvoie { accepted: Promise<SendAgentSignalAccepted>, signal: CreatedAgentSignal, persisted?: Promise<void> }. 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.

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.

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.

object

id:

string

Nom du canal d’état, tel que browser ou editor.

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.

contents:

string | Array<TextPart | FilePart>

Représentation de l’état présentée au LLM.

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.

value?:

unknown

Valeur structurée de l’instantané pour mode: 'snapshot'.

delta?:

unknown

Valeur structurée de la modification pour mode: 'delta'.

attributes?:

Record<string, string | number | boolean>

Attributs rendus dans le tag du signal d’état.

metadata?:

Record<string, unknown>

Métadonnées applicatives stockées avec le signal d’état.

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<SendAgentSignalAccepted>, signal: CreatedAgentSignal, persisted?: Promise<void>, 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.

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.

object

source:

string

Système externe ayant produit la notification, tel que github, slack ou email.

kind:

string

Type de notification au sein de la source, tel que ci-status, mention ou direct-message.

summary:

string

Résumé présenté au LLM et utilisé comme contenu du signal de notification.

priority?:

'low' | 'medium' | 'high' | 'urgent'

Priorité utilisée par la politique de distribution des notifications. Utilise par défaut medium.

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.

dedupeKey?:

string

Clé utilisée pour regrouper les notifications en attente en double provenant de la même source et du même thread.

coalesceKey?:

string

Clé utilisée pour combiner les notifications en attente associées provenant de la même source et du même thread.

attributes?:

Record<string, JSONValue>

Attributs supplémentaires copiés dans le signal de notification émis.

metadata?:

Record<string, unknown>

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.

object

resourceId:

string

ID de ressource de la boîte de réception des notifications et du thread de mémoire cible.

threadId:

string

ID du thread de la boîte de réception des notifications et du thread de mémoire cible.

ifIdle?:

object

Contrôle le comportement lorsque le thread cible est inactif.

object

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<void>, accepted?: Promise<SendAgentSignalAccepted> }. 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.

Configurez notifications.deliveryPolicy sur l’Agent lorsque certaines notifications doivent attendre une autre fenêtre de distribution ou un regroupement de résumés :

src/mastra/agents/support-agent.ts

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.

object

resourceId?:

string

ID de ressource du thread de mémoire.

threadId:

string

ID du thread auquel s’abonner.

Renvoie un objet AgentThreadSubscription comprenant les membres suivants :

stream:

AsyncIterable<AgentChunkType>

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<string, unknown> | ({ requestContext: RequestContext }) => Record<string, unknown> | Promise<Record<string, unknown>>

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<SystemMessage>

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<MastraLanguageModel>

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<string, Agent> | ({ requestContext: RequestContext }) => Record<string, Agent> | Promise<Record<string, Agent>>

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<ToolsInput>

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.

ToolHooks

beforeToolCall?:

(context: ToolHookContext) => void | ToolBeforeHookResult | Promise<void | ToolBeforeHookResult>

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.

afterToolCall?:

(context: ToolAfterHookContext) => void | Promise<void>

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<string, Workflow> | ({ requestContext: RequestContext }) => Record<string, Workflow> | Promise<Record<string, Workflow>>

Workflows que l’Agent peut exécuter. Ils peuvent être statiques ou résolus dynamiquement.

defaultOptions?:

AgentExecutionOptions | ({ requestContext: RequestContext }) => AgentExecutionOptions | Promise<AgentExecutionOptions>

Options par défaut utilisées lors de l’appel à stream() et generate().

defaultGenerateOptionsLegacy?:

AgentGenerateOptions | ({ requestContext: RequestContext }) => AgentGenerateOptions | Promise<AgentGenerateOptions>

Options par défaut utilisées lors de l’appel à generateLegacy().

defaultStreamOptionsLegacy?:

AgentStreamOptions | ({ requestContext: RequestContext }) => AgentStreamOptions | Promise<AgentStreamOptions>

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<MastraScorers>

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<MastraMemory>

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.

object

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 pour découvrir le modèle conceptuel.

src/mastra/run.ts

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 :

src/mastra/run.ts

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.

src/mastra/agents/hooked-agent.ts

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 :

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 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, 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 pour découvrir son utilisation.

Valeur renvoyée

agent:

Agent<TAgentId, TTools>

Nouvelle instance d’Agent avec la configuration indiquée.