Comment Concevoir des Outils pour les Agents IA : Pratiques de Travail et Erreurs Courantes

La qualité d'un agent IA est déterminée non seulement par la puissance du modèle de langage, mais aussi par la manière dont ses outils sont conçus. Machine Learning Mastery a analysé ce qui rend exactement les outils d'agent efficaces — et quelles erreurs transforment un agent intelligent en un agent chaotique.

Le nom et la description décident de tout

Le modèle de langage ne voit pas le code source de l'outil. Il ne voit que son nom, sa description et le schéma de ses paramètres — et c'est sur la base de cela qu'il décide quand l'appeler et avec quels arguments. Exemple d'un mauvais outil : `get_data()` avec la description « récupère les données ». Exemple d'un bon outil : `get_user_purchase_history(user_id)` — « retourne une liste des achats des 90 derniers jours, triée par date. Utilise quand tu dois analyser les dépenses ou construire la personnalisation ». La deuxième option explique non seulement ce que fait l'outil, mais aussi quand l'appeler — ce sont des niveaux fondamentalement différents d'utilité pour l'agent.

Un nom porte une sémantique : `process_file` — trop large. `extract_invoice_line_items` — le modèle comprend immédiatement le contexte et l'applicabilité. Bonne formule : verbe + objet + clarification.

« La description de l'outil est un prompt pour l'outil lui-même.

Si elle est vague, l'agent hallucinera les arguments ou appellera le mauvais outil. »

Un outil — une responsabilité

L'erreur la plus courante est un « couteau suisse » : une fonction avec une douzaine de paramètres qui fait cinq choses différentes selon une combinaison de drapeaux. Signes d'un outil mal conçu :

• Paramètre `mode` ou `action` avec un ensemble de valeurs de chaîne
• Plus de 5–6 paramètres dans une seule fonction
• La description contient « ou » — « recherche le contact ou en crée un nouveau »
• Retourne des types de données différents selon les arguments d'entrée
• Paramètres facultatifs qui changent radicalement le comportement

Si un outil fait plusieurs choses — divise-le en outils séparés. Un agent choisira plus facilement entre `search_contact` et `create_contact` que de deviner la bonne combinaison de drapeaux dans `manage_contact`. Avec plus de 20 outils en contexte, la précision des modèles pour choisir le bon diminue notablement — garde l'ensemble compact.

Paramètres et valeurs de retour

Le type de paramètre affecte la qualité de la génération. `string` sans description — une source d'hallucinations. `enum` avec une liste explicite de valeurs autorisées — non. Pour les paramètres numériques, spécifie la plage et les unités de mesure : pas `timeout`, mais `timeout_seconds: integer, 1–30`. La valeur de retour doit être prévisible et compacte : l'agent ajoute la totalité de la sortie de l'outil au contexte. Si un outil retourne des milliers de tokens de HTML brut — c'est un goulot d'étranglement pour toute la chaîne d'appels. Principes d'une bonne valeur de retour :

• JSON avec structure fixe — le modèle analyse mieux les formats prévisibles
• Erreurs — données structurées, pas d'exceptions non capturées
• Champs métadonnées : `total_results`, `truncated: true`, `next_cursor`
• Seulement ce dont l'agent a besoin pour l'étape suivante — rien de plus
• En cas d'erreur — un message clair avec des instructions pour les actions ultérieures

Qu'est-ce que cela signifie

Les outils pour les agents ne sont pas juste des enveloppes autour d'API. C'est une interface entre le modèle de langage et le monde réel, qui exige la même attention qu'une API publique : documentation, types bien pensés, tests en isolation. Un agent ne corrigera pas un outil mal conçu — il l'appellera incorrectement encore et encore.