> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt # 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](https://mastra.zisheng.pro/fr/docs/studio/overview). Depuis la racine de votre projet, démarrez Studio et le serveur de développement local avec [`mastra dev`](https://mastra.zisheng.pro/fr/reference/cli/mastra) : **npm**: ```bash npx mastra dev ``` **pnpm**: ```bash pnpm dlx mastra dev ``` **Yarn**: ```bash yarn dlx mastra dev ``` **Bun**: ```bash bun x mastra dev ``` Ouvrez Studio à l’adresse [`http://localhost:4111`](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`](http://localhost:4111/api) pour parcourir les ressources disponibles, puis connectez votre frontend au moyen du [client Mastra](https://mastra.zisheng.pro/fr/docs/server/mastra-client). 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](https://github.com/mastra-ai/skills) 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**: ```bash npx skills add mastra-ai/skills ``` **pnpm**: ```bash pnpm dlx skills add mastra-ai/skills ``` **Yarn**: ```bash yarn dlx skills add mastra-ai/skills ``` **Bun**: ```bash bun x skills add mastra-ai/skills ``` Mettez régulièrement la compétence à jour pour bénéficier des dernières recommandations : **npm**: ```bash npx skills update mastra ``` **pnpm**: ```bash pnpm dlx skills update mastra ``` **Yarn**: ```bash yarn dlx skills update mastra ``` **Bun**: ```bash bun x skills update mastra ``` > **Remarque:** Lorsque vous créez un projet avec [create mastra](https://mastra.zisheng.pro/fr/docs), 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`](https://mastra.zisheng.pro/fr/reference/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 : ```bash 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](#mastra-skill) 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 : ```text 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](https://mastra.zisheng.pro/fr/reference/project-structure) 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](https://www.youtube.com/watch?v=5Kfn-oYkJNg\&t=18s) Avec les Agents fondés sur des fichiers, Mastra [découvre](https://mastra.zisheng.pro/fr/reference/file-based-agents/config) 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`](https://mastra.zisheng.pro/fr/reference/core/mastra-class). 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 : ```text 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`. ```typescript import { agentConfig } from '@mastra/core/agent' export default agentConfig({ model: 'openai/gpt-5.6-sol', }) ``` ```markdown 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/.ts`](https://mastra.zisheng.pro/fr/reference/file-based-agents/tools) | Fonctions que le modèle peut appeler | | [`skills/.md`](https://mastra.zisheng.pro/fr/reference/file-based-agents/skills) | Instructions détaillées chargées par l’Agent lorsqu’elles sont pertinentes | | [`memory.ts`](https://mastra.zisheng.pro/fr/reference/file-based-agents/memory) | Historique de conversation et contexte de travail | | [`workspace.ts` et `workspace/`](https://mastra.zisheng.pro/fr/reference/file-based-agents/workspace) | Accès au système de fichiers et au shell | | [`subagents//`](https://mastra.zisheng.pro/fr/reference/file-based-agents/subagents) | 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](https://mastra.zisheng.pro/fr/reference/file-based-agents/config) pour découvrir toutes les conventions de fichiers et options de configuration prises en charge.