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

# 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()`](https://mastra.zisheng.pro/fr/reference/tools/create-tool), 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()`](https://mastra.zisheng.pro/fr/reference/tools/create-tool).

## Démarrage rapide

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

```typescript
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()`](https://mastra.zisheng.pro/fr/reference/tools/create-tool) pour toutes les options et l’[approbation des Tools](https://mastra.zisheng.pro/fr/docs/harness/agent-controller) 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](https://mastra.zisheng.pro/fr/reference/file-based-agents/workspace) ou de bac à sable.

## Priorité par rapport à config

Les Tools découverts sont fusionnés avec les `tools` de [`config.ts`](https://mastra.zisheng.pro/fr/reference/file-based-agents/config). 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.