Aller au contenu principal

Intégrer Mastra à votre projet Express

Dans ce guide, vous allez créer avec Mastra et Express un Agent d’IA capable d’appeler des Tools. Grâce à l’adaptateur de serveur Express, vous pouvez exposer vos Agents sous forme d’endpoints HTTP sans écrire vous-même le routage ni exécuter un serveur Mastra distinct.

Avant de commencer
Lien direct vers Avant de commencer

  • Vous aurez besoin d’une clé d’API fournie par un Provider de modèle pris en charge. Si vous n’avez pas de préférence, utilisez OpenAI.
  • Installez Node.js v22.13.0 ou une version ultérieure

Créer une nouvelle application Express (facultatif)
Lien direct vers Créer une nouvelle application Express (facultatif)

Si vous disposez déjà d’une application Express, passez à l’étape suivante.

Clonez ce dépôt de démarrage, puis installez les dépendances :

git clone https://github.com/mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
npm install

Initialiser Mastra
Lien direct vers Initialiser Mastra

Dans le répertoire de votre projet Express, exécutez mastra init.

Lorsque vous y êtes invité, choisissez un Provider, par exemple OpenAI, puis saisissez votre clé :

npx mastra@latest init

Cette commande crée un dossier src/mastra contenant un exemple d’Agent météo et les fichiers suivants :

  • index.ts : configuration de Mastra, notamment la Memory
  • tools/weather-tool.ts : Tool permettant de récupérer la météo d’un lieu donné
  • agents/weather-agent.ts : Agent météo dont le prompt utilise le Tool

Vous transmettrez ensuite le fichier src/mastra/index.ts à l’adaptateur de serveur Express.

Ajouter l’adaptateur de serveur
Lien direct vers Ajouter l’adaptateur de serveur

Installez le package de l’adaptateur de serveur Express :

npm install @mastra/express@latest

Ouvrez le fichier d’entrée Express src/index.ts, puis ajoutez l’import et le code d’initialisation requis :

src/index.ts
import express, { type Request, type Response } from 'express'
import { MastraServer } from '@mastra/express'
import { mastra } from './mastra'

const app = express()
const PORT = process.env.PORT || 3000

// Middleware
app.use(express.json())

const server = new MastraServer({ app, mastra })
await server.init()

// Routes
app.get('/', (_req: Request, res: Response) => {
  res.json({ message: 'Hello, World!' })
})

// Start server
app.listen(PORT, () => {
  console.log(`Server is running on http://localhost:${PORT}`)
})

Le ⁠MastraServer est initialisé avec l’app Express existante et l’instance ⁠mastra racine. L’appel de ⁠init() enregistre le middleware Mastra et expose tous les endpoints Mastra disponibles.

Tester votre Agent
Lien direct vers Tester votre Agent

Par défaut, les endpoints de Mastra sont ajoutés sous le sous-chemin /api et utilisent les identifiants de vos Agents et Workflows. L’Agent weather-agent créé par défaut par mastra init est disponible à l’adresse /api/agents/weather-agent.

Démarrez votre serveur Express :

npm run start

Dans une autre fenêtre de terminal, utilisez curl pour interroger l’Agent météo :

curl -X POST http://localhost:3000/api/agents/weather-agent/generate -H "Content-Type: application/json" -d "{\"messages\":[{\"role\":\"user\",\"content\":\"What is the weather like in Seoul?\"}]}"

Étapes suivantes
Lien direct vers Étapes suivantes

Félicitations, vous avez créé votre Agent Mastra avec Express ! 🎉

Vous pouvez maintenant enrichir le projet avec vos propres Tools et votre propre logique :

  • En savoir plus sur les Agents
  • Ajouter des Tools à votre Agent
  • Ajouter une Memory similaire à la mémoire humaine à votre Agent

Lorsque vous serez prêt, découvrez comment Mastra s’intègre à Express :

On this page