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

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