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/<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)

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.

📹 Regarder

Regardez le démarrage rapide des Agents Mastra 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 :

src/mastra/agents/test-agent.ts

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 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) :

src/mastra/index.ts

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 pour en savoir plus sur les propriétés et configurations disponibles.

astuce

Utilisez Studio 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(). 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, les Tools, le client Mastra, les gestionnaires de routes, les adaptateurs de serveur ou la ligne de commande. Consultez la section des 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() pour connaître la structure de la réponse, notamment les charges utiles des appels de Tool et de leurs résultats.

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 pour connaître la structure du flux, notamment les charges utiles des appels de Tool et de leurs résultats.

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
Conserver le contexte et les préférences entre les conversations	Memory
Obtenir des objets typés plutôt que du texte brut	Sortie structurée
Human-in-the-loop : suspendre l’exécution en attendant une approbation humaine	Approbation
Créer un réseau multi-Agent	Agents superviseurs
Enregistrer des sous-Agents	Tools
Intercepter ou transformer les messages avant et après la génération	Processeurs
Sécuriser votre Agent	Garde-fous
Créer des Agents qui corrigent leur travail	Scorer de grille d’évaluation
Changer les instructions ou les modèles selon le contexte de la requête	Configuration dynamique
Ajouter la transcription ou la synthèse vocale	Voix
Se connecter à Slack, Discord ou Telegram	Canaux

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 pour découvrir comment appliquer différents modèles avec Mastra.