Déploiement de Studio

Studio est une application monopage (SPA) fondée sur React qui s'exécute dans le navigateur et se connecte à un serveur Mastra en cours d'exécution.

Vous pouvez déployer Studio de deux manières principales :

• La plateforme Mastra fournit une instance Studio hébergée et vous permet d'en partager l'accès avec votre équipe au moyen d'un lien.
• Vous pouvez auto-héberger Studio sur votre propre infrastructure, soit avec votre serveur Mastra, soit séparément sous la forme d'une SPA autonome.

Cette page explique comment déployer Studio sur votre propre infrastructure. Les détails précis d'un déploiement pouvant varier considérablement selon vos besoins et votre configuration, nous présentons ici les principes généraux et les options disponibles.

Démarrage rapide

La manière la plus simple d'exécuter Studio consiste à utiliser la commande mastra studio.

Alors que mastra dev exécute à la fois Studio et une API à des fins de développement, mastra studio sert une interface statique autonome qui se connecte à un serveur Mastra déjà actif. Vous pouvez ainsi déployer Studio indépendamment du serveur Mastra si vous le souhaitez.

Ouvrez un terminal et installez globalement la CLI mastra :

npm

npm install -g mastra

pnpm

pnpm add -g mastra

Yarn

yarn global add mastra

Bun

bun add --global mastra

Exécutez la commande mastra studio :

mastra studio

Ouvrez localhost:3000 dans votre navigateur pour afficher l'interface de Studio. Par défaut, celle-ci tente de se connecter à un serveur Mastra exécuté sur http://localhost:4111. Si aucun serveur n'est trouvé à cette adresse, un formulaire vous permet de saisir l'URL de votre instance Mastra et le préfixe de l'API.

La commande utilise le module http intégré à Node et serve-handler pour distribuer les fichiers statiques.

remarque

Si vous hébergez Studio sous un chemin secondaire (par exemple /agents derrière Nginx), définissez MASTRA_STUDIO_BASE_PATH avant de démarrer Studio :

MASTRA_STUDIO_BASE_PATH=/agents mastra studio

Cette variable met à jour l'URL de base HTML et le routage des ressources statiques afin que l'instance Studio autonome fonctionne correctement sous ce chemin secondaire.

Plateforme Mastra

Pour utiliser Studio hébergé sur la plateforme Mastra, consultez Studio sur la plateforme Mastra.

Exécuter un serveur

L'exécution de mastra studio comme processus persistant ne diffère pas de celle de tout autre service Node.js. Les bonnes pratiques, outils et options habituels de déploiement s'appliquent également. Vous pouvez utiliser un gestionnaire de processus comme PM2, Docker ou des services cloud prenant en charge les applications Node.js. Comme pour tout service web, veillez à configurer correctement CORS et à surveiller les erreurs.

attention

Une fois connecté à votre serveur Mastra, Studio dispose d'un accès complet à vos Agents, Workflows et outils. Veillez à le sécuriser correctement en production, par exemple au moyen d'une authentification ou d'un VPN, afin d'empêcher tout accès non autorisé.

Consultez la documentation sur l'authentification pour en savoir plus.

Avec votre API

Vous pouvez également distribuer Studio avec votre serveur Mastra. Vous ne disposez ainsi que d'un seul service à déployer et à gérer.

Pour cela, exécutez mastra build avec l'option --studio :

mastra build --studio

Cette commande crée un dossier .mastra/output/studio contenant les ressources compilées de Studio. En définissant la variable d'environnement MASTRA_STUDIO_PATH, le serveur Mastra peut également distribuer l'interface Studio.

MASTRA_STUDIO_PATH=.mastra/output/studio node .mastra/output/index.mjs

Utiliser un CDN

Déploiement automatique

Certains Providers cloud proposent de déployer Studio avec votre fonction serverless. Les Providers actuellement pris en charge sont :

• VercelDeployer

Déploiement manuel

Vous ne pouvez pas déployer directement les ressources compilées de Studio sur un CDN, car l'interface dépend de certains paramètres d'exécution. Avec une configuration supplémentaire, vous pouvez transformer les ressources compilées en SPA autonome et la déployer sur n'importe quel service d'hébergement statique.

Suivez l'exemple ci-dessous pour créer une SPA avec Vite.

1. Créez un dossier et initialisez un nouveau projet Node.js :

   npm

   mkdir studio-spa
   cd studio-spa
   npm init

   pnpm

   mkdir studio-spa
   cd studio-spa
   pnpm init

   Yarn

   mkdir studio-spa
   cd studio-spa
   yarn init

   Bun

   mkdir studio-spa
   cd studio-spa
   bun init

2. Installez vite et mastra comme dépendances :

   npm

   npm install vite mastra

   pnpm

   pnpm add vite mastra

   Yarn

   yarn add vite mastra

   Bun

   bun add vite mastra

3. Ajoutez un script de build à votre fichier package.json :

   package.json

   {
     "scripts": {
       "build": "vite build"
     }
   }

4. Créez un fichier index.html de substitution :

   index.html

   <!doctype html>
   <html>
     <head></head>
     <body></body>
   </html>

5. Créez un fichier vite.config.js. Il copie les ressources compilées de Studio dans le dossier dist et remplace dans le HTML chaque valeur %%PLACEHOLDER%% par la valeur de la variable d'environnement correspondante.

   vite.config.js

   import { defineConfig, loadEnv } from 'vite'
   import { readFileSync, cpSync, writeFileSync } from 'node:fs'
   import { resolve, join } from 'node:path'
   
   const studioDir = resolve(import.meta.dirname, 'node_modules/mastra/dist/studio')
   
   export default defineConfig(({ mode }) => {
     const env = loadEnv(mode, process.cwd(), 'MASTRA_')
   
     return {
       plugins: [
         {
           name: 'mastra-studio',
           closeBundle() {
             const outDir = resolve(import.meta.dirname, 'dist')
             cpSync(studioDir, outDir, { recursive: true })
   
             const indexPath = join(outDir, 'index.html')
             const html = readFileSync(indexPath, 'utf-8')
             writeFileSync(
               indexPath,
               html.replaceAll(/%%(\w+)%%/g, (_, key) => env[key] ?? ''),
             )
           },
         },
       ],
       build: {
         emptyOutDir: true,
       },
     }
   })

6. Créez un fichier .env contenant les variables d'environnement nécessaires.

   .env

   MASTRA_SERVER_HOST=localhost
   MASTRA_SERVER_PORT=4111
   MASTRA_SERVER_PROTOCOL=http
   MASTRA_API_PREFIX=/api
   MASTRA_HIDE_CLOUD_CTA=false
   MASTRA_CLOUD_API_ENDPOINT=
   MASTRA_EXPERIMENTAL_FEATURES=false
   MASTRA_TEMPLATES=false
   MASTRA_TELEMETRY_DISABLED=true
   MASTRA_REQUEST_CONTEXT_PRESETS=
   MASTRA_THEME_TOGGLE=false
   MASTRA_EXPERIMENTAL_UI=false
   MASTRA_STUDIO_BASE_PATH=

7. Exécutez le script de build pour générer les fichiers statiques dans le dossier dist :

   npm

   npm run build

   pnpm

   pnpm run build

   Yarn

   yarn build

   Bun

   bun run build

8. Faites pointer votre Provider d'hébergement vers le dossier dist, puis déployez l'application !