Aller au contenu principal

Déployer Mastra sur Vercel

Utilisez @mastra/deployer-vercel pour déployer votre serveur Mastra sous forme de fonctions serverless sur Vercel. Le Deployer regroupe votre code et génère un répertoire .vercel/output conforme à la Build Output API de Vercel, prêt à être déployé sans configuration supplémentaire.

info

Ce guide traite du déploiement du serveur Mastra. Si vous utilisez un adaptateur de serveur ou un framework web, procédez au déploiement comme vous le feriez habituellement pour ce framework.

Avant de commencer
Lien direct vers Avant de commencer

Vous aurez besoin d’une application Mastra et d’un compte Vercel.

attention

Les fonctions Vercel utilisent un système de fichiers éphémère. Tout stockage configuré, y compris celui de l’observabilité, doit donc être hébergé en externe. Si vous utilisez LibSQLStore avec une URL de fichier, adoptez une base de données hébergée à distance.

Installation
Lien direct vers Installation

Ajoutez le package @mastra/deployer-vercel à votre projet :

npm install @mastra/deployer-vercel@latest

Importez VercelDeployer et définissez-le comme Deployer dans votre configuration Mastra :

src/mastra/index.ts
import { Mastra } from '@mastra/core'
import { VercelDeployer } from '@mastra/deployer-vercel'

export const mastra = new Mastra({
  deployer: new VercelDeployer(),
})

Déployer
Lien direct vers Déployer

  1. Envoyez votre projet vers un Provider Git distant, par exemple GitHub, puis connectez votre dépôt à Vercel.

    Par défaut, Vercel exécute npm run build, qui déclenche mastra build. Si vous n’avez pas de script de build, ajoutez "build": "mastra build" à votre package.json.

    remarque

    Pensez à définir les variables d’environnement nécessaires à l’exécution de votre application, par exemple la clé d’API de votre Provider de modèle.

  2. Lorsque vous êtes prêt, cliquez sur Deploy et attendez la fin du premier déploiement.

  3. Vérifiez votre déploiement à l’adresse https://<your-project>.vercel.app/api/agents, qui doit renvoyer une liste JSON de vos Agents.

    Comme le serveur Mastra préfixe chaque endpoint avec /api, vous devez l’ajouter à vos URL lorsque vous effectuez des requêtes.

  4. Vous pouvez maintenant appeler vos endpoints Mastra via HTTP.

    attention

    Configurez l’authentification avant d’exposer publiquement vos endpoints.

Studio
Lien direct vers Studio

Vous pouvez déployer Studio avec votre API en activant l’option studio. Studio est déployé sous forme de ressources statiques servies depuis l’Edge CDN de Vercel et ne consomme donc aucune invocation de fonction.

src/mastra/index.ts
import { Mastra } from '@mastra/core'
import { VercelDeployer } from '@mastra/deployer-vercel'

export const mastra = new Mastra({
  deployer: new VercelDeployer({
    studio: true,
  }),
})

Après le déploiement, Studio est disponible à l’URL racine (https://<your-project>.vercel.app/) et l’API reste accessible sous /api/*. Studio se connecte automatiquement à l’API de la même origine ; aucune variable d’environnement supplémentaire n’est donc nécessaire.

Studio sert ses propres pages depuis le CDN, tandis que tous les autres chemins sont dirigés vers votre serveur. Les routes ajoutées avec registerApiRoute() restent ainsi accessibles à leurs propres chemins. Évitez d’attribuer à une route personnalisée un chemin déjà utilisé par Studio, comme /agents ou /workflows, car Studio les réserve en priorité.

attention

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

Remplacements facultatifs
Lien direct vers Remplacements facultatifs

Le Deployer Vercel prend en charge des options de configuration écrites dans la configuration de fonction de la Vercel Output API. Consultez la référence de VercelDeployer pour découvrir les options disponibles, telles que maxDuration, memory et regions.

Observabilité
Lien direct vers Observabilité

Les fonctions serverless peuvent s’arrêter immédiatement après avoir renvoyé une réponse. Tout traitement asynchrone en attente, comme l’envoi de télémétrie, peut être interrompu avant son terme. Attendre flush() garantit l’envoi de toutes les traces avant l’arrêt de la fonction.

api/chat.ts
import type { VercelRequest, VercelResponse } from '@vercel/node'
import { mastra } from '../src/mastra'

export default async function handler(req: VercelRequest, res: VercelResponse) {
  const { message } = req.body
  const agent = mastra.getAgent('myAgent')
  const result = await agent.generate([{ role: 'user', content: message }])

  await mastra.observability.flush()

  return res.json(result)
}
attention

Le Deployer Vercel n’inclut aucun appel à flush. Si vous en avez besoin, vous devez encapsuler vous-même le Handler afin d’ajouter cette logique avant de renvoyer la réponse. Vous pouvez également déployer l’application sur un serveur de longue durée, tel qu’une machine virtuelle, où ce problème ne se pose pas.

On this page