Classe MastraEditor

La classe MastraEditor configure le système d’édition. Transmettez-la au constructeur Mastra pour activer les fonctionnalités de l’éditeur, telles que les blocs de prompt, la surcharge du code des agents, le versionnage et les fournisseurs d’outils.

Consultez Editor pour une présentation des fonctions de l’éditeur.

Exemple d’utilisation

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraEditor } from '@mastra/editor'

export const mastra = new Mastra({
  agents: {/* your agents */},
  editor: new MastraEditor(),
})

Paramètres du constructeur

logger?:

Logger

Instance de logger. Utilise le logger de l’instance Mastra par défaut si elle n’est pas définie.

toolProviders?:

Record<string, ToolProvider>

= {}

Fournisseurs d’outils d’intégration indexés par ID (par exemple, Composio ou Arcade). Permet aux agents d’utiliser des outils tiers ajoutés par l’éditeur.

processorProviders?:

Record<string, ProcessorProvider>

= {}

Fournisseurs de processeurs pour le traitement configurable des entrées et sorties (par exemple, modération ou limitation des tokens). Les fournisseurs intégrés sont toujours inclus.

filesystems?:

Record<string, FilesystemProvider>

= {}

Fournisseurs de systèmes de fichiers pour accéder aux fichiers (par exemple, S3 ou GCS). Un fournisseur de système de fichiers local est toujours inclus.

sandboxes?:

Record<string, SandboxProvider>

= {}

Fournisseurs de sandbox pour l’exécution de code (par exemple, E2B). Un fournisseur de sandbox local est toujours inclus.

blobStores?:

Record<string, BlobStoreProvider>

= {}

Fournisseurs de stockage blob pour les données binaires (par exemple, S3). Utilise le magasin blob du stockage Mastra par défaut si aucun fournisseur n’est indiqué.

browsers?:

Record<string, BrowserProvider>

= {}

Fournisseurs permettant aux agents d’accéder à un navigateur (par exemple, Stagehand). Aucun n’est intégré ; un fournisseur est requis lorsque builder.features.agent.browser est activé. Consultez la référence BrowserProvider pour l’interface du fournisseur.

builder?:

AgentBuilderOptions

Configuration d’Agent Builder. Consultez la référence AgentBuilderOptions. Omettez cette option ou définissez enabled: false pour désactiver Builder.

source?:

'code' | 'db'

= 'db'

Emplacement de stockage des surcharges d’agents. Avec 'db', les surcharges se trouvent dans le backend de stockage configuré et Studio affiche le flux d’enregistrement et de publication. Avec 'code', les surcharges sont des fichiers JSON par agent sur le disque (acheminés par un FilesystemStore local) et Studio affiche des actions sur le système de fichiers. Consultez les options de stockage d’Editor pour connaître la différence.

codePath?:

string

= './mastra/editor/'

Répertoire utilisé par la source 'code' pour les fichiers JSON par agent. Ignoré lorsque source n’est pas 'code'.

Interfaces de fournisseur

Chaque champ de fournisseur ci-dessus accepte un enregistrement indexé par l’ID du fournisseur. Consultez les pages de référence de chaque fournisseur pour connaître la structure de l’implémentation :

• ProcessorProvider
• FilesystemProvider
• SandboxProvider
• BlobStoreProvider
• BrowserProvider

Agent Builder

Le champ builder active Agent Builder, une interface utilisateur web permettant de créer et modifier des agents stockés. Consultez :

• Présentation d’Agent Builder : concepts et prise en main.
• AgentBuilderOptions : schéma complet des options.
• BuilderAgentDefaults : valeurs par défaut épinglées par l’administrateur pour les nouveaux agents.
• builder.configuration.agent.models : liste autorisée de modèles et modèle par défaut.

Enregistrer l’agent Builder

L’interface de Builder s’exécute avec un agent créé par la fabrique createBuilderAgent() de @mastra/editor/ee. Importez la fabrique, appelez-la, puis enregistrez l’agent renvoyé dans agents sur votre instance Mastra :

import { Mastra } from '@mastra/core'
import { MastraEditor } from '@mastra/editor'
import { createBuilderAgent } from '@mastra/editor/ee'

export const mastra = new Mastra({
  agents: { builderAgent: createBuilderAgent() },
  editor: new MastraEditor({
    builder: { enabled: true },
  }),
})

Le nom de clé (builderAgent) est une convention. Toute clé convient. Le sous-chemin @mastra/editor/ee est contrôlé à l’exécution par la licence Mastra Enterprise Edition.

Consultez la présentation d’Agent Builder pour la liste complète des étapes de configuration.

Espaces de noms

L’éditeur expose des espaces de noms permettant de gérer différents types d’entités. Accédez-y depuis toute instance Mastra avec mastra.getEditor() et appelez directement les méthodes CRUD dans le code de l’application, ou utilisez les routes du serveur Mastra qui s’en servent en interne.

