Tools

Un Agent basé sur des fichiers découvre les Tools à partir des fichiers .ts et .js situés directement dans son répertoire tools/. Chaque fichier découvert est importé lors de la compilation, doit exporter par défaut le résultat de createTool(), et son nom sans extension devient la clé de Tool que le modèle peut appeler.

Utilisez cette page pour la convention basée sur les fichiers. Pour les schémas de Tool, les options d’exécution, la mise en forme de la sortie et les options d’approbation, consultez la référence de createTool().

Démarrage rapide

Placez un Tool par fichier dans tools/. Ce fichier est exposé à l’Agent sous le nom get_weather.

src/mastra/agents/weather/tools/get_weather.ts

import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export default createTool({
  id: 'get_weather',
  description: 'Get the current weather for a location.',
  inputSchema: z.object({
    location: z.string(),
  }),
  outputSchema: z.object({
    location: z.string(),
    temperatureCelsius: z.number(),
    conditions: z.string(),
  }),
  execute: async ({ location }) => {
    return { location, temperatureCelsius: 21, conditions: 'sunny' }
  },
})

Organiser les Tools

Utilisez un fichier par Tool. Nommez le fichier d’après l’action que le modèle doit effectuer :

• Utilisez get_weather.ts, search_docs.ts ou create_ticket.ts.
• Évitez les noms vagues comme helper.ts, api.ts ou utils.ts.
• Colocalisez les tests à côté du Tool sous la forme *.test.ts ou *.spec.ts. La découverte ignore ces fichiers.
• Conservez le code d’assistance partagé en dehors de tools/ ou dans des fichiers qui ne correspondent pas aux extensions découvertes dans tools/.

Comme les répertoires imbriqués ne sont pas découverts en tant que Tools, regroupez les Tools associés avec des préfixes de nom de fichier explicites plutôt qu’avec des sous-dossiers, par exemple calendar_create_event.ts et calendar_list_events.ts.

Options de Tool

La convention basée sur les fichiers contrôle uniquement l’emplacement du Tool et son mode d’enregistrement. L’API du Tool provient toujours de createTool() :

• Utilisez description pour indiquer au modèle quand appeler le Tool.
• Utilisez inputSchema et outputSchema pour des entrées et sorties structurées.
• Utilisez toModelOutput lorsque le modèle doit voir une forme différente de la valeur brute renvoyée par execute.
• Utilisez requireApproval lorsqu’un Tool requiert une confirmation humaine avant son exécution.

Consultez la référence de createTool() pour toutes les options et l’approbation des Tools pour le flux d’approbation.

Limite d’exécution

Le code de Tool s’exécute dans l’environnement d’exécution de votre application ou serveur lorsque l’Agent appelle le Tool. Si un Tool nécessite l’isolation du système de fichiers ou de l’interpréteur de commandes, appelez explicitement les API d’espace de travail ou de bac à sable.

Priorité par rapport à config

Les Tools découverts sont fusionnés avec les tools de config.ts. En cas de conflit de clé, config.tools est prioritaire et un avertissement est consigné.

Si config.tools est une fonction, les Tools découverts sont ignorés avec un avertissement, car les Tools définis par une fonction ne peuvent pas être fusionnés statiquement.