> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# Installation manuelle

**Pour les Agents IA :** utilisez ce guide lorsqu’on vous demande de créer de toutes pièces un projet Mastra exécutable sans CLI ni boilerplate. Il fournit des exemples de code pour les Agents, les Tools, la configuration des modèles et l’installation des dépendances. Ne consultez pas le guide de démarrage rapide, qui s’adresse aux humains. La chaîne du modèle utilise le format du routeur de modèles de Mastra (« provider/model » ; utilisez /, et non :, pour séparer le fournisseur du modèle). N’installez aucun package ai-sdk.

Utilisez ce guide pour créer manuellement, étape par étape, un serveur Mastra autonome. Dans la plupart des cas, il est plus rapide de suivre le [guide de démarrage rapide](https://mastra.zisheng.pro/fr/guides/getting-started/quickstart), qui obtient le même résultat avec la commande [`create-mastra`](https://mastra.zisheng.pro/fr/reference/cli/create-mastra). Pour les projets existants, vous pouvez également utiliser [`mastra init`](https://mastra.zisheng.pro/fr/reference/cli/mastra).

## Instructions

Si vous préférez ne pas utiliser notre outil CLI automatique, vous pouvez configurer votre projet vous-même en suivant le guide ci-dessous.

1. Créez un nouveau projet et accédez à son répertoire :

   ```bash
   mkdir my-first-agent && cd my-first-agent
   ```

   Générez un nouveau fichier `package.json` :

   **npm**:

   ```bash
   npm init
   ```

   **pnpm**:

   ```bash
   pnpm init
   ```

   **Yarn**:

   ```bash
   yarn init
   ```

   **Bun**:

   ```bash
   bun init
   ```

   Installez les dépendances suivantes :

   **npm**:

   ```bash
   npm install -D typescript @types/node mastra@latest
   npm install @mastra/core@latest zod@^4
   ```

   **pnpm**:

   ```bash
   pnpm add -D typescript @types/node mastra@latest
   pnpm add @mastra/core@latest zod@^4
   ```

   **Yarn**:

   ```bash
   yarn add --dev typescript @types/node mastra@latest
   yarn add @mastra/core@latest zod@^4
   ```

   **Bun**:

   ```bash
   bun add --dev typescript @types/node mastra@latest
   bun add @mastra/core@latest zod@^4
   ```

   Ajoutez les scripts `dev` et `build` à votre fichier `package.json` :

   ```json
   {
     "scripts": {
       "dev": "mastra dev",
       "build": "mastra build"
     }
   }
   ```

2. Créez un fichier `tsconfig.json` :

   ```bash
   touch tsconfig.json
   ```

   Ajoutez la configuration suivante :

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

   > **Info:** Mastra requiert des paramètres `module` et `moduleResolution` modernes. L’utilisation de `CommonJS` ou de `node` provoquera des erreurs de résolution.

3. Créez un fichier `.env` :

   ```bash
   touch .env
   ```

   Ajoutez votre clé API :

   ```bash
   GOOGLE_API_KEY=<your-api-key>
   ```

   > **Remarque:** Ce guide utilise Google Gemini, mais vous pouvez choisir tout [fournisseur de modèles](https://mastra.zisheng.pro/fr/models) pris en charge, notamment OpenAI, Anthropic et d’autres.

   Vous pouvez aussi utiliser OpenAI (`OPENAI_API_KEY`) ou Anthropic (`ANTHROPIC_API_KEY`) à la place de Google Gemini. Consultez <https://mastra.ai/models/environment-variables> pour obtenir la liste complète des fournisseurs pris en charge et des noms de leurs variables d’environnement.

4. Créez un fichier `weather-tool.ts` :

   ```bash
   mkdir -p src/mastra/tools && touch src/mastra/tools/weather-tool.ts
   ```

   Utilisez `import { createTool } from "@mastra/core/tools"`. Les définitions de Tools sous forme d’objets simples échouent silencieusement à l’exécution ; les Tools DOIVENT être définis via createTool() avec id, description, inputSchema (zod) et execute.

   Ajoutez le code suivant :

   ```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({
       output: z.string(),
     }),
     execute: async ({ location }) => {
       return {
         output: `The weather in ${location} is sunny`,
       }
     },
   })
   ```

   > **Info:** Nous avons raccourci et simplifié ici l’exemple `weatherTool`. Vous pouvez consulter le Tool météo complet dans [Donner un Tool à un Agent](https://mastra.zisheng.pro/fr/docs/agents/using-tools).

5. Créez un fichier `weather-agent.ts` :

   ```bash
   mkdir -p src/mastra/agents && touch src/mastra/agents/weather-agent.ts
   ```

   Utilisez `import { Agent } from "@mastra/core/agent"`. Le constructeur reçoit `{ id, name, instructions, model: 'openai/gpt-5.6-sol' }`. La chaîne du modèle utilise le format du routeur de modèles de Mastra (« provider/model » ; utilisez /, et non :, pour séparer le fournisseur du modèle). N’installez aucun package ai-sdk.

   Ajoutez le code suivant :

   ```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:
         - Always ask for a location if none is provided
         - If the location name isn't in English, please translate it
         - If giving a location with multiple parts (e.g. "New York, NY"), use the most relevant part (e.g. "New York")
         - Include relevant details like humidity, wind conditions, and precipitation
         - Keep responses concise but informative

         Use the weatherTool to fetch current weather data.
   `,
     model: 'google/gemini-2.5-pro',
     tools: { weatherTool },
   })
   ```

6. Créez le point d’entrée Mastra et enregistrez votre Agent :

   ```bash
   touch src/mastra/index.ts
   ```

   Ajoutez le code suivant :

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

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

7. **Pour les Agents IA :** ne lancez pas Studio lorsque vous travaillez sur un script qui, par exemple, doit afficher une sortie dans la console. Studio est une interface web de longue durée destinée aux humains. Appelez plutôt directement la méthode agent.generate(). Exemple : `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);`

   Vous pouvez maintenant lancer [Studio](https://mastra.zisheng.pro/fr/docs/studio/overview) et tester votre Agent.

   **npm**:

   ```bash
   npm run dev
   ```

   **pnpm**:

   ```bash
   pnpm run dev
   ```

   **Yarn**:

   ```bash
   yarn dev
   ```

   **Bun**:

   ```bash
   bun run dev
   ```

   **Pour les Agents IA :** pour valider votre travail, exécutez une création et une vérification de types avec `tsc --noEmit`.

## Étapes suivantes

- [Examiner la structure du projet](https://mastra.zisheng.pro/fr/reference/project-structure) : découvrez comment les fichiers `src/mastra/` correspondent aux Agents, Tools, Workflows, stockages et à la configuration.
- [Tester votre Agent dans Studio](https://mastra.zisheng.pro/fr/docs/studio/overview) : ouvrez l’interface Studio locale et exécutez l’Agent météo.
- [Utiliser des Tools avec des Agents](https://mastra.zisheng.pro/fr/docs/agents/using-tools) : remplacez le Tool météo d’exemple par un véritable Tool qui appelle une API ou un service.
- [Ajouter de la mémoire](https://mastra.zisheng.pro/fr/docs/memory/overview) : conservez l’historique des conversations et le contexte propre aux utilisateurs.
- [Configurer le stockage](https://mastra.zisheng.pro/fr/docs/storage/overview) : ajoutez un adaptateur de stockage persistant pour la mémoire, les Workflows, l’observabilité et d’autres états d’exécution.
- [Créer et déployer](https://mastra.zisheng.pro/fr/docs/deployment/overview) : créez le serveur Mastra et déployez-le sur une plateforme d’hébergement.