Premiers pas

Mastra est un framework TypeScript permettant de créer des agents et des applications IA. Créez votre premier agent avec une seule commande, puis commencez à développer.

Pour les agents IA : si vous devez créer un projet Mastra à partir de zéro, suivez les instructions condensées jusqu’au prochain titre. Adaptez l’exemple de code de l’agent et du tool à vos besoins. Important pour la suite : définissez model comme une chaîne au format provider/model, par exemple openai/gpt-5.6-sol. Pour OpenAI, utilisez openai/<model>, et non openai:<model>, et n’importez ni ne transmettez un objet provider.

Créez un fichier package.json avec { "type": "module" }. Installez les dépendances requises : npm install @mastra/core@latest zod@latest typescript@latest @types/node@latest mastra@latest

Créez un fichier tsconfig.json :

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "outDir": "dist"
  },
  "include": ["src/**/*"]
}

Si vous devez ajouter un tool à l’agent, créez un nouveau fichier et utilisez import { createTool } from "@mastra/core/tools". Les définitions de tool sous forme d’objet brut échouent silencieusement à l’exécution ; les tools DOIVENT être définis avec createTool() et id, description, inputSchema (zod), execute(). execute() reçoit deux paramètres : les données d’entrée validées par inputSchema, en premier paramètre, et un objet facultatif de contexte d’exécution, en second paramètre, contenant requestContext, tracingContext, abortSignal et d’autres métadonnées d’exécution.

Exemple :

// src/mastra/tools/weather-tool.ts
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const weatherTool = createTool({
  id: 'get-weather',
  description: 'Get current weather for a location',
  inputSchema: z.object({
    location: z.string().describe('City name'),
  }),
  outputSchema: z.object({
    location: z.string(),
    temperatureCelsius: z.number(),
    conditions: z.string(),
  }),
  execute: async ({ location }) => {
    return {
      location,
      temperatureCelsius: 21,
      conditions: 'sunny',
    }
  },
})

Si vous devez créer un agent, créez un nouveau fichier et utilisez import { Agent } from "@mastra/core/agent". Le constructeur reçoit { id, name, instructions, model }. La propriété model est une chaîne au format du routeur de modèles Mastra. Aucun import de provider n’est nécessaire pour ce format. N’installez aucun package AI SDK sauf indication contraire de la documentation Mastra.

En définissant le modèle au format provider/model, Mastra recherche automatiquement les variables d’environnement du provider. Le modèle défini exige qu’une variable d’environnement soit configurée pour ce provider. OpenAI : OPENAI_API_KEY. Anthropic : ANTHROPIC_API_KEY. Google : GOOGLE_API_KEY. Par exemple, tout openai/<model> requiert la variable d’environnement OPENAI_API_KEY. Consultez https://mastra.ai/models/environment-variables pour la liste complète des providers pris en charge et le nom de leurs variables d’environnement.

Voici une courte liste des ID de modèles connus :

• openai/gpt-5.6-sol, openai/gpt-5-mini
• anthropic/claude-sonnet-4-6, anthropic/claude-opus-4-7, anthropic/claude-haiku-4-5
• google/gemini-2.5-flash

Consultez https://mastra.ai/models pour la liste complète des modèles pris en charge.

Ajoutez un tool à un agent en important le tool et en le transmettant au constructeur de l’agent sous forme d’objet tools.

Exemple :

// src/mastra/agents/weather-agent.ts
import { Agent } from '@mastra/core/agent'
import { weatherTool } from '../tools/weather-tool.ts'

export const weatherAgent = new Agent({
  id: 'weather-agent',
  name: 'Weather Agent',
  instructions: `
      You are a helpful weather assistant that provides accurate weather information.

      Your primary function is to help users get weather details for specific locations. When responding:
      - Include relevant details like humidity, wind conditions, and precipitation
      - Keep responses concise but informative

      Use the weatherTool to fetch current weather data.
`,
  // Use a string in provider/model format, not provider:model or a provider object.
  model: 'openai/gpt-5.6-sol',
  tools: { weatherTool },
})

