Editor

Editor fonctionne comme un CMS pour les Agents Mastra. Les collaborateurs peuvent modifier les instructions et les Tools d’un Agent dans Studio sans accéder au code source ni écrire de code. Ils peuvent tester les modifications avant de les mettre en production.

TypeScript définit les valeurs par défaut de l’Agent. Editor enregistre les modifications séparément au lieu de mettre à jour le code source. Les collaborateurs peuvent ainsi améliorer l’Agent tandis que les développeurs conservent le contrôle de son modèle, de son identité et de son environnement d’exécution.

Un Studio déployé rend Editor accessible aux collaborateurs en dehors du développement local.

📹 À regarder

Regardez l’atelier Mastra Editor pour suivre une présentation guidée.

Quand utiliser Editor

Utilisez Editor lorsqu’un Agent est défini dans le code, mais que les personnes responsables de son comportement ne doivent pas modifier le code source. Editor convient particulièrement lorsque les instructions ou les Tools changent souvent et doivent être testés avant d’atteindre les utilisateurs. Si les développeurs prennent en charge chaque modification et publient la configuration de l’Agent avec l’application, conservez plutôt la configuration de l’Agent dans le code.

Démarrage rapide

Installez @mastra/editor. Ce guide de démarrage rapide utilise LibSQL pour stocker les modifications d’Editor :

npm

npm install @mastra/editor @mastra/libsql

pnpm

pnpm add @mastra/editor @mastra/libsql

Yarn

yarn add @mastra/editor @mastra/libsql

Bun

bun add @mastra/editor @mastra/libsql

Ajoutez MastraEditor et le stockage à l’instance Mastra. Vous pouvez réutiliser un stockage existant au lieu d’ajouter le stockage LibSQL présenté ici.

src/mastra/index.ts

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

export const mastra = new Mastra({
  agents: {/* existing agents */},
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
  editor: new MastraEditor(),
})

Utiliser Editor dans Studio

Dans Studio, ouvrez Agents, sélectionnez un Agent, puis Editor. Les collaborateurs peuvent mettre à jour les instructions et les Tools de l’Agent selon ses autorisations Editor.

Avec le stockage en base de données, enregistrez les modifications sous forme de brouillon afin de les tester sans affecter l’Agent en production. Publiez le brouillon lorsqu’il est prêt à être utilisé.

Instructions

La section Instructions affiche le prompt système de l’Agent défini dans le code. Les collaborateurs peuvent le remplacer ou ajouter des blocs d’instructions.

Un bloc d’instructions peut inclure des valeurs de la requête actuelle. Par exemple, {{userName}} insère un nom fourni par le contexte de requête. Une condition d’affichage peut afficher un bloc uniquement pour un client, un rôle ou un feature flag donné.

Blocs de prompts

Un bloc de prompt est un texte d’instructions enregistré qui peut être utilisé par plusieurs Agents. Créez-en un sous Prompts, publiez-le, puis ouvrez la section Instructions d’un Agent et sélectionnez Add block.

Par exemple, les Agents chargés de l’assistance, des retours et du suivi des commandes peuvent tous avoir besoin de la même politique de remboursement. Enregistrez cette politique sous forme de bloc de prompt et ajoutez-la à chaque Agent. Lorsqu’elle change, mettez à jour et publiez le bloc une seule fois au lieu de modifier trois Agents.

Lorsqu’un bloc de prompt change, chaque Agent qui référence sa version publiée reçoit la mise à jour. Les modifications du brouillon sont utilisées uniquement pendant l’aperçu et n’affectent donc pas les Agents en production avant la publication du bloc.

Consultez la référence des blocs de prompts pour la syntaxe des modèles, les conditions, les versions et les API.

Tools

Les Tools permettent à un Agent d’effectuer des actions. Les collaborateurs choisissent parmi les Tools accessibles à Editor, mais ne peuvent pas en implémenter de nouveaux dans Studio. Leur disponibilité dépend de leur source :

• Les Tools du projet doivent être implémentés et enregistrés dans le projet Mastra par un développeur.
• Les Tools d’intégration deviennent disponibles après l’enregistrement d’un Provider comme Composio ou Arcade par un développeur. Les collaborateurs peuvent alors parcourir le catalogue du Provider et ajouter des Tools sans que chacun d’eux soit d’abord ajouté dans le code.
• Les Tools MCP deviennent disponibles lorsqu’un client MCP est configuré. Un collaborateur autorisé peut créer le client dans Studio, puis choisir parmi les Tools exposés par ses serveurs.

