Contexte des agents IA : privilégier les interfaces

L'interface répond souvent à la bonne question

Pour appeler un module voisin, l'agent a généralement besoin de savoir : quelles fonctions sont accessibles, quels paramètres elles prennent, quelles valeurs elles renvoient, et quelles règles s'y appliquent. Il n'a pas forcément besoin des boucles internes, ni de tout ce qui sert uniquement au calcul interne.

Une signature seule ne suffit cependant pas. settle_batch(txns, tier) montre comment on appelle la fonction, mais pas forcément des règles comme « conserver l'ordre de première apparition » ou « appliquer le seuil à partir de 15 000 centimes inclus ». Un bon résumé d'interface doit donc aussi inclure types, constantes publiques et contrats, surtout pour les cas limites.

Le bruit peut faire ressortir de mauvaises règles

Dans l'expérience, les dépendances contenaient des commentaires et des éléments d'implémentation obsolètes. Par exemple, certains évoquaient un tri des clés ou une condition différente pour calculer une réserve. Le contrat public, lui, demandait un ordre précis et une règle stricte au-dessus de 300 points de base.

Ce genre de divergence existe dans la vraie vie : un commentaire n'est pas toujours à jour, une ancienne version traîne encore, ou un exemple contredit le comportement attendu. Ajouter tout le code voisin sans tri augmente les chances que le modèle « choisisse » un indice secondaire. Ce n'est pas une garantie d'erreur, mais c'est une confusion évitable.

La règle simple qui ressort : transmettez d'abord ce qui sert à l'intégration. Donnez l'implémentation quand la tâche demande d'expliquer ou de modifier un comportement, pas seulement parce que la dépendance est importée.

Les résultats mesurés

Sur cette tâche, le mode « code complet » fait 17 réussites sur 20 en trois appels. Le mode « squelette d'interface » fait 20 sur 20 en un appel. Les volumes d'entrée sont respectivement de 45 270 et 2 316 jetons (environ 95 % de moins pour le second mode). Le coût estimé passe de 0,0446 à 0,0078 dollar, et le temps d'exécution d'environ 30 à environ 13 secondes.

Les trois erreurs restantes du premier mode aident à comprendre le pourquoi. L'agent a rejeté une valeur nulle pourtant autorisée pour unit_cents en testant cents <= 0 au lieu de cents < 0. Il a aussi recopié des clés d'entrée non validées dans la sortie, alors que le contrat limitait le dictionnaire à cinq clés. Bref : des erreurs de frontière et de cas limite, précisément le genre de choses qu'un contrat explicite met en évidence.

Comment lire ces chiffres sans en faire une loi

Ce benchmark montre un compromis opérationnel assez logique : un contexte plus court et mieux ciblé peut réduire coûts et itérations, et améliorer le respect de certains contrats. Mais il ne prouve pas que les squelettes seront toujours meilleurs, partout. Ici, on a un modèle, une tâche, un environnement isolé, et 20 tests cachés. La qualité des consignes, le contenu fourni et l'outil de génération comptent aussi. Sur une autre tâche - par exemple quand il faut comprendre une optimisation interne ou corriger une dépendance - le code complet peut redevenir utile.

Pour tester l'approche dans votre cas : prenez des tâches représentatives de votre équipe, gardez le même modèle, les mêmes consignes et les mêmes tests, et ne changez que la stratégie de contexte. Mesurez au moins le taux de réussite, les régressions, le nombre de passages, le volume de jetons, et le temps de revue humaine. Si votre coût baisse mais que le taux de défauts monte (ou que la correction devient plus lente), ce n'est pas un gain.

À retenir : ce résultat sert surtout de raison de tester un contexte filtré par interface, pas une invitation à supprimer aveuglément des dépendances.

Construire le squelette en Python

En Python, le module standard ast permet de repérer fonctions et classes sans exécuter le code. Voici une version simplifiée qui masque le corps des fonctions tout en conservant leur docstring lorsqu'elle existe :

