Mastra est une bibliothèque pour construire des agents LLM en TypeScript : vous définissez un agent avec un modèle, des outils et de la mémoire, vous composez un workflow à partir d'étapes, vous notez les réponses et vous inspectez les exécutions dans un panneau local. La version actuelle de @mastra/core est la 1.61.0 du 21 août 2026, publiée sous Apache 2.0 avec une exception importante décrite plus bas.
Ce que Mastra apporte et ce qu'il n'apporte pas
Le paquet @mastra/core exporte des dizaines de sous-chemins, mais en pratique vous travaillez avec quatre concepts. Un agent est un objet avec des instructions, un modèle, un ensemble d'outils et une mémoire facultative. Un outil est une fonction avec une description et des schémas d'entrée et de sortie. Un workflow est un graphe d'étapes avec un flux de données typé. Un scorer est une fonction qui évalue le résultat d'un agent et enregistre un nombre accompagné d'une justification.
Par-dessus se trouve une couche serveur. Le paquet @mastra/server expose les agents et les workflows en HTTP, et des adaptateurs séparés le rattachent à une application existante : @mastra/hono, @mastra/express, @mastra/fastify, @mastra/koa, @mastra/nestjs, @mastra/next et @mastra/tanstack-start. Si vous construisez sur Next.js, l'agent n'a pas besoin d'être un processus séparé.
Mastra n'est pas un fournisseur de modèles et n'a pas d'API d'inférence propre. L'AI SDK se trouve en dessous, en trois générations à la fois : le cœur déclare des alias @ai-sdk/provider-v5 pointant vers 2.0.3, @ai-sdk/provider-v6 vers 3.0.14 et @ai-sdk/provider-v7 vers 4.0.4, avec un ensemble correspondant de provider-utils. Cela aide pendant les migrations, mais une seule installation embarque ainsi trois couches de compatibilité parallèles.
Deux dépendances du cœur méritent un coup d'œil avant un audit. posthog-node en ^5.46.1 est de la télémétrie intégrée à la bibliothèque plutôt qu'un plugin ajouté. chat en ^4.34.0 est le Chat SDK du dépôt vercel/chat, ce qui signifie que les intégrations Slack, Teams et Google Chat sont tirées que vous les utilisiez ou non. @mastra/core 1.61.0 décompressé pèse environ 65 Mo pour une archive de 13,9 Mo.
Versions, rythme de publication et famille de paquets
La version 1.0.0 est sortie le 20 janvier 2026 et la 1.61.0 le 21 août. Cela fait 61 incréments mineurs en 213 jours, un tous les trois jours et demi en moyenne. Le registre contient 71 versions stables 1.x, soit une tous les trois jours. Pour mémoire, le registre liste 1505 versions de @mastra/core, mais l'immense majorité sont des instantanés de branches numérotés 0.0.0-<branch-name>-<date> et publiés à chaque pull request.
J'ai vérifié qu'aucune version dépréciée ne se trouve en tête de liste en se faisant passer pour actuelle. Exactement deux sont marquées deprecated, 0.10.13 et 0.15.0, toutes deux de l'ancienne ligne 0.x. Rien n'est retiré dans la ligne 1.x, et les tags alpha et beta pointent respectivement vers 1.62.0-alpha.2 et 1.1.0-alpha.2.
La famille est vaste. Interroger le registre npm pour @mastra renvoie au moins 168 paquets dans ce scope, en ne comptant que les 250 premiers résultats. La numérotation est volontairement inégale : @mastra/deployer et @mastra/server avancent en phase avec le cœur à 1.61.0, @mastra/memory est à 1.27.0, @mastra/rag à 2.6.0, @mastra/mcp à 1.17.1 et @mastra/playground-ui à 51.0.0.
J'ai vérifié séparément les plages de dépendances peer, car c'est une source classique de conflits d'installation. Toutes ont la forme >=X-0 <2.0.0-0, donc elles sont ouvertes vers le haut et rien n'entre en conflit avec le cœur le plus récent. Les bornes inférieures divergent en revanche : @mastra/rag, @mastra/evals et @mastra/mcp acceptent n'importe quel cœur 1.x, @mastra/libsql exige au moins 1.51.0, @mastra/pg au moins 1.53.0 et @mastra/inngest au moins 1.58.0. Figer un cœur plus ancien pour éviter les changements d'interface exclut donc les adaptateurs les plus récents.
La licence selon trois sources
Le dépôt mastra-ai/mastra n'a pas de fichier LICENSE. Il n'y a que LICENSE.md, identique sur les branches main et master. Les variantes LICENSE, LICENSE.MD, LICENSE.txt, LICENCE et COPYING renvoient toutes 404, donc un scanner qui ne cherche que le nom sans extension ne trouve rien.
Le contenu de ce fichier n'est pas de l'Apache 2.0 pur. Il s'ouvre sur une exclusion : tout ce qui se trouve dans n'importe quel répertoire nommé ee/, y compris packages/core/src/auth/ee/ et packages/server/src/server/auth/ee/, relève de la licence figurant dans ee/LICENSE. Seul le reste est sous Apache 2.0, avec une mention de copyright pour Kepler Software, Inc.
Le fichier ee/LICENSE existe et s'intitule Mastra Enterprise Edition (EE) License. Il autorise la modification du code pour votre propre développement et vos tests, tandis que l'usage en production exige un accord écrit avec Kepler Software. La production désigne tout usage au-delà du développement et des tests sur vos propres systèmes, et un environnement de préproduction est explicitement compté comme du test. La copie, la distribution et la vente sont interdites.
La deuxième source, le champ license du registre npm, indique simplement Apache-2.0 sans aucune trace de cette exclusion. La troisième source est plus intéressante encore. Le paquet publié @mastra/core 1.61.0 ne contient aucun fichier de licence, car le champ files de son package.json vaut ["dist", "CHANGELOG.md", "./**/*.d.ts"]. Il contient en revanche 66 chemins sous des répertoires ee/, parmi lesquels dist/auth/ee/fga-check.js et dist/agent-builder/ee/. Autrement dit, du code couvert par la licence commerciale est livré dans un paquet déclaré Apache 2.0, et le texte de la licence n'est pas du tout dans le paquet.
La cohérence au sein de la famille est inégale aussi. @mastra/inngest 1.8.7 se comporte à l'inverse du cœur : il n'a aucun champ license, mais embarque un LICENSE.md avec le texte complet de l'exception. Le même champ manque dans @mastra/editor 0.14.0 et @mastra/redis-streams 0.4.0. Les paquets @mastra/memory, @mastra/rag, @mastra/evals, @mastra/mcp, @mastra/libsql et la CLI mastra embarquent tous correctement un fichier de licence.
À retenir en pratique : si vous tenez un registre des licences de dépendances, l'entrée « Apache-2.0 » pour @mastra/core est incomplète. Vérifiez si vous touchez quoi que ce soit de @mastra/core/auth/ee ou du constructeur d'agents, car c'est un régime juridique différent.
# core and CLI
npm install @mastra/core mastra
# durable storage instead of the default process memory
npm install @mastra/libsql
# what usually follows later
npm install @mastra/memory @mastra/evals @mastra/mcp
# local studio on port 4111
npx mastra dev
# build into .mastra/output
npx mastra build
# what the license inside the package really is
npm pack @mastra/core@1.61.0
tar tzf mastra-core-1.61.0.tgz | grep -E "^package/(LICENSE|LICENCE)"Agent, outils et mémoire dans le code
La configuration de l'agent accepte id, name, instructions, model, tools, memory, workflows, agents, scorers, inputProcessors, outputProcessors, defaultOptions et maxSteps. Vous créez un outil avec createTool et les champs id, description, inputSchema, outputSchema et execute. Depuis la ligne 1.x, le premier argument de execute est directement la donnée d'entrée plutôt qu'un objet avec un champ context, ce qui est le piège le plus courant en portant d'anciens exemples.
import { Mastra } from '@mastra/core'
import { Agent } from '@mastra/core/agent'
import { createTool } from '@mastra/core/tools'
import { Memory } from '@mastra/memory'
import { LibSQLStore } from '@mastra/libsql'
import { z } from 'zod'
const invoiceTool = createTool({
id: 'fetch-invoice',
description: 'Fetches an invoice by number',
inputSchema: z.object({ number: z.string() }),
outputSchema: z.object({ total: z.number(), currency: z.string() }),
requireApproval: false,
execute: async (inputData) => {
const res = await fetch(`https://erp.internal/invoices/${inputData.number}`)
return res.json()
}
})
const memory = new Memory({
storage: new LibSQLStore({ id: 'agent-memory', url: 'file:./agent-memory.db' }),
options: {
lastMessages: 20,
semanticRecall: { topK: 5, messageRange: 2, scope: 'resource' },
workingMemory: {
enabled: true,
scope: 'resource',
template: '# Customer profile\n- **Name**:\n- **Billing currency**:'
}
}
})
export const mastra = new Mastra({
agents: {
billing: new Agent({
id: 'billing',
name: 'Billing',
instructions: 'Answer questions about invoices only.',
model: 'openai/gpt-5-mini',
tools: { invoiceTool },
memory
})
},
storage: new LibSQLStore({ id: 'runs', url: 'file:./mastra-runs.db' })
})Le champ requireApproval accepte un booléen ou une fonction et suspend l'exécution de l'outil jusqu'à son approbation. Associé à suspendSchema et resumeSchema, il offre une gestion avec un humain dans la boucle sans file de tâches maison.
Le cœur exige Node 22.13.0 ou plus récent et déclare une dépendance peer sur zod dans la plage ^3.25.0 || ^4.0.0. Les schémas passent par Standard Schema, donc zod n'est formellement pas la seule option, mais c'est sa version qui est vérifiée à l'installation. Quiconque écrit en TypeScript pur obtient l'inférence de types depuis le schéma de l'outil jusqu'au résultat de l'étape du workflow.
Workflows et scorers
Vous créez un workflow avec createWorkflow, des étapes avec createStep, et vous assemblez le graphe avec then, parallel, branch, dountil, dowhile, foreach, map, sleep, sleepUntil et waitForEvent, en le fermant avec commit. L'exécution passe par createRun. Déclarer un schedule fait automatiquement passer le workflow au moteur événementiel.
import { createWorkflow, createStep } from '@mastra/core/workflows'
import { z } from 'zod'
const parse = createStep({
id: 'parse',
inputSchema: z.object({ raw: z.string() }),
outputSchema: z.object({ items: z.array(z.string()) }),
execute: async ({ inputData }) => ({ items: inputData.raw.split('\n') })
})
const enrich = createStep({
id: 'enrich',
inputSchema: z.object({ items: z.array(z.string()) }),
outputSchema: z.object({ enriched: z.number() }),
execute: async ({ inputData }) => ({ enriched: inputData.items.length })
})
export const ingest = createWorkflow({
id: 'ingest',
inputSchema: z.object({ raw: z.string() }),
outputSchema: z.object({ enriched: z.number() })
})
.then(parse)
.then(enrich)
.commit()L'évaluation se trouve dans @mastra/evals 1.9.0, avec les sous-chemins ./scorers/prebuilt, ./scorers/utils et ./checks. Les scorers prêts à l'emploi comprennent createAnswerRelevancyScorer, createFaithfulnessScorer, createHallucinationScorer, createToxicityScorer, createBiasScorer, createContextPrecisionScorer, createToolCallAccuracyScorerCode et createTrajectoryAccuracyScorerLLM, entre autres. Vous construisez les vôtres avec createScorer et les champs id, description, judge, type et prepareRun, puis vous enchaînez preprocess, analyze, generateScore et generateReason.
import { createScorer } from '@mastra/core/evals'
import { createFaithfulnessScorer } from '@mastra/evals/scorers/prebuilt'
import { z } from 'zod'
const hasInvoiceNumber = createScorer({
id: 'has-invoice-number',
description: 'Checks whether the answer contains the invoice number',
type: { input: z.object({ number: z.string() }), output: z.string() }
})
.analyze(({ run }) => ({ found: run.output.includes(run.input.number) }))
.generateScore(({ results }) => (results.analyze.found ? 1 : 0))
.generateReason(({ results }) =>
results.analyze.found ? 'Number present' : 'No number in the answer'
)
const faithfulness = createFaithfulnessScorer({ model: 'openai/gpt-5-mini' })Les résultats des scorers atterrissent dans le même stockage que les exécutions, donc le panneau les affiche à côté des traces d'exécution. Si vous collectez déjà des métriques dans Langfuse ou Braintrust, des paquets de liaison séparés existent pour les deux.
Studio, stockage des exécutions et plateforme payante
La commande mastra dev lance le studio local sur le port 4111, sauf si la variable PORT dit autre chose. L'interface est incluse dans le paquet mastra sous dist/studio, donc vous ne l'installez pas séparément. Les builds vont dans .mastra/output.
La question clé est de savoir où atterrissent les exécutions et la mémoire quand vous ne configurez rien. La réponse est sans ambiguïté et visible dans le code : le constructeur Mastra examine le champ storage et, s'il est absent, crée un InMemoryStore et met en file un avertissement qui dit :
No `storage` configured on Mastra, falling back to an in-memory store. In-memory
storage is not durable: all data is lost on restart, and it is not safe for
production. Configure a persistent storage adapter (e.g. @mastra/libsql,
@mastra/pg, @mastra/cloudflare).Par défaut, il n'y a donc aucun fichier SQLite et rien d'autre sur le disque. Tout vit dans la mémoire du processus et disparaît au redémarrage. Le panneau est un outil de développement ; pour que quoi que ce soit survive à un déploiement, vous devez attacher un adaptateur et exécuter une base de données, ce qui est une pièce mobile de plus dans l'architecture.
L'offre payante se divise en deux voies. La variante auto-hébergée est gratuite sous Apache 2.0, et le complément Enterprise payant couvre RBAC, SSO, IAM et politique réseau, pour un seul tarif annuel forfaitaire sans comptage par trace. Ce sont précisément les fonctionnalités qui se trouvent sous ee/ dans le dépôt. La deuxième voie est la Mastra Platform hébergée.
| Élément | Starter | Teams |
|---|---|---|
| Prix mensuel | 0 USD | 250 USD |
| Événements d'observabilité | 100 k, puis 10 USD/100 k | 1 M, puis 8 USD/100 k |
| Temps CPU | 24 h, puis 0,35 USD/h | 250 h, puis 0,25 USD/h |
| Rétention des données | 15 jours | 6 mois |
| Sortie de données | 10 Go, puis 0,10 USD/Go | 100 Go, puis 0,10 USD/Go |
| Stockage de récupération | 250 Mo, puis 20 USD/Go | 1 Go, puis 20 USD/Go |
| Tokens de passerelle | tarif du marché + 5,5 % | tarif du marché + 5,5 % |
La page des tarifs est rendue côté serveur, donc on peut la lire sans exécuter JavaScript. Deux éléments y ressortent. Premièrement, la ligne LibSQL est intitulée « Rows Written » mais facture le dépassement à 2,50 USD par million de lectures sur Starter et 2 USD sur Teams ; les écritures et les lectures sont deux choses différentes et le tableau se contredit. Deuxièmement, le complément CPU de la formule Enterprise est annoncé à 0,00008 USD par seconde, ce qui revient à 0,288 USD par heure, un chiffre situé entre les tarifs des deux formules moins chères.
Le point d'équilibre vaut aussi la peine d'être calculé. En ne comptant que la ligne d'observabilité, Starter facture 10 USD par 100 k événements au-delà des premiers 100 k, tandis que Teams facture 250 USD plus 8 USD par 100 k au-delà d'un million. Les deux se rejoignent à 9 millions d'événements par mois, où les deux reviennent à 890 USD. En dessous de ce seuil, vous achetez Teams pour la rétention, le SSO et l'enveloppe CPU, pas pour des événements moins chers.
Mastra face aux autres frameworks d'agents
Le principal argument en faveur de Mastra est simple : c'est une bibliothèque écrite en TypeScript pour TypeScript, pas un portage depuis Python. Cet argument doit cependant être formulé honnêtement, car la version qui dit « la concurrence n'a rien en JavaScript » ne tient plus.
| Framework | Langage d'origine | Équivalent npm | État du portage |
|---|---|---|---|
| Mastra | TypeScript | @mastra/core 1.61.0 | la seule implémentation |
| LangGraph | Python | @langchain/langgraph 1.4.12 | actif, en avance sur le numéro Python |
| OpenAI Agents SDK | Python | @openai/agents 0.17.0 | actif, encore sur la ligne 0.x |
| PydanticAI | Python | aucun | pas de portage |
| CrewAI | Python | seulement le crewai 1.0.1 non officiel | mort depuis août 2024 |
| LangChain Agents | Python | @langchain/core 1.2.9 | actif |
Le portage JavaScript de LangGraph est sorti le 19 août 2026, trois jours avant cette mesure, et son numéro de version est même supérieur au 1.2.11 de Python. L'affirmation sur les portages négligés se vérifie ailleurs : @instructor-ai/instructor s'est arrêté à 1.7.0 du 27 janvier 2025, PydanticAI n'a rien sur npm, et le paquet crewai sur npm est une implémentation privée issue du dépôt jaafarskafi1/crew-js, pas du code de l'équipe CrewAI.
Les différences tiennent moins à la disponibilité qu'au caractère. LangGraph décrit un graphe d'états et c'est son seul modèle. PydanticAI s'appuie sur une sortie typée par validation. CrewAI organise le travail autour de rôles dans une équipe. L'OpenAI Agents SDK est le plus pratique avec un seul fournisseur. Mastra couvre un spectre plus large : agent, workflow, mémoire, RAG, évaluation, panneau et déployeur dans un seul dépôt. Cette étendue est un avantage au départ et une charge en maintenance, car vous mettez tout à jour d'un coup et des versions tombent tous les trois jours.
L'entreprise derrière le projet est Kepler Software, Inc., fondée en octobre 2024 par des personnes précédemment impliquées dans Gatsby, dont Sam Bhagwat et Abhi Aiyer. Le site du projet annonce 27,4 k étoiles sur le dépôt. Dépendre d'une seule entreprise est un risque réel : c'est elle qui décide de ce qui va sous ee/, et la frontière entre la partie ouverte et la partie commerciale passe par des répertoires plutôt que par des paquets séparés.
Erreurs courantes
Lancer en production sans champ storage est la plus fréquente. L'application démarre, l'agent répond, et après un redémarrage de conteneur il n'y a plus de fils de conversation ni de traces d'exécution. L'avertissement va dans le journal et se manque facilement.
La deuxième est de traiter Apache-2.0 du registre npm comme la réponse complète à la question de la licence. L'exception pour les répertoires ee/ ne figure que dans LICENSE.md du dépôt, et le paquet ne contient aucun texte de licence.
La troisième est la plage de versions dans package.json. Avec 61 versions mineures en sept mois, écrire ^1.0.0 signifie que quelqu'un dans l'équipe tirera un cœur différent des autres. Figez une version exacte et relevez-la délibérément.
La quatrième est de copier d'anciens exemples. La signature de execute dans les outils est passée à la transmission directe de la donnée d'entrée, et le panneau a été renommé de playground en studio, tandis que le paquet @mastra/playground-ui existe toujours sous l'ancien nom en version 51.0.0.
La cinquième est de mélanger des adaptateurs avec un cœur ancien figé. Les planchers de dépendances peer diffèrent d'un paquet à l'autre, et @mastra/inngest ne s'installera pas avec un cœur antérieur à 1.58.0 même si le reste du projet fonctionne. Si vous avez besoin d'exécutions durables et de longue durée, envisagez plutôt la passerelle vers Inngest ou Temporal, qui ont tous deux des paquets dédiés.
FAQ
Mastra est-il entièrement open source ?
Pas entièrement. Le code en dehors des répertoires nommés ee/ est sous Apache 2.0. Le contenu des répertoires ee/, y compris packages/core/src/auth/ee/, relève d'une licence Enterprise Edition séparée qui autorise le développement et les tests mais subordonne l'usage en production à un accord écrit avec Kepler Software.
Où Mastra stocke-t-il la mémoire et les exécutions par défaut ?
Nulle part de durable. Sans champ storage, le constructeur crée un InMemoryStore et les données disparaissent au redémarrage du processus. Vous activez la durabilité avec un adaptateur, par exemple @mastra/libsql avec url: 'file:./mastra.db', @mastra/pg ou @mastra/cloudflare.
Le rythme des versions est-il un problème ?
Cela dépend de votre discipline. Soixante et une versions mineures en 213 jours, c'est une tous les trois jours et demi, et la ligne 1.x n'a aucune version dépréciée. Avec une version exacte figée et des mises à niveau délibérées, c'est gérable ; avec une plage ^, vous aurez des surprises entre les environnements.
En quoi Mastra diffère-t-il de LangGraph ?
LangGraph modélise un graphe d'états et dispose d'un portage JavaScript en version 1.4.12, sorti en même temps que celui de Python. Mastra couvre plus de couches à la fois, dont la mémoire, l'évaluation et un panneau local, et est écrit entièrement en TypeScript, donc il ne traduit pas des concepts d'un autre langage.
Combien coûte la Mastra Platform hébergée ?
La formule Starter est gratuite avec une limite de 100 k événements d'observabilité, 24 heures de CPU et 15 jours de rétention. La formule Teams coûte 250 USD par mois pour 1 million d'événements, 250 heures de CPU et six mois de rétention. Enterprise est sur devis.
Peut-on utiliser Mastra sans son serveur ?
Oui. Les agents et les workflows peuvent être appelés directement depuis le code de l'application. Les adaptateurs @mastra/next, @mastra/hono et @mastra/nestjs existent pour les exposer dans une application existante, pas pour lancer un processus séparé.
Sources : le dépôt mastra-ai/mastra, le paquet @mastra/core sur npm, les tarifs de Mastra.