Tous les espaces de noms étendent une classe de base CRUD commune ; ils exposent donc les mêmes méthodes create, getById, update, delete, list, listResolved et clearCache. Les tableaux de propriétés propres à chaque espace de noms ci-dessous documentent également les méthodes supplémentaires.

agent:

EditorAgentNamespace

Opérations CRUD et gestion des versions des agents stockés. Gère l’application des surcharges stockées aux agents définis dans le code.

EditorAgentNamespace

create:

(input: StorageCreateAgentInput) => Promise<Agent>

Crée un agent stocké et renvoie une instance hydratée d’Agent. Accepte un id, authorId, des métadonnées et l’instantané initial (nom, description, instructions, modèle, outils, mémoire, etc.).

getById:

(id: string, options?: GetByIdOptions) => Promise<Agent | null>

Renvoie une instance hydratée d’Agent pour un agent stocké. Transmettez des options avec versionId, versionNumber ou status ("draft" | "published" | "archived") pour cibler une version précise. Les requêtes utilisant la version par défaut sont mises en cache.

update:

(input: StorageUpdateAgentInput) => Promise<Agent>

Met à jour partiellement un agent stocké. Crée une version à partir des champs d’instantané fournis, l’affecte à activeVersionId et invalide le cache. Définissez memory sur null pour désactiver la mémoire.

delete:

(id: string) => Promise<void>

Supprime un agent stocké et le retire du registre d’exécution Mastra.

list:

(args?: StorageListAgentsInput) => Promise<StorageListAgentsOutput>

Liste les agents stockés avec des filtres facultatifs de pagination, orderBy, authorId et métadonnées. Renvoie les instantanés bruts stockés.

listResolved:

(args?: StorageListAgentsInput) => Promise<StorageListAgentsResolvedOutput>

Identique à list, mais renvoie des configurations entièrement résolues, dont les références ont été déréférencées.

applyStoredOverrides:

(agent: Agent, options?: { versionId?: string; status?: "draft" | "published" }) => Promise<Agent>

Modifie sur place un agent défini dans le code afin d’appliquer les surcharges stockées (instructions, outils, variables). Appelée en interne par mastra.getAgent() ; vous l’appelez rarement directement.

clone:

(agent: Agent, options: { newId: string; newName?: string; metadata?: Record<string, unknown>; authorId?: string; requestContext?: RequestContext; }) => Promise<Agent>

Crée un agent stocké en clonant un agent existant.

clearCache:

(agentId?: string) => void

Vide le cache en mémoire pour un agent ou pour tous les agents. Appelée automatiquement après les mutations.

prompt:

EditorPromptNamespace

Opérations CRUD sur les blocs de prompt. Inclut une méthode de prévisualisation qui résout les blocs d’instructions avec le contenu des brouillons.

EditorPromptNamespace

create:

(input: StorageCreatePromptBlockInput) => Promise<StorageResolvedPromptBlockType>

Crée un bloc de prompt stocké. Accepte un id, authorId, des métadonnées et l’instantané initial (nom, description, contenu, règles, requestContextSchema).

getById:

(id: string, options?: GetByIdOptions) => Promise<StorageResolvedPromptBlockType | null>

Renvoie un bloc de prompt résolu. Transmettez des options pour cibler une version ou un statut précis.

update:

(input: StorageUpdatePromptBlockInput) => Promise<StorageResolvedPromptBlockType>

Met à jour partiellement un bloc de prompt stocké. Crée une version de brouillon à partir des champs d’instantané fournis.

delete:

(id: string) => Promise<void>

Supprime un bloc de prompt stocké et le retire du registre d’exécution Mastra.

list:

(args?: StorageListPromptBlocksInput) => Promise<StorageListPromptBlocksOutput>

Liste les blocs de prompt stockés avec des filtres facultatifs de pagination, orderBy, authorId, métadonnées et statut.

listResolved:

(args?: StorageListPromptBlocksInput) => Promise<StorageListPromptBlocksResolvedOutput>

Identique à list, mais renvoie un contenu de bloc de prompt entièrement résolu.

preview:

(blocks: AgentInstructionBlock[], context: Record<string, unknown>) => Promise<string>

Résout un tableau de blocs d’instructions par rapport à un contexte, effectue le rendu des variables de gabarit et évalue les conditions d’affichage. Inclut le contenu de brouillon des blocs de prompt référencés.

clearCache:

(id?: string) => void

Vide le cache en mémoire pour un bloc de prompt ou tous les blocs de prompt.

mcp:

EditorMCPNamespace

Opérations CRUD sur les configurations de clients MCP stockées.

EditorMCPNamespace

create:

(input: StorageCreateMCPClientInput) => Promise<MCPClient>

Crée un client MCP stocké. Accepte un id, authorId, des métadonnées et l’instantané initial (serveurs, filtrage des outils).

getById:

(id: string, options?: GetByIdOptions) => Promise<MCPClient | null>

