> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt # Présentation des Agents Les Agents utilisent des LLM et des Tools pour résoudre des tâches ouvertes. Ils raisonnent sur les objectifs et décident quels Tools utiliser. Ils conservent la mémoire des conversations et poursuivent leurs itérations jusqu’à ce que le modèle produise une réponse finale ou qu’une condition d’arrêt facultative soit remplie. Les Agents produisent des réponses structurées que vous pouvez afficher dans votre interface ou traiter par programmation. Utilisez-les directement ou composez-les au sein de Workflows ou de systèmes multi-Agent. **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/`, et non `openai:`, 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 : ```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 : ```ts // 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/` requiert la variable d’environnement `OPENAI_API_KEY`. Consultez 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 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 : ```ts // 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 : ```ts 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 : ```ts // 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) ``` ## Quand utiliser des Agents Utilisez des Agents lorsque la tâche est ouverte et que ses étapes ne sont pas connues à l’avance. Un Agent décide quels Tools appeler, combien d’itérations effectuer et quand s’arrêter. Vous fournissez l’objectif et les contraintes au lieu de définir chaque étape. Pour les processus prédéterminés à plusieurs étapes dotés d’un flux de contrôle explicite, utilisez plutôt des [Workflows](https://mastra.zisheng.pro/fr/docs/workflows/overview). > **📹 Regarder:** Regardez le [démarrage rapide des Agents Mastra](https://www.youtube.com/watch?v=G8tXjcseNjg) pour découvrir brièvement comment créer et tester un Agent Mastra. ## Démarrage rapide Créez un Agent en instanciant la classe `Agent` de `@mastra/core` et fournissez les propriétés requises : ```typescript import { Agent } from '@mastra/core/agent' export const testAgent = new Agent({ id: 'test-agent', name: 'Test Agent', instructions: 'You are a helpful assistant.', model: 'openai/gpt-5.6-sol', }) ``` Les `instructions` définissent le comportement, la personnalité et les capacités de l’Agent. Ces instructions système établissent son identité fondamentale et son expertise. Le `model` est indiqué sous la forme `'provider/model-name'` au moyen du [routeur de modèles](https://mastra.zisheng.pro/fr/models) de Mastra. Pour rendre l’Agent disponible dans toute votre application, enregistrez-le auprès de votre instance Mastra (généralement située dans `src/mastra/index.ts`) : ```typescript import { Mastra } from '@mastra/core' import { testAgent } from './agents/test-agent' export const mastra = new Mastra({ agents: { testAgent }, }) ``` Une fois enregistré, il peut être appelé depuis des Workflows, des Tools ou d’autres Agents, et accéder à des ressources partagées telles que la Memory, la journalisation et les fonctionnalités d’observabilité. Consultez la [référence des Agents](https://mastra.zisheng.pro/fr/reference/agents/agent) pour en savoir plus sur les propriétés et configurations disponibles. > **Astuce:** Utilisez [Studio](https://mastra.zisheng.pro/fr/docs/studio/overview) pour tester votre Agent avec différents messages, examiner les appels de Tool et les réponses, et déboguer son comportement. ## Utiliser votre Agent Après l’enregistrement, récupérez votre Agent avec [`mastra.getAgentById()`](https://mastra.zisheng.pro/fr/reference/core/getAgentById). Appelez `.generate()` pour obtenir une réponse complète ou `.stream()` pour transmettre les jetons en temps réel. Vous pouvez appeler des Agents depuis les [étapes de Workflow](https://mastra.zisheng.pro/fr/docs/workflows/agents-and-tools), les [Tools](https://mastra.zisheng.pro/fr/docs/agents/using-tools), le [client Mastra](https://mastra.zisheng.pro/fr/reference/client-js/mastra-client), les gestionnaires de routes, les [adaptateurs de serveur](https://mastra.zisheng.pro/fr/docs/server/server-adapters) ou la ligne de commande. Consultez la [section des guides](https://mastra.zisheng.pro/fr/guides) pour apprendre à utiliser des Agents avec le framework de votre choix. Lorsque vous référencez un Agent depuis votre instance Mastra, utilisez `mastra.getAgentById()` afin de garantir son accès aux services partagés, tels que le stockage au niveau de l’instance, la journalisation et le registre des Agents. Un Agent importé directement peut fonctionner avec sa propre configuration locale, mais il n’aura pas accès à ces services partagés. **.generate()**: Renvoie la réponse complète une fois tous les appels de Tool et toutes les étapes terminés. Le résultat comprend `text`, `toolCalls`, `toolResults`, `steps` et les statistiques d’utilisation des jetons dans `usage`. Consultez la [référence de `Agent.generate()`](https://mastra.zisheng.pro/fr/reference/agents/generate) pour connaître la structure de la réponse, notamment les charges utiles des appels de Tool et de leurs résultats. ```ts const agent = mastra.getAgentById('test-agent') const response = await agent.generate('Help me organize my day') console.log(response.text) ``` **.stream()**: Renvoie un flux que vous pouvez consommer à mesure que les jetons arrivent. Le résultat expose `textStream` pour la sortie incrémentale, ainsi que des promesses pour `toolCalls`, `toolResults`, `steps` et les statistiques d’utilisation des jetons dans `usage`, résolues à la fin du flux. Consultez la [référence de `MastraModelOutput`](https://mastra.zisheng.pro/fr/reference/streaming/agents/MastraModelOutput) pour connaître la structure du flux, notamment les charges utiles des appels de Tool et de leurs résultats. ```ts const agent = mastra.getAgentById('test-agent') const stream = await agent.stream('Help me organize my day') for await (const chunk of stream.textStream) { process.stdout.write(chunk) } ``` ## Enrichir votre Agent Une fois votre Agent en cours d’exécution, utilisez ce tableau pour trouver la page correspondant à votre prochaine étape : | Objectif | Point de départ | | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | | Donner à votre Agent des Tools pour appeler des API ou services externes | [Tools](https://mastra.zisheng.pro/fr/docs/agents/using-tools) | | Conserver le contexte et les préférences entre les conversations | [Memory](https://mastra.zisheng.pro/fr/docs/memory/overview) | | Obtenir des objets typés plutôt que du texte brut | [Sortie structurée](https://mastra.zisheng.pro/fr/docs/agents/structured-output) | | Human-in-the-loop : suspendre l’exécution en attendant une approbation humaine | [Approbation](https://mastra.zisheng.pro/fr/docs/agents/agent-approval) | | Créer un réseau multi-Agent | [Agents superviseurs](https://mastra.zisheng.pro/fr/docs/capabilities/subagents) | | Enregistrer des sous-Agents | [Tools](https://mastra.zisheng.pro/fr/docs/agents/using-tools) | | Intercepter ou transformer les messages avant et après la génération | [Processeurs](https://mastra.zisheng.pro/fr/docs/agents/processors) | | Sécuriser votre Agent | [Garde-fous](https://mastra.zisheng.pro/fr/docs/agents/guardrails) | | Créer des Agents qui corrigent leur travail | [Scorer de grille d’évaluation](https://mastra.zisheng.pro/fr/docs/capabilities/subagents) | | Changer les instructions ou les modèles selon le contexte de la requête | [Configuration dynamique](https://mastra.zisheng.pro/fr/docs/server/request-context) | | Ajouter la transcription ou la synthèse vocale | [Voix](https://mastra.zisheng.pro/fr/guides/voice/overview) | | Se connecter à Slack, Discord ou Telegram | [Canaux](https://mastra.zisheng.pro/fr/docs/capabilities/channels/overview) | ## Systèmes multi-Agent Un système multi-Agent utilise plusieurs Agents pour résoudre une tâche trop vaste ou trop spécialisée pour un seul Agent. Au lieu de créer un Agent doté de dizaines de Tools et d’un long ensemble d’instructions, vous répartissez les responsabilités entre des Agents spécialisés et laissez un coordinateur réunir les résultats. Consultez la [présentation conceptuelle des systèmes multi-Agent](https://mastra.zisheng.pro/fr/guides/concepts/multi-agent-systems) pour découvrir comment appliquer différents modèles avec Mastra.