Guide Complet du Framework Mastra : L'Outil Puissant AI Agent pour les Développeurs TypeScript

---

title: Guide Complet du Framework Mastra : L'Outil Puissant AI Agent pour les Développeurs TypeScript date: 2026-04-01 authors: [kevinpeng] slug: mastra-typescript-ai-agent-framework-2026-fr categories: - Assistants IA tags: - Mastra - TypeScript - AI Agent - Framework Open Source - Outils Développeur cover: https://res.makeronsite.com/freeaitool.com/052-mastra-typescript-ai-agent-framework-2026-cover.webp description: Mastra est le framework AI Agent TypeScript le plus populaire en 2026, offrant des workflows, de la mémoire, RAG, l'évaluation et le traçage. Ce guide couvre l'installation, les concepts clés, les exemples pratiques et le déploiement en production. lang: fr

---

Pourquoi choisir Mastra ?

Si vous êtes un développeur TypeScript/JavaScript cherchant à atteindre la même productivité que les développeurs Python dans le développement d'applications IA, Mastra est le framework conçu pour vous.

Mastra est un framework AI Agent open-source natif TypeScript, soutenu par Y Combinator, conçu spécifiquement pour les développeurs web. Il fournit tous les primitifs nécessaires pour construire, tester et déployer des applications IA, vous permettant de passer rapidement de l'idée à la production.

Avantages principaux

• TypeScript Natif : Support complet des types et IntelliSense IDE
• Prêt pour la production : Workflows, mémoire, RAG, évaluation et traçage intégrés
• Expérience développeur : Playground interactif et débogage en temps réel
• Open Source et gratuit : Licence MIT, piloté par la communauté

Démarrage rapide

Installer Mastra

# Créer un nouveau projet
npx create-mastra@latest my-ai-app

# Entrer dans le répertoire du projet
cd my-ai-app

# Installer les dépendances
npm install

Structure du projet

my-ai-app/
├── src/
│   ├── mastra/
│   │   ├── agents/          # Définitions des agents
│   │   ├── tools/           # Outils personnalisés
│   │   ├── workflows/       # Workflows
│   │   └── index.ts         # Point d'entrée principal
│   └── index.ts
├── package.json
└── mastra.config.ts

Concepts fondamentaux

1. Créer un Agent

Les agents sont le bloc de construction principal de Mastra. Chaque agent a un rôle spécifique, des outils et une mémoire.

// src/mastra/agents/customer-support.ts
import { Agent } from '@mastra/core/agent';

export const customerSupportAgent = new Agent({
  name: 'Customer Support Agent',
  instructions: `
    Vous êtes un assistant de support client professionnel, chargé de répondre aux questions des utilisateurs sur les produits.
    - Maintenir un ton amical et professionnel
    - Fournir des informations précises
    - Si vous ne connaissez pas la réponse, dites-le honnêtement et suggérez de contacter le support humain
  `,
  model: {
    provider: 'ANTHROPIC',
    name: 'claude-sonnet-4-20250514',
  },
});

2. Créer des outils personnalisés

Les outils permettent aux agents d'effectuer des actions concrètes, comme interroger une base de données ou appeler une API.

// src/mastra/tools/order-lookup.ts
import { createTool } from '@mastra/core/tools';
import { z } from 'zod';

export const orderLookupTool = createTool({
  id: 'order-lookup',
  description: 'Consulter le statut d\'une commande par numéro',
  inputSchema: z.object({
    orderId: z.string().describe('Numéro de commande'),
  }),
  execute: async ({ context }) => {
    const { orderId } = context;

    // Simuler une requête en base de données
    const order = await db.orders.findUnique({
      where: { id: orderId },
    });

    return {
      status: order?.status || 'not_found',
      items: order?.items || [],
      total: order?.total || 0,
    };
  },
});

3. Lier des outils à un Agent

// src/mastra/agents/customer-support.ts
import { customerSupportAgent } from './customer-support';
import { orderLookupTool } from '../tools/order-lookup';

# Ajouter des outils
customerSupportAgent.addTools([orderLookupTool]);

4. Créer des Workflows

Les workflows vous permettent d'orchestrer plusieurs agents et outils pour implémenter des processus métier complexes.

// src/mastra/workflows/order-processing.ts
import { Workflow } from '@mastra/core/workflows';
import { agentStep } from '@mastra/core/step';

export const orderProcessingWorkflow = new Workflow({
  name: 'order-processing',
  triggerSchema: z.object({
    orderId: z.string(),
    customerEmail: z.string().email(),
  }),
});

// Définir les étapes
const checkOrder = agentStep({
  agent: customerSupportAgent,
  outputSchema: z.object({
    status: z.string(),
    canRefund: z.boolean(),
  }),
});

const sendEmail = agentStep({
  agent: emailAgent,
  outputSchema: z.object({
    sent: z.boolean(),
  }),
});

# Orchestrer le flux
orderProcessingWorkflow
  .step(checkOrder)
  .then(sendEmail, {
    when: { ref: checkOrder, path: 'canRefund', eq: true },
  });