import ast
def extraire_squelette(source: str) -> str:
"""Conserve les interfaces et docstrings, masque les corps de fonctions."""
arbre = ast.parse(source)
for nœud in ast.walk(arbre):
if isinstance(nœud, (ast.FunctionDef, ast.AsyncFunctionDef)):
doc = ast.get_docstring(nœud, clean=False)
instructions = []
if doc:
instructions.append(ast.Expr(value=ast.Constant(value=doc)))
instructions.append(ast.Expr(value=ast.Constant(value=Ellipsis)))
nœud.body = instructions
ast.fix_missing_locations(arbre)
return ast.unparse(arbre)

Cette base aide à démarrer, mais ce n'est pas un outil de production complet. Elle masque les corps de fonctions parcourues, y compris celles qui sont privées ou imbriquées. Selon le dépôt, il faudra préserver les définitions de classes, les constantes publiques, les décorateurs et tout ce qui permet de comprendre l'API. Dans certains cas, on peut aussi exclure les fonctions privées - sauf si elles constituent un contrat que l'agent doit connaître.

Pour plusieurs langages, un parseur comme Tree-sitter peut fournir une base syntaxique commune. Mais aucun parseur ne sait automatiquement quelles règles métier sont importantes. Ensuite, il faut enrichir : contrats explicites, types, constantes et exceptions pertinentes. Une docstring du style « traite les paiements » dit souvent trop peu sur les cas limites.

Appliquer un filtre en trois niveaux

1. Contexte initial : fichier cible, interfaces publiques des dépendances directes, contrats pertinents, et tests connus.
2. Enrichissement ciblé : si l'agent bloque ou si le contrat dépend d'un détail interne, ajoutez la fonction concernée - pas tout le dépôt.
3. Vérification : lancez les tests, regardez le diff, et contrôlez les invariants métier, notamment les valeurs limites et les effets de bord.

Cette progression évite le tout ou rien : envoyer le dépôt entier dès le départ, ou au contraire priver l'agent des infos dont il a besoin. On transforme la construction du contexte en décision réversible. Si le squelette ne suffit pas, on élargit plutôt que de repartir de zéro.

Pour une équipe, le filtre doit aussi être prévisible. Faites-le tourner sur des fichiers de test, puis inspectez le résultat après chaque changement. Un outil qui supprime par erreur une surcharge, une annotation ou un décorateur peut créer une confusion pire que le bruit qu'il voulait enlever.

Les cas où le squelette ne suffit pas

Faites attention notamment dans ces cas :

• Contrats incomplets : les signatures et docstrings ne décrivent pas toujours les invariants réels. Il faut souvent passer par les tests ou le code.
• Dépendance à modifier : masquer le corps prive l'agent de ce dont il a besoin pour corriger proprement.
• Comportement implicite : l'ordre, la gestion des erreurs, l'encodage ou les effets de bord peuvent être importants, mais non documentés.
• Génération imparfaite : le filtre peut supprimer des éléments essentiels, produire du code ambigu, ou manquer des constructions du langage.
• Investigation d'incident : les traces d'exécution et le chemin réel des données comptent plus qu'une API « théorique ».

Un compromis pratique : donner d'abord une carte d'interface à l'agent, puis ouvrir les fichiers (ou fonctions) au fur et à mesure. C'est plus naturel pour une investigation : on délimite le système, puis on descend au détail utile. À l'inverse, pour une modification locale bien spécifiée, le squelette peut suffire dès le premier passage.

La règle de décision

Avant d'ajouter une dépendance au prompt, posez une question simple : l'agent doit-il connaître le contrat, ou comprendre l'implémentation ? Si seul le contrat est nécessaire, passez par l'interface et les règles métier. Si la tâche implique de changer ou d'expliquer le fonctionnement interne, fournissez le code pertinent.

Enfin, gardez une règle de contrôle : le contexte réduit ne doit jamais remplacer les tests. Les contrats synthétisés doivent être vérifiables, et les changements doivent être jugés sur le comportement attendu - pas sur la capacité de l'agent à produire une réponse « en un passage ».