Renvoie une instance MCPClient hydratée pour un client MCP stocké.

update:

(input: StorageUpdateMCPClientInput) => Promise<MCPClient>

Met à jour partiellement un client MCP stocké et invalide le cache.

delete:

(id: string) => Promise<void>

Supprime un client MCP stocké et le retire du registre d’exécution Mastra.

list:

(args?: StorageListMCPClientsInput) => Promise<StorageListMCPClientsOutput>

Liste les clients MCP stockés avec pagination et filtres facultatifs.

listResolved:

(args?: StorageListMCPClientsInput) => Promise<StorageListMCPClientsResolvedOutput>

Identique à list, mais renvoie des configurations de clients MCP entièrement résolues.

clearCache:

(id?: string) => void

Vide le cache en mémoire pour un client MCP ou tous les clients MCP.

mcpServer:

EditorMCPServerNamespace

Opérations CRUD sur les configurations de serveurs MCP.

EditorMCPServerNamespace

create:

(input: StorageCreateMCPServerInput) => Promise<MCPServerBase>

Crée une configuration de serveur MCP stockée et renvoie une instance de serveur hydratée.

getById:

(id: string, options?: GetByIdOptions) => Promise<MCPServerBase | null>

Renvoie un serveur MCP hydraté pour un id donné.

update:

(input: StorageUpdateMCPServerInput) => Promise<MCPServerBase>

Met à jour partiellement une configuration de serveur MCP stockée.

delete:

(id: string) => Promise<void>

Supprime une configuration de serveur MCP stockée.

list:

(args?: StorageListMCPServersInput) => Promise<StorageListMCPServersOutput>

Liste les configurations de serveurs MCP stockées.

listResolved:

(args?: StorageListMCPServersInput) => Promise<StorageListMCPServersResolvedOutput>

Identique à list, mais renvoie des configurations de serveurs entièrement résolues.

clearCache:

(id?: string) => void

Vide le cache en mémoire pour un serveur MCP ou tous les serveurs MCP.

scorer:

EditorScorerNamespace

Opérations CRUD sur les configurations d’évaluateurs.

EditorScorerNamespace

create:

(input: StorageCreateScorerInput) => Promise<MastraScorer>

Crée un évaluateur stocké et renvoie une instance MastraScorer hydratée.

getById:

(id: string, options?: GetByIdOptions) => Promise<MastraScorer | null>

Renvoie un évaluateur hydraté pour un id donné.

update:

(input: StorageUpdateScorerInput) => Promise<MastraScorer>

Met à jour partiellement un évaluateur stocké.

delete:

(id: string) => Promise<void>

Supprime un évaluateur stocké et le retire du registre d’exécution Mastra.

list:

(args?: StorageListScorersInput) => Promise<StorageListScorersOutput>

Liste les évaluateurs stockés avec pagination et filtres facultatifs.

listResolved:

(args?: StorageListScorersInput) => Promise<StorageListScorersResolvedOutput>

Identique à list, mais renvoie des configurations d’évaluateurs entièrement résolues.

clearCache:

(id?: string) => void

Vide le cache en mémoire pour un évaluateur ou tous les évaluateurs.

Exemples d’espace de noms d’agent

Créez un remplacement stocké pour un agent existant défini dans le code :

src/scripts/seed-agent.ts

import { mastra } from '../mastra'

const editor = mastra.getEditor()!

await editor.agent.create({
  id: 'support-agent',
  instructions: 'You are a friendly support agent for Acme.',
  tools: {
    search_kb: { description: 'Search the Acme knowledge base' },
  },
})

Méthodes

Accès aux fournisseurs

getToolProvider(id)

Renvoie un fournisseur d’outils enregistré à partir de son ID.

const composio = mastra.getEditor()?.getToolProvider('composio')

getToolProviders()

Renvoie tous les fournisseurs d’outils enregistrés sous la forme d’un Record<string, ToolProvider>.

getProcessorProvider(id)

Renvoie un fournisseur de processeurs enregistré à partir de son ID.

getProcessorProviders()

Renvoie tous les fournisseurs de processeurs enregistrés.

getFilesystemProviders()

Renvoie tous les fournisseurs de systèmes de fichiers enregistrés.

getSandboxProviders()

Renvoie tous les fournisseurs de sandbox enregistrés.

getBlobStoreProviders()

Renvoie tous les fournisseurs de magasins blob enregistrés.

Source

getSource()

Renvoie la source configurée ('code' ou 'db'), ou undefined lorsque l’éditeur a été construit sans source explicite.

const source = mastra.getEditor()?.getSource()

Valeur renvoyée : 'code' | 'db' | undefined

Lorsque source est omise, Editor utilise le stockage de base de données configuré même si getSource() renvoie undefined. Consultez les options de stockage d’Editor pour les flux de stockage et le versionnage de la source de code pour l’activation et le comportement de l’historique Git.