💻 computer science

HarnessAPI: A Skill-First Framework for Unified Streaming APIs and MCP Tools

HarnessAPI est un framework Python qui élimine la duplication de code en traitant les dossiers de compétences typés comme une source unique de vérité pour générer automatiquement des endpoints HTTP de streaming unifiés, une documentation OpenAPI interactive et des outils MCP sans configuration à partir d'un seul gestionnaire et de schémas Pydantic.

Auteurs originaux : Edwin Jose

Publié 2026-05-22

📖 5 min de lecture🧠 Analyse approfondie

CC BY 4.0

Auteurs originaux : Edwin Jose

Article original sous licence CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ Ceci est une explication générée par l'IA de l'article ci-dessous. Elle n'a pas été rédigée ni approuvée par les auteurs. Pour une précision technique, consultez l'article original. Lire la clause de non-responsabilité complète

Imaginez que vous êtes un chef ayant inventé une nouvelle recette délicieuse (une « compétence »). Dans le monde de l'IA et des logiciels, cette recette doit être servie à deux types de clients très différents :

Le Client Web : Il se rend sur le site web de votre restaurant, remplit un formulaire et s'attend à recevoir un reçu rapide et formaté (un point de terminaison HTTP).
Le Butler Robot : C'est un assistant IA (comme un majordome numérique) qui doit saisir votre recette directement sur l'étagère de votre cuisine pour l'utiliser pendant la cuisson (un outil MCP).

Le Problème : Le Cauchemar de la « Double Saisie »
Actuellement, si vous voulez servir les deux clients, vous devez écrire votre recette deux fois.

D'abord, vous l'écrivez dans un registre élégant pour le site web (en utilisant un ensemble de règles).
Ensuite, vous devez réécrire les exactes mêmes instructions dans un cahier différent pour le buteur robot (en utilisant un ensemble de règles totalement différent).

L'article appelle cela le problème de la « double pile ». Le pire est que si vous modifiez un ingrédient dans votre cuisine (mettez à jour votre code), vous devez vous souvenir de mettre à jour les deux registres. Si vous oubliez, le site web pourrait indiquer « Ajoutez 2 œufs » tandis que le buteur robot pensera « Ajoutez 2 tasses de farine ». Cela conduit à de la confusion, des erreurs et une paperasse supplémentaire considérable.

La Solution : HarnessAPI
L'auteur, Edwin Jose, a créé un framework appelé HarnessAPI qui résout ce problème en changeant les règles du jeu. Au lieu de commencer par le « site web » ou le « robot », vous commencez par la Compétence (le dossier de la recette).

Considérez HarnessAPI comme un traducteur et une imprimante universels situés dans votre cuisine.

Vous placez votre recette dans un seul dossier avec un ensemble d'instructions.
HarnessAPI examine ce dossier et imprime automatiquement pour vous le « Reçu Web » et la « Feuille d'Instructions Robot ».
Parce que les deux feuilles proviennent du même dossier maître, elles ne peuvent jamais diverger. Si vous modifiez la recette, les deux feuilles se mettent à jour instantanément.

Comment Cela Fonctionne (Les Tours de Magie)

Un Dossier, Deux Portes : Le framework traite un dossier contenant votre code comme la « Source de Vérité ». Il construit automatiquement une porte pour le web et une porte pour le robot, vous évitant ainsi de les construire manuellement.
Le Serveur Métamorphe : Imaginez un serveur qui peut changer d'uniforme en fonction de celui qui demande. Si un navigateur web demande des données, le serveur les sert sous forme d'un fichier JSON standard. Si un agent IA demande un flux de données (comme une vidéo lue par morceaux), le serveur passe instantanément en mode flux. Le serveur (votre code) ne sait même pas qu'il change ; le framework gère la transition automatiquement.
Le Robot « Faux » : Pour permettre au buteur robot de comprendre votre code, le framework crée à la volée un « wrapper » spécial (un traducteur). C'est comme si le framework écrivait rapidement une note disant : « Hé Robot, voici exactement comment appeler cette fonction », afin que le robot ne soit pas confus par des structures de code complexes.

Pourquoi Cela Compte (Les Résultats)
L'auteur a testé cela en construisant six « compétences » différentes (comme résumer du texte ou traduire des langues) de deux manières :

L'Ancienne Méthode : Écrire manuellement le code pour le site web et le robot séparément.
La Méthode HarnessAPI : Écrire simplement la compétence une seule fois.

Les Constats :

