sgr-agent-core : raisonnement guidé par schéma et agents de recherche en Python
Schema-Guided Reasoning (SGR) has agentic system design created by neuraldeep community
En bref
- De quoi s’agit-il ?
- Une bibliothèque Python sous licence MIT qui structure la sortie d'un LLM avec un schéma avant de lui laisser choisir ses outils. Le point de départ est solide, la documentation reste inégale.
- À qui s’adresse-t-il ?
- Adoptez sgr-agent-core si vous voulez un serveur d'agents de recherche compatible OpenAI que vous pouvez lancer avec sgr -c examples/sgr_deep_research/config.yaml et brancher sur un modèle local. Passez votre chemin si vous cherchez un cadre généraliste couvrant la mémoire longue, l'orchestration multi-agents ou l'observabilité.
- Puis-je l’utiliser commercialement ?
- Oui. MIT est une licence permissive : vous pouvez utiliser, modifier et vendre un logiciel qui en dépend, à condition de conserver les mentions de droit d’auteur et de licence.
- Est-il encore maintenu ?
- Oui. Les derniers commits datent d’il y a 20 jours.
- En quel langage est-il écrit ?
- Principalement Python, d’après les statistiques de langage de GitHub.
Ces réponses reposent sur les données GitHub du projet (dernière synchronisation le 15 septembre 2026) et sur notre analyse. Elles ne constituent pas un avis juridique.
ANALYSE OPEN SOURCE APPROFONDIE
Le problème : un LLM qui doit raisonner et appeler des outils en même temps
Un agent de recherche enchaîne deux tâches de nature différente. Il doit décider quoi faire (chercher, ouvrir une page, demander une précision) et produire une réponse exploitable par un programme. Les deux se marchent souvent dessus. Si vous laissez le modèle libre de sa sortie, vous récupérez du texte qu'il faut parser à la main. Si vous le contraintes à un format strict, vous perdez la souplesse du choix d'outil.
Le README présente le Schema-Guided Reasoning comme la combinaison d'un raisonnement structuré et d'une sélection d'outils flexible. La cible est claire : des équipes qui construisent un service de recherche documentaire ou de veille et qui veulent exposer le résultat derrière une API compatible OpenAI. Le paquet s'installe avec pip install sgr-agent-core et se présente comme une bibliothèque, pas seulement comme une application. C'est ce double usage qui distingue le projet d'un simple script de démonstration.
Deux phases, trois agents, un schéma au milieu
L'architecture annoncée est en deux phases, portée par une interface BaseAgent extensible. Le dépôt fournit trois implémentations : SGRAgent, ToolCallingAgent et SGRToolCallingAgent. La distinction n'est pas cosmétique. ToolCallingAgent s'appuie sur le function calling natif du modèle. SGRAgent demande au modèle de remplir un schéma, ce qui rend la sortie vérifiable avant d'être exécutée. SGRToolCallingAgent combine les deux, et le README mentionne un axe de recherche interne sur le function calling hybride.
Le point intéressant est le flux de données. Le modèle produit une structure conforme à un schéma, cette structure est validée, puis elle déclenche un outil. L'ordre inverse serait plus fragile : un outil lancé sur une sortie non validée peut consommer du budget de recherche pour rien. Le schéma joue donc le rôle de contrat intermédiaire entre le modèle et l'exécution.
Les outils fournis couvrent la recherche web, l'extraction de contenu de page et la clarification. Cette dernière mérite attention : un agent peut interrompre son raisonnement pour poser une question. C'est utile pour un agent dialogique, mais cela suppose que le client sache répondre. Le CLI sgrsh annonce gérer ces demandes de clarification et de dialogue. Le README ne détaille pas le format exact de ces échanges, et c'est une zone que je qualifierais de sous-documentée à ce stade.
Mise en route : Docker, pip, puis le binaire sgr
Le chemin le plus court passe par l'image publiée. Le README donne la séquence complète : cloner le dépôt, créer les répertoires logs et reports avec des permissions d'écriture, copier examples/sgr_deep_research/config.yaml.example vers config.yaml, puis lancer le conteneur ghcr.io/vamplabai/sgr-agent-core:latest en montant le fichier de configuration en lecture seule et en exposant le port 8010.
Le serveur répond alors sur http://localhost:8010 avec des points d'entrée compatibles OpenAI, et Swagger UI est disponible sur http://localhost:8010/docs. Cette compatibilité est l'argument le plus concret du projet : un client qui parle déjà à OpenAI peut viser cette URL sans réécriture.
Les clés à renseigner sont nommées explicitement dans le README : llm.api_key pour le modèle, tools.web_search_tool.api_key et tools.extract_page_content_tool.tavily_api_key pour Tavily. Ces deux dernières sont marquées optionnelles, ce qui laisse entendre qu'un agent peut fonctionner sans recherche web, mais le README ne décrit pas ce que fait l'agent dans ce cas.
En installation locale, pip install sgr-agent-core puis la commande sgr -c examples/sgr_deep_research/config.yaml démarrent le serveur. Une variante existe : python -m sgr_agent_core.server --config-file. Pour l'usage interactif, sgrsh accepte une requête unique, un mode conversationnel sans argument, et une sélection d'agent via --agent sgr_agent ou -a. Enfin, sgracp --config examples/sgr_deep_research/config.yaml expose les mêmes agents en JSON-RPC sur stdio pour les éditeurs qui parlent l'Agent Client Protocol. Le bloc acp du fichier YAML, avec la clé acp.agent, choisit l'agent exposé ; sans ce bloc, le premier agent défini est utilisé.
Ce que le projet ne dit pas
Le README annonce une couverture de tests complète et une maturité de production. Aucun chiffre de couverture n'est fourni, et je ne peux pas la vérifier. Il faut le prendre comme une intention affichée, pas comme une mesure.
Le point qui me gêne le plus concerne le benchmark. Les chiffres SimpleQA sont donnés pour gpt-4.1-mini : 86,08 pour cent d'exactitude, 3 724 réponses correctes, 554 incorrectes, 48 non tentées. Deux choses manquent. D'abord, le nombre total d'exemples n'est pas rappelé, donc la part des questions non tentées reste à calculer. Ensuite, et c'est plus important, aucune mesure équivalente n'est publiée pour un modèle local, alors que le README met en avant la possibilité de faire de la recherche entièrement privée avec des modèles ouverts. C'est justement là que le raisonnement guidé par schéma devrait apporter le plus, parce qu'un petit modèle suit mieux un schéma qu'une instruction en prose. L'absence de ces chiffres est un manque, pas un détail.
Autre limite de forme : le README est tronqué dans le matériel que j'ai, et la documentation complète vit sur un site externe. Les détails d'implémentation du schéma lui-même, sa structure exacte, ne sont pas visibles ici. Un lecteur qui veut écrire son propre BaseAgent devra aller chercher ces informations ailleurs.
Face à un framework d'agents généraliste
La comparaison la plus directe se fait avec les cadres d'orchestration généralistes, du type LangGraph ou LlamaIndex. La différence n'est pas la qualité, c'est la portée. Ces cadres vous donnent des graphes d'états, de la persistance, des points de reprise, et une large bibliothèque d'intégrations. Ils vous laissent construire la validation de sortie vous-même, souvent en empilant un analyseur syntaxique par-dessus la réponse du modèle.
sgr-agent-core prend le chemin inverse. Le schéma est au centre, et le cadre est étroit : recherche, extraction, clarification. Vous n'avez pas de graphe à dessiner, mais vous n'avez pas non plus de mécanisme de reprise après incident ni de mémoire longue documentée. Le serveur HTTP compatible OpenAI est livré, ce qui n'est pas le cas par défaut dans la plupart des cadres généralistes.
Le choix se fait donc sur une question simple. Si votre besoin est un service de recherche avec une sortie contrainte et une API standard, le périmètre étroit du projet est un avantage. Si votre besoin est un système à plusieurs agents avec des boucles longues et de la persistance, vous allez buter sur les bords.
Licence, mises à jour et coût de suivi
Le projet est publié sous licence MIT. Concrètement, cela autorise la réutilisation, la modification et la redistribution, y compris dans un produit commercial, à condition de conserver la mention de copyright et le texte de la licence. Le README ne signale aucune clause supplémentaire, aucun usage restreint. Je ne donne pas d'avis juridique : faites lire le fichier LICENSE de votre copie avant toute intégration dans un produit distribué.
Le rythme de publication est irrégulier. Les versions 0.6.0, 0.7.0 et 0.7.1 sont datées du 24 janvier, du 18 mars et du 15 juillet. Le dernier envoi sur la branche principale est plus récent que la dernière version publiée. Autrement dit, la branche main avance entre deux versions. Si vous épinglez une version, vous suivez un rythme de quelques mois. Si vous suivez main, vous prenez le risque de changements d'interface non publiés.
Le coût d'exploitation réel ne vient pas du code mais des dépendances externes. Un modèle compatible OpenAI et, en pratique, une clé Tavily pour la recherche et l'extraction. Le README ne décrit pas de mécanisme de repli quand ces services sont indisponibles. Un déploiement en production suppose donc de traiter ces pannes en amont, dans votre propre couche réseau.
Conclusion éditoriale
Adoptez sgr-agent-core si vous voulez un serveur d'agents de recherche compatible OpenAI que vous pouvez lancer avec sgr -c examples/sgr_deep_research/config.yaml et brancher sur un modèle local. Passez votre chemin si vous cherchez un cadre généraliste couvrant la mémoire longue, l'orchestration multi-agents ou l'observabilité. Avant de vous engager, vérifiez le contenu réel de la clé agents dans le config.yaml.example, la manière dont sgrsh traite les demandes de clarification, et si le schéma de sortie de votre modèle supporte le mode JSON strict.
Notes de la communauté