Mastra : Guide du framework d'agents IA TypeScript 2026

Pendant deux ans, construire des agents IA en TypeScript revenait à choisir entre deux options peu séduisantes : envelopper LangChain.js dans du code défensif et prier, ou assembler une demi-douzaine de bibliothèques — magasin vectoriel, gestionnaire de prompts, harnais d'évaluation, télémétrie, moteur de workflow — en un pipeline fragile. Mastra s'est imposé comme la troisième option, et en 2026 il est discrètement devenu le point de départ par défaut des applications IA en production dans l'écosystème TypeScript.

Ce guide explique ce qu'est Mastra, pourquoi il a délogé les acteurs en place chez tant d'équipes, et comment évaluer s'il convient à votre stack.

Qu'est-ce que Mastra ?

Mastra est un framework open-source d'ingénierie IA écrit en TypeScript, par l'équipe à l'origine de Gatsby. Il est opiniâtre sur les primitives nécessaires pour livrer un vrai produit IA : agents, workflows, outils, RAG, mémoire, évaluations et télémétrie — le tout dans une surface API cohérente, tout typé nativement.

La promesse est simple. Au lieu de coudre ensemble six bibliothèques aux abstractions incompatibles, vous obtenez un framework unique qui gère le cycle de vie complet : de l'agent à prompt unique au workflow durable multi-étapes avec récupération, évaluation en CI, et traces OpenTelemetry qui alimentent votre pile d'observabilité.

Il se déploie partout où Node ou un runtime serverless tourne — Vercel, Cloudflare Workers, Render, votre propre cluster Kubernetes — et ne vous enferme pas chez un fournisseur de modèle.

Les cinq primitives de production

1. Les agents

Les agents sont au cœur de Mastra. Un agent possède un modèle, un prompt système, un ensemble d'outils, une mémoire optionnelle, et une sortie structurée optionnelle. Vous le définissez une fois, puis l'appelez depuis n'importe quelle route, file d'attente ou workflow.

import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
 
export const supportAgent = new Agent({
  name: "support",
  instructions: "Aider les clients à résoudre les problèmes de facturation.",
  model: openai("gpt-4o"),
  tools: { lookupInvoice, refundOrder },
});

Voilà la définition complète d'un agent. Mémoire et RAG s'enfichent via le même constructeur. L'agent est typé de bout en bout — entrées d'outils, sorties et réponses structurées passent toutes par l'inférence TypeScript, donc les refactorings ne cassent pas silencieusement le comportement.

2. Les workflows

Les workflows sont basés sur des graphes, durables et reprenables. Vous décrivez les étapes, les branches et la parallélisation de manière déclarative, et Mastra gère les retries, la suspension et la replay. C'est là que Mastra dépasse le plus clairement LangChain.js : le moteur de workflow est conçu pour la fiabilité, pas seulement pour l'expressivité.

Un schéma classique consiste à utiliser un agent dans une étape, puis à acheminer le résultat vers une étape déterministe. Par exemple, un agent classe un email entrant, puis une étape déterministe écrit en base et déclenche une notification. Si l'écriture en base échoue, le workflow reprend à l'étape échouée plutôt que de relancer l'appel LLM et de brûler des tokens.

3. Les outils

Les outils sont des fonctions typées que l'agent peut appeler. Mastra utilise les schémas Zod pour les entrées et sorties, ce qui donne à votre agent une surface d'appel structurée et validée, et à votre éditeur l'autocomplétion sur chaque paramètre. Le même outil peut être réutilisé entre plusieurs agents ou workflows sans redéclarer le schéma.

4. RAG et mémoire

Mastra livre des adaptateurs de première classe pour les principaux magasins vectoriels — Pinecone, Qdrant, pgvector, Chroma, Turso — et pour les backends de mémoire dont Postgres et Upstash. Vous pouvez brancher recherche sémantique, historique de conversation et mémoire de travail sans quitter le framework. Embeddings, chunking et récupération sont de première classe, pas des ajouts de dernière minute.

5. Les évaluations

