Instructions

Les instructions d’un Agent contiennent son prompt système permanent : le modèle les lit à chaque tour. Utilisez-les pour définir l’identité, le ton, le rôle et les règles permanentes de l’Agent.

Rédigez-les dans l’un des deux fichiers placés à la racine de l’Agent. Utilisez instructions.md lorsque le prompt est un texte fixe. Utilisez instructions.ts lorsqu’il nécessite du code, par exemple s’il est construit à partir de constantes partagées ou déterminé pour chaque requête.

Les instructions sont toujours présentes dans le contexte. Réservez-les donc aux comportements stables qui s’appliquent à toutes les requêtes. Placez tout contenu conditionnel, volumineux ou orienté vers une action dans tools/ ou skills/, que le modèle utilise uniquement lorsque c’est pertinent.

Démarrage rapide

Ajoutez un fichier instructions.md à la racine de l’Agent. Tout ce que vous y écrivez devient le prompt ; la version la plus courte tient donc en une seule phrase.

src/mastra/agents/weather/instructions.md

You are a helpful weather assistant. Answer questions about current conditions and forecasts.

Contenu des instructions

Des instructions efficaces couvrent les aspects du comportement d’un Agent qui ne changent pas d’une requête à l’autre :

• Rôle et identité
• Ton et style
• Règles permanentes
• Format de sortie

Placez les consignes conditionnelles, volumineuses ou orientées vers une action dans tools/ ou skills/, que le modèle utilise uniquement lorsque c’est pertinent.

Instructions en TypeScript

Utilisez instructions.ts lorsque Markdown ne permet pas d’exprimer le prompt. Le fichier exporte par défaut une chaîne, un message système ou une fonction qui renvoie l’un des deux ; agentInstructions() type l’export sans le modifier.

Exportez une chaîne lorsque le prompt est assemblé dans le code, par exemple à partir de constantes partagées avec le reste de votre application :

src/mastra/agents/weather/instructions.ts

import { agentInstructions } from '@mastra/core/agent'
import { SUPPORTED_UNITS } from '../../constants'

export default agentInstructions(`
You are a helpful weather assistant.
Report conditions using one of these units: ${SUPPORTED_UNITS.join(', ')}.
`)

Exportez une fonction lorsque le prompt dépend de la requête. Mastra l’appelle à chaque tour et lui transmet le contexte de requête :

src/mastra/agents/support/instructions.ts

import { agentInstructions } from '@mastra/core/agent'

export default agentInstructions(({ requestContext }) => {
  const tier = requestContext.get('tier') ?? 'standard'
  return `You are a support agent. Treat this as a ${tier}-tier customer.`
})

La fonction peut être async et reçoit mastra en plus de requestContext. Elle peut ainsi lire des données depuis le stockage ou un autre composant primitif enregistré avant de renvoyer le prompt.

Les deux fichiers peuvent également se trouver dans le répertoire d’un sous-Agent, qui suit les mêmes règles.

Comportement à la compilation

instructions.md et instructions.ts sont intégrés différemment à l’Agent déployé :

• instructions.md : Mastra lit le fichier et insère son contenu dans le code généré au moment de la compilation.
• instructions.ts : le code généré importe le module. Celui-ci est donc regroupé comme n’importe quel autre fichier TypeScript et peut effectuer des imports depuis le reste de votre projet.

Avec mastra dev, la modification de l’un ou l’autre fichier déclenche une nouvelle compilation. Dans une application déployée, aucun des deux fichiers n’est lu sur le disque lors de l’exécution ; les modifications prennent donc effet après la compilation suivante.

Priorité par rapport à config

Les instructions peuvent provenir de instructions.ts, de instructions.md ou du champ instructions de config.ts :

• Une valeur instructions définie à l’exécution (une fonction) dans config.ts est prioritaire sur les deux fichiers.
• Sinon, instructions.ts est prioritaire sur instructions.md.
• instructions.md est prioritaire sur une chaîne instructions statique dans config.ts.
• Si aucune de ces sources n’est présente, la compilation échoue et indique le répertoire de l’Agent.

Si vous définissez des instructions à plusieurs endroits, un avertissement indique les deux sources et celle qui est prioritaire. Conservez une seule source par Agent.