Mastra : un cadre TypeScript pour agents, workflows et serveurs MCP

Le problème concret : recoller cinq briques autour d'un LLM

Un agent utile n'est pas un appel à une API de modèle. Il faut router vers plusieurs fournisseurs, exposer des outils, garder un historique, reprendre une exécution interrompue, mesurer les résultats. En TypeScript, cela se traduit souvent par un assemblage de bibliothèques hétérogènes, chacune avec son format de message et son cycle de vie. Mastra se présente comme la couche qui absorbe cet assemblage : le README annonce un routage vers plus de 40 fournisseurs derrière une interface unique, des agents, un moteur de workflow, la mémoire conversationnelle, les évaluations et l'observabilité dans le même paquet.

Le public visé est précis. Ce sont des développeurs qui écrivent du React, du Next.js ou du Node.js et qui veulent livrer une fonctionnalité d'IA sans changer de langage ni de chaîne d'outils. Le README cite explicitement l'intégration avec Vercel AI SDK UI et CopilotKit pour la partie interface. Une équipe dont la pile est Python, Java ou Go n'a ici aucune raison de se déplacer : tout le framework est TypeScript, et rien dans le matériel fourni n'indique une autre voie d'accès.

Agents et workflows : deux régimes d'exécution, pas un seul

La distinction centrale du projet tient en une phrase du README : les agents raisonnent sur un objectif, choisissent des outils et itèrent jusqu'à ce que le modèle produise une réponse finale ou qu'une condition d'arrêt soit remplie. Les workflows, eux, servent quand il faut un contrôle explicite. Le moteur est décrit comme un graphe, avec une syntaxe de flux en chaînage : .then(), .branch(), .parallel().

Ce n'est pas un détail cosmétique. Un agent est non déterministe par construction : le nombre d'étapes varie d'une exécution à l'autre. Un graphe de workflow fixe les transitions à l'avance. La documentation ne prétend pas que l'un remplace l'autre, et c'est la bonne lecture : on met un agent dans une branche du graphe quand l'étape est ouverte, et on garde le graphe pour tout ce qui doit être reproductible, par exemple une suite d'appels d'API avec validation intermédiaire.

Le point le plus intéressant est la suspension. Le README indique qu'un agent ou un workflow peut être suspendu pour attendre une entrée ou une approbation humaine, puis repris. L'état d'exécution est conservé via le stockage, ce qui autorise une pause sans limite de durée. C'est le mécanisme qui rend possible une validation par un humain au milieu d'un processus long, sans garder de processus en mémoire pendant des heures.

Mémoire, contexte et MCP : ce que le framework branche autour du modèle

Trois briques entourent l'appel au modèle. D'abord l'historique de conversation, cité dans le README sous memory/conversation-history. Ensuite la récupération de données depuis des sources externes (API, bases de données, fichiers) pour l'usage RAG. Enfin ce que le projet appelle Observational Memory, présenté comme une mémoire plus proche du comportement humain, destinée à la cohérence des agents sur la durée.

Le README ne détaille pas le fonctionnement interne d'Observational Memory. Il donne un lien vers la documentation et s'arrête là. C'est une lacune à noter : sans lire la page dédiée, on ne peut pas savoir ce qui est stocké, sous quelle forme, ni comment l'ancienneté est gérée. Un lecteur qui cherche un mécanisme de résumé automatique ou de fenêtre glissante ne trouvera pas la réponse dans le README.

Le volet MCP est plus net. Mastra permet d'écrire des serveurs Model Context Protocol qui exposent agents, outils et ressources structurées. L'intérêt pratique est l'inversion : au lieu de consommer des outils tiers, on publie ses propres agents vers n'importe quel système compatible avec le protocole. Cela transforme un agent Mastra en brique réutilisable hors de l'application qui l'a créé.

Mise en route : la commande, le Studio et le port 4111

Le README recommande une seule commande pour démarrer :

npm create mastra@latest

Une variante non interactive est documentée, avec le nom du projet et le fournisseur de modèle :

npm create mastra@latest <project-name> -- --llm <provider>