C'est la fonctionnalité qui convainc les responsables d'ingénierie. Mastra traite l'évaluation comme du code : vous écrivez des suites d'évaluations comme vous écrivez des tests, vous les exécutez en CI, et vous bloquez les déploiements selon des métriques comme la fidélité, la pertinence des réponses et la toxicité. La plupart des équipes découvrent que leurs prompts régressent silencieusement en production. Mastra rend cette régression visible avant le merge.

Pourquoi les équipes quittent LangChain.js

Trois raisons reviennent dans les retours de migration :

1. La sécurité de typage fonctionne réellement. LangChain.js laisse fuiter des types any dans toute la chaîne d'appel. Mastra est typé de bout en bout, donc les refactorings ne cassent pas silencieusement les agents.
2. Une seule API opiniâtre. Plus besoin de choisir entre quatre abstractions de mémoire. Mastra impose des défauts qui marchent en prod.
3. Les primitives de production sont intégrées. Workflows durables, traces OpenTelemetry, harnais d'évaluation et adaptateurs de déploiement ne sont pas des add-ons tiers.

Il y a aussi une raison moins technique : la documentation de Mastra se lit comme écrite par des gens qui ont réellement livré des agents, pas par des gens qui génèrent une documentation de référence à partir de commentaires JSDoc. Cela seul fait gagner des jours d'essais et erreurs.

Quand Mastra est le bon choix

Mastra est un excellent choix lorsque vous :

• Construisez un produit multi-agents ou multi-étapes, pas un prompt ponctuel
• Travaillez dans une base de code TypeScript où la sécurité de typage compte
• Déployez sur Node ou des runtimes serverless modernes
• Intégrez récupération, mémoire ou usage d'outils au-delà du simple chat
• Devez livrer évaluations et observabilité pour la conformité ou la qualité

C'est surdimensionné si vous n'avez besoin que d'une complétion de chat unique derrière un bouton. Pour cela, l'AI SDK seul suffit.

Un exemple réaliste

Imaginez un copilote de support interne qui trie les tickets entrants. Avec Mastra, vous composez :

• Un agent qui lit le ticket, classe l'urgence et rédige une réponse
• Un workflow qui exécute l'agent, ramifie vers une étape de récupération depuis la base de connaissances, puis répond automatiquement ou route vers un humain
• Une suite d'évaluations qui note 200 tickets historiques chaque nuit pour repérer les régressions de qualité
• Des traces OpenTelemetry qui alimentent votre pile d'observabilité existante

La plupart des équipes mettent tout cela en production en deux sprints. Le même périmètre sur une stack faite main prend généralement un trimestre.

Considérations de production

Quelques points à anticiper avant la mise en production :

• Télémétrie des coûts. Les coûts de tokens montent vite. Utilisez le tracing intégré pour attribuer la dépense aux fonctionnalités, pas seulement aux totaux.
• Couverture d'évaluation. Traitez les suites d'évaluations comme des tests. Visez d'abord la couverture des modes d'échec les plus coûteux.
• Versioning des workflows. Les workflows durables en production ont besoin d'un chemin de migration clair quand vous changez la forme des étapes. Anticipez-le.
• Portabilité des fournisseurs. Le framework est neutre, mais le comportement des modèles ne l'est pas. Quand vous passez de Claude à GPT ou inversement, lancez d'abord votre suite d'évaluations.

En résumé

Mastra est devenu le framework IA TypeScript par défaut pour la même raison que Next.js est devenu le framework React par défaut : il regroupe les primitives de production ennuyeuses et difficiles à maîtriser, pour que les équipes consacrent leur temps au produit. Si votre équipe a dépassé le stade du prototype et livre des fonctionnalités IA dans une vraie base de code, Mastra est aujourd'hui le point de départ le plus défendable en TypeScript.

Pour les organisations de la région MENA qui construisent des produits IA avec des talents TypeScript locaux, Mastra offre un autre avantage sous-estimé : la documentation, les types et les patterns sont assez explicites pour que les équipes montent en compétence sans expertise LLM préalable. Cette accessibilité, combinée à la possibilité de déployer sur n'importe quel cloud — y compris une infrastructure souveraine — en fait un choix particulièrement adapté aux équipes d'ingénierie IA en pleine croissance dans la région.

Si vous construisez des produits IA et souhaitez de l'aide pour concevoir la bonne architecture, choisir le bon framework, ou livrer des agents de niveau production, contactez notre équipe.