Créez un point d’entrée Mastra dans src/mastra/index.ts et enregistrez l’agent :

import { Mastra } from '@mastra/core'
import { weatherAgent } from './agents/weather-agent.ts'

export const mastra = new Mastra({
  agents: { weatherAgent },
})

Vous pouvez maintenant exécuter l’agent directement. Pour cela, importez l’instance Mastra et appelez agent.generate() après avoir récupéré l’agent par son ID. Node.js 22.18.0 et les versions ultérieures peuvent exécuter directement des fichiers TypeScript. Veillez à ajouter les extensions de fichier lors de l’import de fichiers locaux. Exemple :

// run.mjs
import { mastra } from './src/mastra/index.ts'

const agent = mastra.getAgentById('weather-agent')
const response = await agent.generate('Weather in SF')
console.log(response.text)

Démarrage rapide

Exécutez cette commande pour créer une structure d’agent généraliste dotée d’un espace de travail local, d’outils shell, de mémoire, de suivi des tâches, d’un accès au web et de planifications récurrentes. Elle installe également des skills Mastra pour votre agent de codage installé afin que vous puissiez commencer à lui donner des instructions et à le modifier :

npm

npm create mastra@latest

pnpm

pnpm create mastra@latest

Yarn

yarn create mastra

Bun

bunx create-mastra

Vous pouvez ouvrir immédiatement Studio, une interface utilisateur interactive pour votre projet Mastra. Consultez le guide de démarrage rapide pour une présentation complète.

Intégrer Mastra à votre framework

Ajoutez Mastra à un projet existant ou créez une application avec votre framework préféré :

Next.js

React

Astro

Express

SvelteKit

Hono

Pour les autres frameworks, consultez les guides d’intégration aux frameworks.

Modèles

Parcourez les modèles pour trouver des projets Mastra complets que vous pouvez cloner et adapter.

Cas d’utilisation

Intégrer des agents à votre produit

Ajoutez des capacités d’IA à votre plateforme afin que vos utilisateurs puissent créer des agents ou interagir avec eux.

Utilisé par Replit, Fireworks, Medusa

Assistants destinés aux clients

Créez des agents qui traitent les demandes, planifient des rendez-vous, envoient des rappels et répondent aux questions par chat, WhatsApp ou par la voix.

Utilisé par Vetnio, Lua

Modèles : Chatbot de documentation, Agent Slack

Assistants internes

Aidez vos employés à travailler plus vite avec une IA qui comprend votre domaine, par exemple pour les demandes RH, la documentation clinique, la préparation commerciale ou la génération de documents.

Utilisé par Factorial, Counsel Health, Cedar, SoftBank

Modèles : Discuter avec un PDF, Analyse Google Sheets

Agents d’analyse de données

Permettez aux utilisateurs d’interroger des bases de données et des tableaux de bord en langage naturel. Connectez-vous à vos sources de données et renvoyez des réponses, des graphiques ou des rapports.

Utilisé par Index, PLAID Japan

Modèles : Discuter avec une base de données, Du CSV aux questions

Automatisation de contenu

Générez, transformez et gérez du contenu structuré à grande échelle pour un système de gestion de contenu, une base de connaissances ou un système de documentation.

Utilisé par Sanity

Modèles : Discuter avec YouTube, Fiches à partir d’un PDF

Automatisation DevOps et ingénierie

Automatisez les déploiements, résolvez les problèmes de production, gérez l’infrastructure et traitez les workflows d’astreinte.

Utilisé par StarSling

Modèles : Revue de code de PR GitHub, Agent de navigateur

Workflows de vente et de mise sur le marché

Transformez les conversations avec les clients en tâches structurées, générez des notes d’investissement ou automatisez des séquences de prospection.

Utilisé par Kestral, Orange Collective, WorkOS

Modèles : Synthèse des retours clients

Vidéo

Une visite rapide de la plateforme Mastra montre comment les éléments s’articulent.