AP10 · Outil calqué sur l’API

Définition

On expose à l’agent les points d’accès d’une API conçue pour des développeurs, un pour un. L’agent doit les enchaîner lui-même pour accomplir la moindre intention.

Symptômes observables

• Des appels `list_*` puis `get_*` en boucle pour une seule demande de l’utilisateur.
• Les tokens d’entrée gonflent à chaque appel, sous le poids des résultats intermédiaires.
• Des outils destructeurs ou sensibles, hérités de l’API interne, sont exposés sans besoin.

Pourquoi c'est nuisible

Une API est faite d’actions granulaires : enchaînées par un modèle, elles multiplient les tours, polluent le contexte et dégradent la performance. Elles exposent aussi des opérations dangereuses sans le filet des revues humaines, et rien de déterministe n’empêche l’agent d’en abuser.

Un choix défendable quand…

• Un prototype en lecture seule sur une petite API, le temps d’observer quelles intentions reviennent avant de concevoir les outils.

Chiffres

• Thoughtworks classe la conversion naïve d’une API en serveur MCP dans l’anneau « Hold » (à éviter) de son radar de novembre 2025.
• Faire écrire à l’agent du code contre l’API, plutôt que de lui faire enchaîner les outils, fait passer un exemple de 150 000 à 2 000 tokens (−98,7 %, mesure de l’éditeur sur son propre exemple).

Remèdes du catalogue

• A2 · Outils et interface agent-machine (ACI) — Des outils pensés pour l’agent : une intention, un outil, qui fait les appels nécessaires et ne renvoie que l’utile.
• C4 · Agent qui agit en code — L’agent écrit du code contre l’API dans un bac à sable ; seul le résultat filtré revient dans le contexte.
• G1 · Sélecteur d’actions — Les opérations sensibles sortent du jeu d’outils, ou ne restent accessibles que par une liste fermée d’actions aux paramètres validés.

Mesures hors catalogue

• Un serveur MCP dédié, construit au-dessus de l’API, plutôt qu’une conversion automatique.

Patterns détournés

• A2 · Outils et interface agent-machine (ACI)

Anti-patterns voisins

• AP12 · Trop d’outils chargés d’emblée
• AP13 · Sorties d’outils non bornées
• AP19 · Outil à fonctionnalité excessive

Sources

• Technology Radar, vol. 33 — Thoughtworks, 2025-11
• Writing effective tools for agents — Anthropic (K. Aizawa et al.), 2025-09-11
• Function calling — OpenAI (documentation)
• Code execution with MCP — Anthropic (A. Jones, C. Kelly), 2025-11-04