Les valeurs de fournisseur acceptées, telles que listées, sont openai, anthropic, google et xai. Le prompt fourni dans le README précise que si le fournisseur n'est pas supporté, la question est reposée avec la liste des valeurs valides. La commande crée un projet par défaut, installe les compétences Mastra pour les assistants de codage détectés et initialise Git lorsque c'est pertinent.

Ensuite, le README donne cette commande de démarrage du serveur de développement :

npx bgproc start -n <project-name> -w -- npm run dev

Le Studio est alors accessible sur http://localhost:4111. C'est l'interface de construction, de test et de gestion des agents, workflows et outils. Ce port fixe mérite d'être connu avant l'installation : sur une machine où 4111 est déjà pris, il faudra vérifier dans la configuration du projet comment le changer, point que le README n'aborde pas.

La licence mixte est le vrai critère de décision

Le dépôt applique un modèle à deux niveaux. Le cadre principal et, selon le README, la grande majorité du code sont sous Apache-2.0. Mais tout répertoire nommé ee/ relève de la Mastra Enterprise License, avec un exemple cité : packages/core/src/auth/ee/. Ces fonctionnalités sont en source disponible, utilisables librement en développement et en test, mais exigent une licence entreprise valide pour un usage en production.

Le champ de licence du dépôt est renseigné comme NOASSERTION, ce qui est cohérent avec cette dualité : aucun identifiant SPDX unique ne décrit l'ensemble. Le README renvoie à LICENSE.md pour la cartographie complète et à ee/LICENSE pour le texte de la licence entreprise.

La conséquence pratique est simple à énoncer, même si elle demande une vérification juridique au cas par cas : avant de mettre en production, il faut savoir si le chemin de code que vous utilisez traverse un répertoire ee/. La réponse ne se lit pas dans le README seul, elle se lit dans l'arborescence des paquets installés. C'est le premier contrôle à faire, et il ne coûte qu'une recherche dans node_modules. Le rythme de publication observé (1.65.0, 1.64.0, 1.63.0 entre le 26 août et le 9 septembre 2026) suggère des mises à jour fréquentes du paquet @mastra/core, donc un coût de suivi à prévoir sur les versions mineures.

Ce que le README ne dit pas, et une alternative réelle

Plusieurs zones restent floues dans le matériel fourni. Le README affirme qu'on peut déployer Mastra comme serveur autonome, sans décrire le format de ce déploiement ni les contraintes d'exploitation. Il mentionne des évaluations et de l'observabilité sans nommer les backends pris en charge. Il cite des templates, un cours et des vidéos, ce qui renvoie à de la documentation externe plutôt qu'à des garanties techniques. Rien de tout cela n'est un défaut en soi, mais un lecteur qui évalue le projet sur ce seul README travaille sur une vue partielle.

Pour situer l'approche, la comparaison la plus utile se fait avec LangChain.js. Là où Mastra propose un graphe de workflow avec .then(), .branch() et .parallel() comme primitive de contrôle, LangChain.js s'organise autour d'abstractions de chaînes et d'agents, avec sa propre bibliothèque d'intégrations. La différence de fond n'est pas la liste des fournisseurs : c'est le régime d'exécution. Mastra met en avant la suspension et la reprise via le stockage, ce qui suppose une persistance d'état assumée dès la conception. Un projet qui n'a jamais besoin d'interrompre une exécution pour attendre un humain n'a pas ce besoin, et une bibliothèque plus légère fera l'affaire.

Second cas où Mastra est le mauvais outil : un script unique qui appelle un modèle avec un prompt fixe. Ajouter un graphe, un stockage et un Studio pour cela revient à installer une infrastructure sans usage. Le coût de compréhension dépasse le gain.

Conclusion éditoriale

Mastra convient aux équipes déjà en TypeScript qui veulent des agents, des workflows suspendables et un serveur MCP dans le même dépôt, sans assembler cinq bibliothèques. Il ne convient pas à qui cherche un runtime Python, ni à qui refuse une licence maison sur une partie du code. Avant d'adopter, vérifier deux points précis : le contenu des répertoires ee/ dans les paquets que vous installez, et le comportement de reprise après suspension avec le backend de stockage que vous comptez utiliser en production.

Sources officielles

1. Issues
2. mastra-ai/mastra on GitHub
3. Project website
4. README
5. Releases