Vue d’ensemble de Server

Mastra s’exécute comme un serveur HTTP qui expose vos agents, workflows et autres fonctionnalités en tant qu’endpoints d’API. Le serveur gère le routage des requêtes, l’exécution des middlewares, l’authentification et les réponses en streaming.

info

Cette page couvre les options de configuration server transmises au constructeur Mastra. Pour exécuter Mastra avec votre propre serveur HTTP, comme Hono ou Express, consultez Adaptateurs de serveur.

Fonctionnalités de Server

• Middleware : interceptez les requêtes pour l’authentification, la journalisation, CORS ou l’injection de contexte propre à la requête.
• Routes d’API personnalisées : étendez le serveur avec vos propres endpoints HTTP ayant accès à l’instance Mastra.
• Request Context : transmettez des valeurs propres à la requête aux agents, tools et workflows selon les conditions d’exécution.
• Adaptateurs de serveur : exécutez Mastra avec Express, Hono ou votre propre serveur HTTP au lieu du serveur généré.
• Adaptateurs personnalisés : créez des adaptateurs pour des frameworks qui ne sont pas officiellement pris en charge.
• SDK client Mastra : client sûr du point de vue des types pour appeler agents, workflows et tools depuis des environnements navigateur ou serveur.
• A2A : exposez les agents par des cartes d’agent et des flux de tâches A2A, ainsi que des notifications push.
• Authentification : sécurisez les endpoints avec JWT, Clerk, Supabase, Firebase, Auth0 ou WorkOS.

Configuration

Configurez le serveur en transmettant un objet server au constructeur Mastra :

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    port: 3000, // Defaults to PORT env var or 4111
    host: '0.0.0.0', // Defaults to MASTRA_HOST env var or 'localhost'
  },
})

Consultez la référence de configuration pour obtenir la liste complète des options de serveur disponibles.

Déployer votre serveur

Les serveurs Mastra peuvent être déployés dans tout environnement compatible avec Node.js. Déployez-les en production avec la plateforme Mastra ou votre propre infrastructure. Consultez la documentation de déploiement pour savoir comment faire.

Architecture de Server

Mastra utilise Hono comme framework de serveur HTTP sous-jacent. Lorsque vous build une application Mastra avec mastra build, cette commande génère un serveur HTTP fondé sur Hono dans le répertoire .mastra.

Le serveur fournit :

• Des endpoints d’API pour tous les agents et workflows enregistrés
• Des routes d’API et middlewares personnalisés
• Une authentification couvrant plusieurs providers
• Un contexte de requête pour la configuration à l’exécution
• La suppression de données des streams pour sécuriser les réponses

API REST

Vous pouvez explorer tous les endpoints disponibles dans la spécification OpenAPI à l’adresse http://localhost:4111/api/openapi.json, qui détaille chaque endpoint et ses schémas de requête et de réponse.

Pour explorer l’API de manière interactive, ouvrez Swagger UI à l’adresse http://localhost:4111/swagger-ui. Vous pourrez y découvrir les endpoints et les tester directement depuis votre navigateur.

remarque

Les endpoints OpenAPI et Swagger sont désactivés par défaut en production. Pour les activer, définissez respectivement server.build.openAPIDocs et server.build.swaggerUI sur true.

API Responses d’OpenAI

Mastra expose des routes Responses et Conversations compatibles avec OpenAI, qui vous permettent d’utiliser les agents Mastra comme une Responses API. Ces routes sont des adaptateurs reposant sur les agents, la mémoire et le stockage Mastra ; les requêtes s’exécutent donc via l’agent Mastra sélectionné plutôt que comme un proxy brut de provider.

Ces API sont actuellement expérimentales.

Utilisez agent_id pour sélectionner l’agent Mastra qui doit traiter la requête. Les requêtes initiales ciblent directement un agent, et les tours de suivi stockés peuvent se poursuivre avec previous_response_id. Vous pouvez également transmettre model pour remplacer le modèle configuré de l’agent pour une seule requête. Si vous omettez model, Mastra utilise le modèle déjà configuré sur l’agent.

Les routes Responses prennent en charge le streaming, l’appel de fonctions avec les tools, les continuations stockées avec previous_response_id, les threads de conversation avec conversation_id, le passthrough spécifique au provider avec providerOptions et la sortie JSON avec text.format.

Pour le contrat complet des requêtes et réponses, consultez la référence de l’API Responses et la référence de l’API Conversations. Pour la liste complète des routes HTTP, consultez les routes du serveur.

Masquage des données de stream

Lors du streaming des réponses d’agent, la couche HTTP masque les prompts système, définitions de tools, clés d’API et données similaires dans chaque chunk avant de l’envoyer aux clients. Ce comportement est activé par défaut.

Ce comportement ne peut être configuré qu’en utilisant des adaptateurs de serveur. Pour les adaptateurs de serveur, le masquage des données de stream est également activé par défaut.

Configuration TypeScript

Mastra exige des paramètres module et moduleResolution compatibles avec les versions modernes de Node.js. Les options héritées telles que CommonJS ou node ne sont pas prises en charge.

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true,
    "outDir": "dist"
  },
  "include": ["src/**/*"]
}

Étapes suivantes

• Ajoutez un middleware
• Créez des routes d’API personnalisées
• Ajoutez une authentification
• Déployez votre serveur en production