Exemple pratique : Construire un bot de service client

Construisons un bot de service client complet capable de gérer les demandes de commande, les retours et les consultations produits.

Code complet

// src/mastra/index.ts
import { Mastra } from '@mastra/core/mastra';
import { customerSupportAgent } from './agents/customer-support';
import { orderLookupTool } from './tools/order-lookup';
import { refundTool } from './tools/refund';
import { orderProcessingWorkflow } from './workflows/order-processing';

export const mastra = new Mastra({
  agents: {
    'customer-support': customerSupportAgent,
  },
  tools: {
    'order-lookup': orderLookupTool,
    'refund': refundTool,
  },
  workflows: {
    'order-processing': orderProcessingWorkflow,
  },
});

Lancer le serveur de développement

# Lancer le serveur de développement Mastra (inclut le Playground)
npx mastra dev

Visitez http://localhost:4111 pour ouvrir le Playground interactif et tester vos agents en temps réel.

Appeler un Agent

// src/index.ts
import { mastra } from './mastra';

async function main() {
  const agent = mastra.getAgent('customer-support');

  const response = await agent.generate(
    'Mon numéro de commande est ORD-12345, veuillez vérifier le statut'
  );

  console.log(response.text);
}

main();

Fonctionnalités avancées

Système de mémoire

Mastra intègre la mémoire, permettant aux agents de se souvenir de l'historique des conversations.

import { Memory } from '@mastra/memory';

const memory = new Memory({
  storage: {
    type: 'postgres',
    connectionString: process.env.DATABASE_URL,
  },
});

const agent = new Agent({
  name: 'Support Agent',
  memory,
  // ...autre configuration
});

RAG (Génération Augmentée par Récupération)

import { RAG } from '@mastra/rag';

const rag = new RAG({
  vectorStore: {
    type: 'pinecone',
    apiKey: process.env.PINECONE_API_KEY,
  },
});

# Indexer des documents
await rag.index({
  documents: ['./docs/product-manual.pdf'],
  indexName: 'product-knowledge',
});

# Utiliser dans un agent
const agent = new Agent({
  name: 'Product Expert',
  rag: {
    indexes: ['product-knowledge'],
  },
});

Évaluation et traçage

import { Eval } from '@mastra/evals';

const eval = new Eval({
  name: 'response-quality',
  criteria: [
    { name: 'accuracy', weight: 0.4 },
    { name: 'helpfulness', weight: 0.3 },
    { name: 'tone', weight: 0.3 },
  ],
});

# Lancer l'évaluation
const results = await eval.evaluate(agent, testCases);
console.log(results.summary);

Déploiement en production

Déploiement sur Vercel

# Installer Vercel CLI
npm i -g vercel

# Déployer
vercel deploy --prod

Déploiement sur Docker

# Dockerfile
FROM node:20-alpine

WORKDIR /app
COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

EXPOSE 3000
CMD ["npm", "start"]

# Construire et exécuter
docker build -t my-mastra-app .
docker run -p 3000:3000 my-mastra-app

Conseils d'optimisation des performances

1. Utiliser les réponses en streaming : Pour la génération de textes longs, activer le streaming pour améliorer l'expérience utilisateur
2. Mettre en cache les résultats d'outils : Pour les outils fréquemment appelés, implémenter un cache de résultats
3. Traitement par lots : Pour plusieurs requêtes similaires, utiliser des appels API par lots
4. Surveiller la latence : Utiliser le traçage intégré de Mastra pour surveiller la durée de chaque étape

Comparaison avec d'autres frameworks

Caractéristique	Mastra	LangChain.js	Vercel AI SDK
TypeScript Natif	✅	⚠️	✅
Workflows intégrés	✅	✅	❌
Playground interactif	✅	❌	❌
Système de mémoire	✅	✅	⚠️
Support RAG	✅	✅	❌
Outils d'évaluation	✅	⚠️	❌
Courbe d'apprentissage	Moyenne	Raide	Douce

Résumé

Mastra est l'une des meilleures options pour les développeurs TypeScript qui souhaitent se lancer dans le développement d'AI Agents. Il offre :

• 🎯 API conviviale pour les développeurs : Typage sûr, support IntelliSense complet
• 🔧 Fonctionnalités intégrées riches : Workflows, mémoire, RAG, évaluation en un seul endroit
• 🚀 Prêt pour la production : Chaîne d'outils complète du développement au déploiement
• 📚 Excellente documentation : Tutoriels et exemples détaillés

Si vous travaillez déjà dans l'écosystème TypeScript et souhaitez construire rapidement des applications IA, Mastra vaut le coup d'œil.

Ressources

• Documentation officielle Mastra
• Repository GitHub
• Mastra Playground
• Projets d'exemple
• Discord communautaire

---

Lectures recommandées :

• Guide d'orchestration multi-agents LangGraph
• Kit de développement d'agents Google ADK
• Guide complet du framework PydanticAI