Dans la section Tools de l’Agent, les collaborateurs peuvent ajouter les Tools dont il a besoin ou réécrire la description d’un Tool pour cet Agent. Une description plus précise aide l’Agent à comprendre quand utiliser le Tool sans modifier celui-ci.

Tools du projet

Les développeurs peuvent enregistrer un Tool de projet dans l’instance Mastra afin de le rendre accessible dans Editor :

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraEditor } from '@mastra/editor'
import { searchOrders } from './tools/search-orders'

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

Le sélecteur de Tools de Studio répertorie le Tool. Un collaborateur peut l’ajouter à un Agent lorsque celui-ci autorise la modification des Tools. La vue Editor de l’Agent répertorie également les Tools associés dans le code.

Composio

Composio fournit des Tools pour des services comme GitHub, Slack et Gmail. Enregistrez le Provider avec une clé API Composio afin de rendre son catalogue de Tools accessible dans Editor :

src/mastra/index.ts

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

export const mastra = new Mastra({
  agents: {/* agents */},
  editor: new MastraEditor({
    toolProviders: {
      composio: new ComposioToolProvider({
        apiKey: process.env.COMPOSIO_API_KEY!,
      }),
    },
  }),
})

Les identifiants des Tools Composio ressemblent à GITHUB_CREATE_ISSUE. Par défaut, un Tool sélectionné utilise la connexion associée à l’auteur de l’Agent. Consultez la portée des connexions pour utiliser plutôt la connexion de chaque appelant.

Arcade

Arcade fournit un autre catalogue de Tools avec authentification intégrée. Enregistrez-le avec une clé API Arcade :

src/mastra/index.ts

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

export const mastra = new Mastra({
  agents: {/* agents */},
  editor: new MastraEditor({
    toolProviders: {
      arcade: new ArcadeToolProvider({
        apiKey: process.env.ARCADE_API_KEY!,
      }),
    },
  }),
})

Les identifiants des Tools Arcade utilisent le format Toolkit.ToolName, comme Github.GetRepository.

Clients MCP

Les collaborateurs peuvent également créer un client MCP réutilisable dans Studio et ajouter ses Tools à un Agent. Les clients stockés peuvent démarrer un serveur stdio local ou se connecter à un serveur HTTP distant. Les filtres de Tools permettent à chaque Agent d’utiliser uniquement ceux dont il a besoin sur ce serveur.

Consultez la référence des Tools d’Editor pour la configuration MCP, les conditions, le filtrage et l’ordre de résolution. Consultez ToolProvider pour les options des Providers.

Déterminer ce que les collaborateurs peuvent modifier

Par défaut, les collaborateurs peuvent modifier les instructions d’un Agent et gérer ses Tools, y compris leurs descriptions. L’id, le name et le model de l’Agent proviennent toujours du code.

Utilisez le champ editor de l’Agent pour limiter les éléments modifiables :

src/mastra/agents/support-agent.ts

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

export const supportAgent = new Agent({
  id: 'support-agent',
  name: 'Support agent',
  instructions: 'Help customers with Acme products.',
  model: 'openai/gpt-5.6-sol',
  editor: {
    instructions: true,
    tools: {
      description: true,
    },
  },
})

Cet Agent permet aux collaborateurs de modifier ses instructions et d’améliorer la description des Tools qui lui sont déjà associés. Ils ne peuvent ni ajouter ni supprimer de Tools.

Valeur de editor	Éléments modifiables par les collaborateurs
Omise	Instructions, Tools et descriptions des Tools
false	Aucun élément
{ instructions: true }	Instructions
{ tools: true }	Tools et descriptions des Tools
{ tools: { description: true } }	Descriptions des Tools déjà ajoutés dans le code

Studio affiche tous les autres éléments en lecture seule. Consultez les remplacements d’Editor pour obtenir la configuration complète.

Choisir où stocker les modifications

Editor peut enregistrer les modifications dans la base de données configurée ou sous forme de fichiers dans le dépôt.

Stockage en base de données

La base de données est l’option par défaut. Editor utilise le stockage configuré dans l’instance Mastra, ce qui permet à l’application et à Editor de partager le même backend.

Pour utiliser un backend distinct pour les données d’Editor, définissez l’option editor de MastraCompositeStore. Les domaines de stockage sans route explicite continuent d’utiliser son stockage default.

L’exemple suivant conserve les données de l’application et d’Editor dans des fichiers LibSQL distincts :

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraCompositeStore } from '@mastra/core/storage'
import { MastraEditor } from '@mastra/editor'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  agents: {/* existing agents */},
  storage: new MastraCompositeStore({
    id: 'mastra-storage',
    default: new LibSQLStore({
      id: 'app-storage',
      url: 'file:./mastra.db',
    }),
    editor: new LibSQLStore({
      id: 'editor-storage',
      url: 'file:./editor.db',
    }),
  }),
  editor: new MastraEditor(),
})

