PySpur : un canevas visuel pour itérer sur des agents écrits en Python

Trois douleurs nommées dans le README

Le README énonce le problème avant de décrire l'outil. Il liste trois symptômes : l'ajustement de prompts par essais successifs, le manque de visibilité sur les interactions entre étapes d'un workflow, et la relecture de sorties brutes en JSON dans un terminal. Ces trois points ne sont pas indépendants. Un agent qui enchaîne un appel d'outil, une reformulation et une seconde requête produit une trace longue, et c'est précisément cette trace qu'on relit à la main quand rien ne va. PySpur répond en déplaçant la lecture vers un graphe affiché dans le navigateur, chaque noeud correspondant à une étape. Le public visé est explicite : des ingénieurs qui construisent déjà des agents et qui connaissent Python. Le README ne promet pas de supprimer le code, il promet de réduire le nombre d'allers-retours entre l'édition et l'observation du résultat.

Un serveur local, un graphe, des noeuds en Python

Le mécanisme tient en deux couches. D'un côté, un serveur lancé par la commande pyspur serve, qui sert une interface web sur le port 6080 et stocke l'état dans une base. De l'autre, le graphe lui-même : des noeuds reliés entre eux, chacun exécutant du code Python. Le README indique qu'ajouter un nouveau type de noeud se fait en créant un seul fichier Python, ce qui signifie que le catalogue de noeuds n'est pas figé et que l'interface lit ce que le code expose. Les fonctionnalités listées couvrent les boucles avec mémoire pour l'appel d'outils répété, les sorties structurées éditées via un schéma JSON, le RAG en quatre temps (parse, chunk, embed, upsert vers une base vectorielle), le multimodal (vidéo, image, audio, texte, code) et les breakpoints human-in-the-loop. Ces derniers suspendent le workflow à un point donné et le reprennent après approbation humaine, ce qui suppose une persistance de l'état entre les deux moments. C'est cette contrainte de persistance qui explique la recommandation d'une base PostgreSQL plutôt que SQLite.

Installation : trois commandes et un fichier .env

Le chemin court tient en trois étapes, avec Python 3.11 minimum. pip install pyspur, puis pyspur init my-project pour créer un répertoire contenant un fichier .env, puis pyspur serve --sqlite pour démarrer. L'application écoute alors sur http://localhost:6080. Le README signale que SQLite sert de valeur par défaut mais recommande de renseigner une URL PostgreSQL dans le .env pour une expérience plus stable. Les clés de fournisseurs s'ajoutent de deux façons : par l'onglet API Keys de l'interface, ou à la main dans le .env suivi d'un redémarrage par pyspur serve. Le README annonce la prise en charge de plus de cent fournisseurs de LLM, d'embedders et de bases vectorielles, sans détailler comment cette compatibilité est obtenue. Pour le développement du projet lui-même, une autre voie existe : un dev container (.devcontainer/devcontainer.json) pour Cursor ou VS Code, ou bien docker compose -f docker-compose.dev.yml up --build -d. Le README précise que le développement sous Windows n'est pas pris en charge.

Ce que le dépôt ne dit pas

Plusieurs points restent flous à la lecture du matériel fourni. La description du dépôt indique TypeScript comme langage principal, alors que le produit se présente comme Python d'abord : l'interface est donc vraisemblablement l'essentiel du code TypeScript, mais rien ne le confirme explicitement. La dernière version publiée listée est v0.1.18, datée du 25 mars 2025, tandis que le dernier push sur la branche main est daté de juin 2026. Un écart de plus d'un an entre la dernière release et le dernier commit mérite une vérification avant tout engagement : soit le projet avance sans publier, soit l'activité est irrégulière. Le README ne fournit aucune indication sur les performances, la consommation mémoire ou le comportement sous charge. Il ne décrit pas non plus la procédure de migration de base entre deux versions, ce qui compte pour un outil qui persiste l'état des workflows en attente d'approbation. Ces silences ne sont pas des défauts en soi, mais ils délimitent ce qu'on peut affirmer.

Le cas où PySpur n'est pas le bon outil

Un canevas visuel impose un modèle mental : le graphe est la source de vérité, et le code s'y accroche. Si votre agent est une fonction de deux cents lignes avec une seule boucle, l'interface ajoute une couche de sérialisation entre vous et le comportement réel. Le débogage se fait alors en deux endroits, dans l'éditeur Python et dans l'interface, ce qui est exactement le problème que PySpur prétend résoudre. Autre cas défavorable : un pipeline déployé en production qui doit tourner sans intervention humaine et sans base de données d'état. Les breakpoints human-in-the-loop supposent un stockage persistant et un humain disponible pour approuver. Si votre contrainte est un traitement par lots nocturne sans supervision, cette fonctionnalité reste inutilisée et vous payez le coût d'une base et d'un serveur web pour rien. Le README ne prétend pas couvrir ces cas, mais il ne les exclut pas non plus.

Face à un framework d'orchestration sans interface

L'alternative la plus directe est un framework d'orchestration écrit en Python, où le graphe est décrit dans le code et où l'exécution se suit par des journaux et des traces. La différence n'est pas cosmétique. Dans un framework de ce type, la définition du workflow est un artefact versionnable, relu en diff lors d'une revue de code, et l'exécution ne dépend d'aucun serveur d'interface. PySpur déplace cette définition vers un état stocké en base et manipulé dans le navigateur. On gagne la visualisation des boucles et des branchements, la modification à chaud d'un noeud et la capture automatique des traces d'exécution des agents déployés. On perd la revue de diff sur la topologie du graphe, puisque celle-ci vit dans la base et non dans un fichier. Le choix se joue donc sur une question précise : votre équipe débugge-t-elle plus souvent en lisant un graphe qu'en lisant un diff ? Si la réponse penche vers le graphe, PySpur a un argument. Sinon, l'interface devient une dépendance supplémentaire à maintenir.

Coût de maintenance et licence

Le dépôt est publié sous Apache-2.0. Concrètement, vous pouvez lire, modifier et redistribuer le code, y compris dans un produit commercial, à condition de conserver les mentions de copyright, le fichier de licence et de signaler les fichiers modifiés. La licence inclut une clause de brevets. Ce paragraphe n'est pas un conseil juridique : faites relire le texte de la licence si la redistribution est au programme. Sur la maintenance, deux coûts se cumulent. Le premier est la base de données : passer de SQLite à PostgreSQL, comme le recommande le README, ajoute une dépendance d'infrastructure à provisionner et à sauvegarder. Le second est le suivi des versions. Le projet est en 0.1.x, donc en phase initiale, et rien dans le matériel fourni ne décrit une politique de compatibilité entre versions ni un chemin de migration pour les workflows déjà persistés. Pour un outil qui conserve l'état d'exécutions en pause, c'est le point à tester en premier sur une copie de vos données avant de le brancher sur quoi que ce soit d'important.

Conclusion éditoriale

PySpur convient aux équipes qui itèrent déjà sur des agents Python et veulent voir le graphe plutôt que de relire des logs. Il ne convient pas à qui cherche un orchestrateur de production sans interface, ni à un poste Windows, le README précisant que le développement sur PC n'est pas pris en charge. Avant d'adopter, vérifiez deux points : la configuration PostgreSQL dans le fichier .env, car le mode --sqlite est présenté comme moins stable, et la licence Apache-2.0 du dépôt, qui vous laisse relire et modifier le code mais vous impose de conserver les mentions de copyright et le texte de licence dans les redistributions.

Sources officielles

1. License: Apache-2.0
2. Project website
3. PySpur-Dev/pyspur on GitHub
4. README
5. Releases