74 % Moins de Travail : La méthode HarnessAPI a nécessité 74 % de code « boilerplate » (le travail d'installation ennuyeux et répétitif) en moins.
Pas de Dérive : Dans l'ancienne méthode, les deux versions pouvaient dériver et devenir incohérentes. Dans la nouvelle méthode, elles sont mathématiquement garanties identiques car elles proviennent de la même source.
Un Seul Processus : Au lieu d'exécuter deux serveurs distincts (un pour le web, un pour le robot), HarnessAPI exécute tout dans un seul processus unique, le rendant plus léger et plus facile à gérer.

La Mise en Garde (Limites)
L'article est honnête concernant quelques règles de sécurité :

La Fonctionnalité « Hot-Swap » : Il existe une fonctionnalité permettant de mettre à jour le code pendant que le serveur tourne (idéal pour les tests), mais l'auteur avertit que c'est comme donner une télécommande de votre cuisine à quelqu'un. Il n'est que sûr de l'utiliser sur votre propre ordinateur (localhost) et ne devrait jamais être activé pour des sites web publics, sinon des pirates pourraient prendre le contrôle de votre serveur.
Complexité : Cela fonctionne très bien pour des recettes standards, mais si votre recette implique des structures imbriquées extrêmement complexes, le traducteur automatique pourrait avoir besoin d'un peu d'aide.

En Résumé
HarnessAPI est un outil qui empêche les développeurs de faire un double travail. Il dit : « Écrivez votre code une fois, et nous nous occuperons du reste. » Il garantit que vos outils IA et vos outils web sont toujours parfaitement synchronisés, économisant du temps et prévenant les erreurs qui surviennent lorsque l'on tente de maintenir deux versions distinctes d'une même chose.

Résumé Technique : HarnessAPI – Un Framework « Skill-First » pour des APIs de Streaming Unifiées et des Outils MCP

1. Énoncé du Problème

L'article identifie une friction architecturale critique dans le déploiement d'outils de Modèles de Langage (LLM). Actuellement, les développeurs doivent maintenir deux représentations parallèles pour chaque fonction Python destinée à servir d'outil LLM :

Point de terminaison HTTP : Pour les clients humains, les tableaux de bord web et les pipelines d'intégration continue, généralement implémentés à l'aide de frameworks comme FastAPI.
Outil MCP : Pour les environnements d'exécution d'agents (par exemple, Claude Desktop, Cursor) utilisant le protocole de contexte de modèle (MCP), généralement implémentés à l'aide de frameworks comme FastMCP.

Bien que ces deux interfaces partagent la même logique métier sous-jacente, elles divergent dans leur machinerie environnante (routage, validation, sérialisation, streaming et maintenance du schéma). Cette approche « double pile » force les développeurs à maintenir deux définitions de schéma distinctes (une pour HTTP/Pydantic, une pour MCP). À mesure que le code évolue, ces définitions s'éloignent l'une de l'autre, entraînant une obsolescence des schémas. L'article cite Patil et al. [9] pour noter que les LLMs hallucinent des appels d'API lorsque les schémas de types sont absents ou obsolètes, rendant cette dérive un risque pour la fiabilité. De plus, Mastouri et al. [10] ont trouvé empiriquement que 88,6 % des serveurs MCP sont soutenus par des services REST existants, ce qui signifie que la grande majorité des déploiements supportent déjà ce fardeau de maintenance double.

Les frameworks existants traitent soit la route (FastAPI), soit l'outil (FastMCP) comme l'entité principale, nécessitant un acte d'enregistrement séparé pour l'autre. Cela force le développeur à agir comme la couche de synchronisation entre les deux.

2. Méthodologie : L'Architecture Skill-First

HarnessAPI propose une architecture « Skill-First » qui inverse la dépendance. Au lieu que le développeur déclare une route puis un outil (ou vice versa), le dossier de compétence (skill folder) devient la source unique de vérité.

Principes de Conception Fondamentaux

Source Unique de Vérité : Une compétence est définie comme un répertoire contenant un handler.py typé et un models.py Pydantic.
Représentations Dérivées : Le framework dérive automatiquement à la fois le point de terminaison HTTP et l'enregistrement de l'outil MCP à partir de cette structure de répertoire unique.
Invariant Structurel : Parce que les deux transports résolvent vers le même modèle Pydantic à l'exécution, la cohérence du schéma est imposée par construction plutôt que par la discipline du développeur.

Mécanismes Techniques Clés

Découverte et Isolation des Compétences :
- Le framework scanne un répertoire de compétences, identifiant les sous-dossiers contenant handler.py et models.py.
- Pour éviter les collisions d'espaces de noms (par exemple, plusieurs compétences définissant une classe nommée Input), HarnessAPI crée un espace de noms de package synthétique pour chaque compétence en utilisant types.ModuleType. Cela permet à plusieurs compétences de coexister sans masquer les classes les unes des autres.
Négociation de Contenu en Mode Double :
- Le framework prend en charge les réponses en streaming et non en streaming à partir d'un seul gestionnaire.
- Streaming (SSE) : Si le client ne demande pas application/json, le framework ouvre un flux d'événements envoyés par le serveur (SSE). Il émet des morceaux de manière incrémentielle, émettant les événements chunk, result, done ou error.
- Par Lots (JSON) : Si le client envoie Accept: application/json, le framework met en mémoire tampon la sortie du gestionnaire et renvoie une seule réponse JSON.
- Cela permet au même gestionnaire de servir des sessions d'agents interactives (streaming) et des pipelines par lots (JSON) sans modifications de code.
Génération Dynamique d'Enveloppe MCP :
- Un défi technique majeur abordé est l'inspection de schéma de FastMCP, qui repose sur la lecture des __annotations__ d'une fonction et la résolution des types par rapport à __globals__. Les fermetures naïves échouent car le modèle Pydantic n'est pas dans la portée globale de la fonction.
- Solution : HarnessAPI compile dynamiquement une fonction d'enveloppe en utilisant exec dans un espace de noms qui inclut explicitement le modèle Pydantic. Cela garantit que le type est résolvable par la couche d'inspection de FastMCP, permettant un enregistrement correct de l'outil sans duplication manuelle du schéma.
Gestion du Cycle de Vie :
- HarnessAPI sous-classe FastAPI et monte l'application FastMCP en tant que sous-application ASGI.
- Elle implémente un gestionnaire de contexte de durée de vie fusionné qui compose les hooks de démarrage/arrêt de l'application de l'utilisateur (par exemple, connexions de base de données) et du serveur FastMCP, permettant un déploiement en processus unique.
Capacité de Remplacement à Chaud (Développement Uniquement) :
- Un point de terminaison optionnel permet de soumettre des chaînes de code pour remplacer dynamiquement la logique du gestionnaire. Ceci est strictement limité aux adresses de bouclage (localhost) pour empêcher l'exécution de code à distance en production.

3. Contributions Clés

L'article définit les contributions suivantes :

Motif d'Architecture Skill-First : Un motif formel où le répertoire de compétence est la définition autoritaire, contrastant avec les motifs route-first (FastAPI) et outil-first (FastMCP).
Mécanismes d'Implémentation :
- Génération dynamique de routes et négociation de contenu en mode double.
- Une technique de génération de code pour propager les annotations Pydantic vers la couche d'inspection de FastMCP.
- Une stratégie de fusion de durée de vie pour le fonctionnement en processus unique.
Réduction du Code Boilerplate : Une évaluation empirique montrant une réduction significative du code face au framework.
Publication Open-Source : La publication de HarnessAPI v0.1.4, disponible sur PyPI et GitHub.

4. Résultats de l'Évaluation

Les auteurs ont évalué HarnessAPI par rapport à une implémentation de double pile maintenue manuellement (serveurs FastAPI et FastMCP séparés) en utilisant six compétences représentatives : Echo, Greet, Summarize, VectorNorm, Classify et Translate.

Réduction du Code Boilerplate : En utilisant cloc pour compter les lignes non vides et non commentées de code face au framework (à l'exclusion de la logique métier), HarnessAPI a nécessité 44 lignes au total pour les six compétences, contre 170 lignes pour l'implémentation manuelle. Cela représente une réduction de 74 % du code boilerplate.
Comportement d'Évolutivité : L'approche manuelle présente une évolutivité en $O(n)$ , où le code du framework croît linéairement avec le nombre de compétences (chacune nécessitant de nouveaux décorateurs et enregistrements). HarnessAPI présente une évolutivité en $O(1)$ concernant le code du framework, car le point d'entrée reste fixe indépendamment du nombre de compétences.
Parité Fonctionnelle : HarnessAPI fournit toutes les fonctionnalités de FastAPI et FastMCP autonomes dès la sortie de la boîte, y compris le streaming SSE, l'interface utilisateur OpenAPI/Swagger et les délais par compétence, sans nécessiter d'intégration de bibliothèque supplémentaire.
Compatibilité : Le framework a importé et enregistré avec succès 12 compétences existantes du dépôt agentskills.io sans modifications du code source, démontrant un déploiement sans friction pour les ensembles de compétences existants.

5. Signification et Revendications

L'article affirme que HarnessAPI résout la « réponse inconfortable » de la maintenance double dans le déploiement d'outils LLM. Sa signification réside dans la transformation de la cohérence des schémas d'une discipline de développeur (sujette aux erreurs et à la dérive) en un invariant structurel imposé par le framework.

Les auteurs soulignent que la réduction de 74 % du code boilerplate est une conséquence de cet invariant, mais le résultat plus durable est la propriété d'évolutivité. À mesure que les écosystèmes d'agents mûrissent et que les développeurs déploient des dizaines ou des centaines de compétences, le fardeau de maintenance cumulatif de l'enregistrement manuel de double pile devient intenable. HarnessAPI suggère que la solution n'est pas de meilleurs outils pour maintenir deux enregistrements, mais l'élimination du second enregistrement entièrement.

L'article reste modeste concernant son périmètre :

Il ne prétend pas résoudre les problèmes de latence de bout en bout ou les benchmarks de concurrence, renvoyant aux caractéristiques de performance connues de la pile FastAPI/Uvicorn sous-jacente.
Il reconnaît des limitations, telles que l'utilisation de exec pour la génération d'enveloppe MCP (une solution temporaire pour le résolveur actuel de FastMCP) et l'absence d'authentification par outil dans la couche MCP.
Il met explicitement en garde contre l'utilisation du point de terminaison de remplacement à chaud dans les déploiements accessibles au réseau, le restreignant aux boucles de développement local.

En conclusion, HarnessAPI fournit une couche de déploiement unifiée et orientée compétence qui garantit la cohérence des schémas, réduit la charge de maintenance et prend en charge les interactions en streaming et par lots pour les agents LLM modernes.