Développer

Une fois votre projet Mastra créé, vous pouvez développer, exécuter et tester votre Agent.

Exécuter Mastra localement

Le moyen le plus rapide d’observer votre Agent en fonctionnement consiste à utiliser Mastra Studio. Depuis la racine de votre projet, démarrez Studio et le serveur de développement local avec mastra dev :

npm

npx mastra dev

pnpm

pnpm dlx mastra dev

Yarn

yarn dlx mastra dev

Bun

bun x mastra dev

Ouvrez Studio à l’adresse http://localhost:4111 pour tester votre Agent et examiner ses exécutions.

Le serveur de développement expose également des API pour vos Agents, Tools et Workflows. Ouvrez http://localhost:4111/api pour parcourir les ressources disponibles, puis connectez votre frontend au moyen du client Mastra.

Les modifications apportées à votre répertoire src/mastra/ redémarrent automatiquement le serveur de développement ; vous n’avez donc pas à le redémarrer manuellement pendant votre travail.

Créer avec l’IA

Mastra fournit une compétence et une CLI pour aider votre Agent de programmation à écrire du code Mastra de qualité.

Compétence Mastra

Les modèles d’IA ne connaissent pas nécessairement les dernières versions des API Mastra. Utilisez la compétence Mastra afin de fournir à votre Agent de programmation des conseils d’implémentation, des bonnes pratiques et des instructions pour récupérer la documentation Mastra la plus récente.

Installez manuellement la compétence avec :

npm

npx skills add mastra-ai/skills

pnpm

pnpm dlx skills add mastra-ai/skills

Yarn

yarn dlx skills add mastra-ai/skills

Bun

bun x skills add mastra-ai/skills

Mettez régulièrement la compétence à jour pour bénéficier des dernières recommandations :

npm

npx skills update mastra

pnpm

pnpm dlx skills update mastra

Yarn

yarn dlx skills update mastra

Bun

bun x skills update mastra

remarque

Lorsque vous créez un projet avec create mastra, la commande installe automatiquement la compétence Mastra afin que votre Agent de programmation puisse la découvrir et l’utiliser.

Mastra CLI

Utilisez la CLI mastra pour offrir à votre Agent de programmation une boucle de rétroaction lui permettant de tester les mises à jour et d’examiner les résultats. La CLI lui donne accès aux Agents, Workflows, Tools, à la Memory, aux évaluations, aux traces et aux journaux.

Par exemple, votre Agent de programmation peut exécuter un Agent, puis récupérer les traces afin d’examiner les résultats :

npx mastra api --url http://localhost:4111 agent run agent '{"messages":"Hello"}'
npx mastra api --url http://localhost:4111 trace list

N’oubliez pas d’installer la compétence Mastra pour apprendre à votre Agent de programmation à utiliser la CLI.

Structure du projet

L’une des premières décisions à prendre lorsque vous adoptez un framework concerne la structure du projet. Nous vous recommandons de conserver le code du framework sous src/mastra/ et de regrouper les primitives associées dans leurs propres fichiers ou dossiers. Utilisez src/mastra/index.ts comme emplacement central pour les configurer et les enregistrer.

Un projet minimal peut présenter la structure suivante :

src/
  mastra/
    agents/
      agent.ts
    tools/
      tool.ts
    workflows/
      workflow.ts
    scorers/
      scorer.ts
    skills.ts
    index.ts

Consultez la référence de la structure des projets pour découvrir l’organisation par défaut et les conventions recommandées.

Agents fondés sur des fichiers

beta

Les Agents fondés sur des fichiers sont en bêta et peuvent évoluer avant leur stabilisation.

La découverte fondée sur des fichiers s’exécute uniquement via mastra dev ou mastra build. Si votre application importe directement mastra, y compris par l’intermédiaire d’un framework web ou d’un adaptateur de serveur, les Agents fondés sur des fichiers ne sont pas découverts. Enregistrez-les dans le code ou exécutez Mastra comme serveur distinct.

📹 Regarder

Créer votre premier Agent fondé sur des fichiers

Avec les Agents fondés sur des fichiers, Mastra découvre automatiquement les Agents et les primitives associées depuis les fichiers pris en charge sous src/mastra/. Vous organisez ces fichiers par convention au lieu d’importer et d’enregistrer chaque primitive sur votre instance Mastra.

Le système de fichiers devient une représentation directe de la structure de votre projet. Votre Agent de programmation et vous pouvez ainsi comprendre son organisation sans devoir retracer toutes les connexions dans le code.

Vous pouvez utiliser des Agents fondés sur des fichiers dans tout votre projet ou les adopter progressivement aux côtés de primitives définies dans le code. Toutes les fonctionnalités et tous les cas d’usage de Mastra ne sont pas encore pris en charge.

Créer votre premier Agent

Un Agent fondé sur des fichiers réside dans son propre répertoire sous src/mastra/agents/. Pour créer un Agent fonctionnel, ajoutez un fichier config.ts pour son modèle et ses options d’exécution, ainsi qu’un fichier instructions.md pour ses instructions permanentes :

src/mastra/agents/
  writing-assistant/
    config.ts
    instructions.md

Le nom du répertoire devient l’id et le name par défaut de l’Agent. Dans cet exemple, Mastra enregistre l’Agent sous le nom writing-assistant.

src/mastra/agents/writing-assistant/config.ts

import { agentConfig } from '@mastra/core/agent'

export default agentConfig({
  model: 'openai/gpt-5.6-sol',
})

src/mastra/agents/writing-assistant/instructions.md

Rewrite text clearly and concisely.

Exécutez npx mastra dev, ouvrez Studio et sélectionnez writing-assistant pour le tester.

Fonctionnement de la découverte

Mastra utilise les chemins pour découvrir et nommer les fonctionnalités fondées sur des fichiers. Le répertoire d’un Agent fournit son id et son name par défaut. Par exemple, tools/search_docs.ts enregistre un Tool sous le nom search_docs, tandis que skills/style-guide.md enregistre une compétence sous le nom style-guide. Consultez les chemins d’extension ci-dessous.

Étendre votre Agent

Ajoutez des fichiers ou des répertoires lorsque votre Agent a besoin de fonctionnalités supplémentaires :

Chemin	Élément ajouté
tools/<tool-name>.ts	Fonctions que le modèle peut appeler
skills/<skill-name>.md	Instructions détaillées chargées par l’Agent lorsqu’elles sont pertinentes
memory.ts	Historique de conversation et contexte de travail
workspace.ts et workspace/	Accès au système de fichiers et au shell
subagents/<agent-id>/	Agents spécialisés auxquels l’Agent parent peut déléguer

Conservez chaque fonctionnalité à proximité de l’Agent qui l’utilise. Mastra découvre et enregistre ces fichiers au démarrage ou au redémarrage du serveur de développement.

Consultez la référence des Agents fondés sur des fichiers pour découvrir toutes les conventions de fichiers et options de configuration prises en charge.