Comment déclarer un outil personnalisé

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

# Comment déclarer un outil personnalisé

Ce guide montre comment transformer un script ou un programme en un outil que le modèle voit à chaque tour, avec des paramètres typés, en le déclarant dans le fichier d'agent. Il suppose que vous avez un fichier YAML d'agent et une commande que vous lancez déjà à la main.

Utilisez-le pour une action fréquente et précise : lancer les tests d'un package, préparer une release, interroger un service. Pour une procédure en plusieurs étapes, ou un savoir-faire que le modèle doit lire avant d'agir, écrivez plutôt un [skill](add-a-skill.md).

## Étapes

1. Vérifiez que la commande fonctionne depuis le répertoire où mm s'exécute :

   ```bash
   ./scripts/release.sh 1.4.2 beta
   ```

2. Ajoutez un bloc `tools:` au fichier d'agent, avec une entrée par commande. Nommez l'outil d'après l'action, décrivez ce qu'il fait et quand s'en servir, déclarez un paramètre par argument, et écrivez la commande comme une liste — le programme d'abord, puis une entrée par argument, avec `{{paramètre}}` là où va une valeur :

   ```yaml
   tools:
     - name: release
       description: Prepare a release of the project for a given version and channel.
       parameters:
         version: { type: string, description: "e.g. 1.4.2" }
         channel: { type: string, enum: [stable, beta, nightly] }
       command: ["./scripts/release.sh", "{{version}}", "{{channel}}"]
   ```

3. Lancez mm et vérifiez que la bannière liste l'outil parmi les autres (ici `release`). Une erreur dans le bloc arrête mm avec un `[config error: …]` qui nomme l'entrée ; la [référence de configuration](../reference/configuration.md#erreurs-de-validation) les liste.

4. Demandez l'action avec vos propres mots :

   ```bash
   mm -p "Prépare la release 1.4.2 sur le canal beta."
   ```

   Le terminal affiche l'appel et sa sortie :

   ```
   🧰 release: ./scripts/release.sh 1.4.2 beta
      │ release done: 1.4.2 beta
   ```

## Variantes

- **Un nombre, un entier ou une option.** Donnez au paramètre un `type` : `number`, `integer` ou `boolean`. Un booléen va en général à l'intérieur d'une entrée : `"--dry-run={{dryRun}}"`.
- **Un argument facultatif.** Ajoutez `required: false`. Si le modèle l'omet, une entrée qui n'est que `"{{p}}"` disparaît de la commande ; donnez un `default` pour passer quand même une valeur :

  ```yaml
  retries: { type: integer, required: false, default: 3 }
  ```

- **Une commande plus longue que `bashTimeout`.** Ajoutez `timeout: 2m` à l'entrée.
- **Demander avant chaque appel.** Mettez `yolo: false` : les outils déclarés demandent alors comme `bash`. Avec `yolo: true`, ils s'exécutent sans demander.
- **Une fonction du shell (pipe, redirection, `&&`).** La commande s'exécute sans shell : écrivez-la dans un script et déclarez le script. Passer `["bash", "-c", "…{{p}}…"]` remettrait la valeur du modèle dans une ligne de shell.
- **La même action qu'un outil MCP.** Un outil déclaré ne peut pas prendre le nom d'un outil MCP : il est ignoré, avec un avertissement au démarrage. Renommez l'un des deux.
- **Un outil sans vos droits.** Un outil qui lit seulement un dossier ou calcule à partir de ses arguments peut être un module WebAssembly exécuté dans un bac à sable plutôt qu'une commande : voir [Écrire un outil personnalisé sous forme de module WebAssembly](write-a-wasm-tool.md).
- **Contrôler ce qui s'exécute avant ou après.** Les [hooks](guard-the-agent-with-hooks.md) `preToolCall` et `postToolCall` s'appliquent aux outils déclarés ; utilisez le nom de l'outil comme `matcher`.

## Voir aussi

- Un exemple complet avec quatre outils et tous les types de paramètres : `demos/declared-tools/`
- Chaque clé, chaque type et chaque erreur : [référence de configuration](../reference/configuration.md#clés-de-tools) et [outils déclarés](../reference/tools.md#outils-déclarés)
- Pourquoi des outils typés à côté des skills, et ce qui a été mesuré : [Les outils déclarés](../explanation/declared-tools.md)