Fichiers du dépôt

Utilisez la source de code afin de conserver les remplacements avec le code de l’application. Les développeurs peuvent examiner les fichiers dans des pull requests et les déployer avec l’application :

src/mastra/index.ts

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

export const mastra = new Mastra({
  agents: {/* existing agents */},
  editor: new MastraEditor({
    source: 'code',
    codePath: './mastra/editor',
  }),
})

Dans ce mode, chaque Agent modifié possède un fichier JSON de remplacement. Editor ne génère pas de TypeScript et ne modifie pas le fichier dans lequel l’Agent a été créé. Par défaut, un Agent dont l’identifiant est support-agent reçoit le fichier suivant :

mastra/editor/agents/support-agent.json

Le fichier contient uniquement les parties gérées par Editor. Par exemple :

mastra/editor/agents/support-agent.json

{
  "instructions": "Help customers with Acme products and answer in their language.",
  "tools": {
    "searchOrders": {
      "description": "Look up an order by its number"
    }
  }
}

Le modèle, le nom et les autres champs de l’Agent contrôlés par le code restent dans son fichier TypeScript. Mastra lit le JSON et applique ces valeurs lors de l’exécution de l’Agent.

Lorsqu’un collaborateur enregistre dans Studio, il peut écrire le fichier dans le système de fichiers local ou le télécharger. Avec une intégration de gestion du code source, Studio peut plutôt ouvrir une pull request. Git fournit alors la révision et l’historique des versions.

Consultez MastraEditor pour les emplacements de fichiers et les options de source.

Gestion des versions

Les Agents et blocs de prompts stockés en base de données utilisent des versions brouillon et publiées. L’enregistrement crée un brouillon tandis que l’Agent en production continue d’utiliser la version publiée. La publication met le brouillon en production. Restaurer une ancienne version crée un brouillon que les collaborateurs peuvent tester avant de le publier.

Les remplacements d’Agents stockés dans le code utilisent des fichiers JSON et l’historique Git.

Sélectionner une version

Une application peut choisir une version stockée pour chaque requête en transmettant un état (published ou draft) ou un identifiant de version précis :

Version selection

const publishedAgent = await mastra.getAgentById('support-agent', {
  status: 'published',
})

const draftAgent = await mastra.getAgentById('support-agent', {
  status: 'draft',
})

const versionedAgent = await mastra.getAgentById('support-agent', {
  versionId: 'abc-123',
})

La sélection de version permet de :

• Comparer deux versions dans un test A/B.
• Donner accès à un brouillon à un petit groupe avant de le publier pour tous.
• Maintenir la production sur la version publiée tandis que la préproduction utilise le dernier brouillon.
• Épingler un client à une version précise.

Les mêmes contrôles de version fonctionnent lorsqu’un superviseur appelle des sous-Agents. Les développeurs peuvent tester le brouillon d’un sous-Agent sans modifier le reste du système.

Consultez la référence de la gestion des versions d’Editor pour la sélection des versions, le comportement des sous-Agents, les points de terminaison REST et les méthodes du SDK.

Accès programmatique

Tout ce qui est accessible dans Studio l’est également de manière programmatique au moyen de mastra.getEditor(), de l’API REST ou du SDK client. Utilisez ces interfaces pour automatiser des mises à jour en masse ou initialiser depuis le code des configurations stockées. Elles peuvent également alimenter des automatisations qui ajustent les Agents en fonction des résultats d’évaluation.

Appelez mastra.getEditor() lorsque le code de l’application a accès à l’instance Mastra :

src/scripts/update-agent.ts

import { mastra } from '../mastra'

const editor = mastra.getEditor()!

await editor.agent.update({
  id: 'support-agent',
  instructions: 'Help customers with Acme products. Reply in their language.',
})

La méthode directe editor.agent.update() active immédiatement la nouvelle version. Pour créer un brouillon sans modifier l’Agent en production, utilisez plutôt l’API REST des Agents stockés ou le SDK client :

Create a draft through the REST API

curl -X PATCH http://localhost:4111/api/stored/agents/support-agent \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Help customers with Acme products. Reply in their language."
  }'

Le préfixe par défaut du serveur est /api. Les développeurs peuvent définir un préfixe personnalisé dans la configuration du serveur.

Consultez les espaces de noms de MastraEditor et l’API Agents du SDK client pour connaître les opérations disponibles.

Étapes suivantes

• Référence de MastraEditor
• Référence des blocs de prompts
• Référence des Tools d’Editor
• Référence de la gestion des versions d’Editor