config.ts

Le fichier config.ts d’un Agent définit son modèle et ses options d’exécution. Utilisez-le pour les options propres à l’Agent, tandis que les fichiers voisins fournissent les instructions, les Tools, les Skills, etc.

Contenu de config.ts

config.ts est le point d’entrée requis pour le modèle et les options d’exécution d’un Agent basé sur des fichiers. Placez-y les paramètres définis au niveau de l’Agent lorsqu’ils ne nécessitent pas leur propre fichier, notamment le modèle, la description, les options d’exécution par défaut, le comportement de nouvelle tentative, les Scorers et l’identité d’affichage.

Conservez les configurations associées dans des fichiers voisins lorsque vous souhaitez que le routage basé sur les fichiers les fusionne dans l’Agent. Par exemple, utilisez instructions.md pour le prompt toujours actif et tools/ pour les actions que le modèle peut appeler.

Démarrage rapide

Le fichier config.ts suivant, accompagné d’un fichier instructions.md, crée un Agent basé sur des fichiers fonctionnel :

src/mastra/agents/weather/config.ts

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

export default agentConfig({
  model: 'openai/gpt-5.6-sol',
})

src/mastra/agents/weather/instructions.md

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

Mastra utilise le nom de répertoire weather comme id et name par défaut de l’Agent. Le fichier voisin instructions.md fournit les instructions requises.

Définir le modèle

Le champ model est le seul champ requis dans agentConfig(). La compilation échoue lorsqu’un répertoire d’Agent ne fournit aucun modèle. Les autres fonctionnalités proviennent de fichiers voisins ou disposent de valeurs par défaut.

src/mastra/agents/weather/config.ts

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

export default agentConfig({
  model: 'openai/gpt-5.6-sol',
})

Identité issue du répertoire

Par défaut, l’id et le name d’un Agent basé sur des fichiers correspondent au nom du répertoire. Pour src/mastra/agents/weather/, Mastra enregistre l’Agent sous le nom weather, sauf si vous remplacez ces champs.

Remplacez id ou name lorsque la clé de routage stable et le nom d’affichage doivent être différents.

src/mastra/agents/weather/config.ts

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

export default agentConfig({
  id: 'weather-assistant',
  name: 'Weather Assistant',
  model: 'openai/gpt-5.6-sol',
})

Définir les options d’exécution

agentConfig() accepte les options du constructeur d’Agent, à ceci près que id, name et les champs des fichiers voisins peuvent être fournis par la convention basée sur les fichiers. Consultez la référence d’Agent pour obtenir la liste complète des options.

À retenir :

• Les sous-agents basés sur des fichiers exigent une description non vide, car le modèle parent l’utilise pour le routage de la délégation.
• defaultOptions, maxRetries, scorers et les autres options d’Agent peuvent figurer dans config.ts lorsqu’elles ne nécessitent pas leur propre fichier.

Emplacement des configurations associées

Limitez config.ts aux options d’exécution. Utilisez des fichiers voisins pour les configurations qui gagnent à disposer de leur propre emplacement.

Paramètre	Fichier ou dossier	Pourquoi cet emplacement
Instructions	instructions.md ou instructions.ts	Conserve le prompt toujours actif dans un Markdown lisible ou permet de le calculer en TypeScript
Tools	tools/	Attribue à chaque action appelable son propre module typé
Skills	skills/	Sépare les procédures chargées à la demande des instructions toujours actives
Memory	memory.ts	Configure la mémoire persistante sans surcharger les options d’exécution
Workspace	workspace.ts	Configure les fichiers et le comportement du Sandbox séparément des paramètres du modèle
Processors	processors/	Sépare les pipelines de traitement des entrées et des sorties
Sous-agents	subagents/	Attribue son propre répertoire à chaque Agent enfant spécialisé

Ordre de priorité

config.ts est fusionné avec les autres fichiers de l’Agent selon les règles suivantes :

Domaine	Source A	Source B	Prioritaire
Instructions	config.instructions dynamique	instructions.ts ou instructions.md	config.instructions dynamique
Instructions	config.instructions statique	instructions.ts ou instructions.md	Le fichier d’instructions
Instructions	instructions.ts	instructions.md	instructions.ts
Tools	config.tools	tools/	Les deux sont fusionnés ; config.tools est prioritaire en cas de collision de clés
Tools	Fonction config.tools	tools/	Fonction config.tools ; les Tools découverts sont ignorés
Skills	config.skills	skills/	Les deux sont fusionnés ; config.skills est prioritaire en cas de collision de noms
Skills	Fonction config.skills	skills/	Fonction config.skills ; les Skills découverts sont ignorés
Memory	config.memory	memory.ts	config.memory
Workspace	config.workspace	workspace.ts	config.workspace

L’absence simultanée de instructions.md, instructions.ts et config.instructions fait échouer la compilation. Si config.memory et memory.ts sont tous deux absents, l’Agent ne dispose d’aucune mémoire.

Cycle de vie de la découverte

Les primitives basées sur des fichiers sont découvertes par le bundler Mastra lors de mastra dev et mastra build. Pendant la découverte, Mastra lit les fichiers pris en charge dans src/mastra/, importe les modules TypeScript et JavaScript, lit les instructions Markdown et les Skills, copie les fichiers d’initialisation du Workspace, puis enregistre les primitives assemblées dans votre application Mastra.

Après la découverte, un Agent basé sur des fichiers s’exécute comme un Agent standard. Son appel depuis l’API Agent, Studio, les Workflows ou le code de votre application utilise le même runtime qu’un Agent défini dans le code.

La découverte s’appuie sur les sources et adopte une approche prudente.

Elle ignore les liens symboliques, les fichiers de test et les répertoires qui ne sont pas des répertoires d’Agent. Les Workflows et les fichiers de projet singleton ne sont routés par fichier que s’ils possèdent un export par défaut.

Démarrez votre application avec la CLI Mastra afin d’exécuter la découverte :

npm

npx mastra dev

pnpm

pnpm dlx mastra dev

Yarn

yarn dlx mastra dev

Bun

bun x mastra dev

Si vous importez directement votre instance mastra, les répertoires agents/<name>/ et les autres conventions ne sont pas découverts. Lorsque vous utilisez Mastra comme bibliothèque, enregistrez plutôt ces primitives dans le code.