Concevoir les outils des agents IA : bonnes pratiques et erreurs courantes

La qualité d'un agent IA ne dépend pas seulement de la puissance du modèle de langage, mais aussi de la conception de ses outils. Machine Learning Mastery a analysé ce qui rend les tools d'un agent efficaces, et quelles erreurs transforment un agent intelligent en agent chaotique.

Le nom et la description font 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 cette seule base qu'il décide quand l'appeler et avec quels arguments.

Exemple d'outil faible : `get_data()`, décrit comme « récupère des données ». Exemple d'outil solide : `get_user_purchase_history(user_id)`, décrit comme « renvoie la liste des achats des 90 derniers jours, triés par date. À utiliser pour analyser les dépenses ou construire une personnalisation ». La seconde version explique non seulement ce que fait l'outil, mais aussi quand l'appeler : pour l'agent, ce sont deux niveaux d'utilité fondamentalement différents.

Le nom porte la sémantique : `process_file` est trop large. Avec `extract_invoice_line_items`, le modèle comprend immédiatement le contexte et le champ d'application. Une bonne formule : verbe + objet + précision.

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

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

Un outil, une responsabilité

L'erreur la plus fréquente est le « couteau suisse » : une fonction à une dizaine de paramètres qui fait cinq choses différentes selon la combinaison de flags.

Les signes d'un outil mal conçu :

• Un paramètre `mode` ou `action` acceptant un ensemble de valeurs textuelles
• Plus de 5–6 paramètres dans une seule fonction
• La conjonction « ou » dans la description : « recherche un contact ou en crée un nouveau »
• Des types de données renvoyés différents selon les arguments d'entrée
• Des paramètres facultatifs qui modifient radicalement le comportement

Si un outil fait plusieurs choses, découpez-le en outils distincts. Il est plus simple pour l'agent de choisir entre `search_contact` et `create_contact` que de deviner la bonne combinaison de flags dans `manage_contact`. Au-delà de 20 outils dans le contexte, la précision des modèles pour choisir le bon outil chute nettement : gardez un jeu d'outils compact.

Paramètres et valeurs de retour

Le type d'un paramètre influe sur la qualité de la génération. Un `string` sans description est une source d'hallucinations. Un `enum` avec une liste explicite de valeurs autorisées ne l'est pas. Pour les paramètres numériques, indiquez la plage et l'unité : pas `timeout`, mais `timeout_seconds: integer, 1–30`.

La valeur de retour doit être prévisible et compacte : l'agent ajoute toute la sortie de l'outil à son contexte. Si l'outil renvoie des milliers de tokens de HTML brut, c'est un goulet d'étranglement pour toute la chaîne d'appels.

Les principes d'une bonne valeur de retour :

• Du JSON à structure fixe : le modèle parse mieux les formats prévisibles
• Des erreurs sous forme de données structurées, et non d'exceptions non interceptées
• Des méta-champs : `total_results`, `truncated: true`, `next_cursor`
• Uniquement ce dont l'agent a besoin pour l'étape suivante, rien de plus
• En cas d'erreur, un message clair indiquant la marche à suivre

Ce que cela signifie

Les outils d'un agent ne sont pas de simples surcouches d'API. Ils forment l'interface entre le modèle de langage et le monde réel, et exigent la même attention qu'une API publique : documentation, types réfléchis, tests en isolation. L'agent ne corrigera pas un outil mal conçu : il continuera à l'appeler de travers, encore et encore.