PySpur: Agenten-Workflows als Graph im Browser, mit Python als Erweiterungspunkt

Drei konkrete Probleme, die die README benennt

Die Einleitung der README nennt drei Schmerzpunkte: Prompt Hell, also stundenlanges Nachjustieren von Prompts, Workflow Blindspots, also fehlende Sicht auf das Zusammenspiel einzelner Schritte, und Terminal Testing Nightmare, das manuelle Lesen roher Ausgaben und JSON-Parsing von Hand. Das sind keine abstrakten Kategorien, sondern Beobachtungen aus einem eigenen Projekt: Das Team beschreibt einen Grafikdesign-Agenten, der Anfang 2024 gestartet wurde und schnell auf Tausende Nutzer kam, dessen Zuverlässigkeit aber schwer zu prüfen war. Die Zielgruppe sind damit AI-Ingenieure, die bereits Agenten betreiben und deren Fehlersuche und Iteration beschleunigen wollen. Wer noch nie einen Agenten gebaut hat, bekommt hier keinen Einstieg in die Grundlagen, sondern eine Arbeitsumgebung für ein Problem, das man schon kennt.

Der Graph als Datenmodell, Python als Erweiterungspunkt

Aus dem Repository geht hervor, dass PySpur in TypeScript geschrieben ist, während die README den Erweiterungsmechanismus in Python verortet: Neue Nodes entstehen laut Feature-Liste durch eine einzelne Python-Datei. Der visuelle Editor und die Ausführungsschicht sind also getrennte Teile, und die Schnittstelle zwischen beiden ist die Node-Definition. Der Ablauf, den die README als vier Schritte beschreibt, ist: Testfälle definieren, den Agenten in Python-Code oder über die UI bauen, iterieren, deployen. Bemerkenswert ist die Reihenfolge. Die Testfälle stehen vor dem Bauen, nicht danach. Das ist eine Designentscheidung, die den Graphen nicht als Skizze behandelt, sondern als Artefakt, gegen das bewertet wird. Die Evals-Funktion greift das auf: Sie bewertet Agenten laut README auf real-world datasets. Wie Testfälle intern gespeichert werden und ob sie versioniert sind, lässt sich aus dem Material nicht belegen.

Human-in-the-Loop als pausierender Zustand, nicht als Callback

Der interessanteste Mechanismus in der README ist der Human-in-the-Loop-Breakpoint. Die Beschreibung ist kurz, aber präzise: Breakpoints pausieren den Workflow, wenn sie erreicht werden, und setzen ihn fort, sobald ein Mensch zustimmt. Das setzt voraus, dass der Ausführungszustand über die Wartezeit hinweg persistiert wird. Genau deshalb empfiehlt die README, in der .env-Datei eine PostgreSQL-Instanz zu konfigurieren, weil der Standard mit SQLite zwar startet, aber laut README weniger stabil ist. Die Empfehlung ist kein Nebensatz, sondern folgt direkt aus der Architektur: Wer Freigabepunkte produktiv nutzt, hält offene Zustände über unbestimmte Zeit, und dafür ist ein einzelner SQLite-Dateipfad die schwächere Wahl. Diese Kopplung zwischen Feature und Datenbankwahl wird in der README nicht explizit ausgesprochen, sie ergibt sich aber aus dem Zusammenspiel der beiden Absätze.

Installation: pip, init, serve --sqlite

Der Quick Start der README ist knapp und vollständig. Voraussetzung ist Python 3.11 oder höher. Dann folgen drei Befehle: pip install pyspur, danach pyspur init my-project und cd my-project, wobei init ein neues Verzeichnis mit einer .env-Datei anlegt, und schließlich pyspur serve --sqlite. Der Server läuft standardmäßig unter http://localhost:6080. API-Schlüssel lassen sich auf zwei Wegen hinterlegen: über den Tab API Keys in der Oberfläche oder manuell in der .env-Datei mit anschließendem Neustart über pyspur serve. Für die Entwicklung nennt die README zwei Wege: den Dev-Container unter .devcontainer/devcontainer.json für Cursor oder VS Code mit der Dev-Containers-Erweiterung, oder den manuellen Start über docker compose -f docker-compose.dev.yml up --build -d. Der manuelle Weg erfordert laut README zusätzliche Konfiguration und deckt nicht alle Funktionen des Dev-Containers ab.

Die Plattformgrenze steht in der README, nicht im Kleingedruckten

Eine Einschränkung ist ungewöhnlich deutlich formuliert: Die Entwicklungsanleitung gilt für Unix-artige Systeme, Entwicklung unter Windows wird nicht unterstützt. Das betrifft nicht nur den Dev-Container, sondern den dokumentierten Entwicklungspfad insgesamt. Wer auf Windows arbeitet, muss auf WSL oder eine Linux-Umgebung ausweichen, ohne dass die README dafür eine Anleitung liefert. Ein zweiter Punkt betrifft die Reife: Die letzten Releases in den Materialien sind v0.1.18, v0.1.17 und v0.1.16, alle aus März 2025. Der letzte Push ins Repository datiert auf Juni 2026. Zwischen den veröffentlichten Versionen und der aktuellen Branch-Spitze liegt also ein Zeitraum, der nicht durch Releases abgedeckt ist. Wer auf eine gepinnte Version setzt, arbeitet mit einem Stand, der deutlich älter ist als main. Ob und wie die Releases gepflegt werden, lässt sich aus dem Material nicht ableiten.

RAG und Tools: Bausteine mit sichtbaren Grenzen

Die RAG-Unterstützung ist in der README in zwei Schritte zerlegt: erst eine Document Collection mit Chunking und Parsing, dann ein Vector Index mit Embedding und Upsert in eine Vector DB. Das ist eine saubere Trennung, weil Chunking-Entscheidungen und Embedding-Modell unabhängig voneinander geändert werden können. Die Feature-Liste nennt mehr als 100 LLM-Provider, Embedder und Vector DBs, ohne einzelne Anbieter zu belegen. Bei den Tools werden Slack, Firecrawl.dev, Google Sheets und GitHub namentlich genannt, jeweils mit dem Zusatz and more. Was hier fehlt, ist eine Aussage darüber, wie ein Tool-Node Fehler behandelt oder wie Retries konfiguriert werden. Die README beschreibt die Existenz der Bausteine, nicht ihr Verhalten im Fehlerfall. Für einen Werkzeugkasten, der explizit auf Zuverlässigkeit zielt, ist das eine Lücke im Dokument, nicht zwingend im Code.

Wo PySpur nicht das richtige Werkzeug ist

PySpur ist ein Server mit Oberfläche, Datenbank und Deploy-Pfad. Wer einen Agenten als Bibliothek in eine bestehende Anwendung einbetten will, ohne einen separaten Dienst zu betreiben, trägt hier mehr Betriebsaufwand als nötig. Dasselbe gilt für sehr einfache Abläufe: Ein einzelner Prompt mit einem Tool-Aufruf braucht keinen Graphen, keine Datenbank und keine Freigabepunkte. Der Vergleich mit einem codezentrierten Framework wie LangGraph liegt nahe, und der Unterschied ist struktureller Natur. LangGraph modelliert den Ablauf als Code, den man in Tests und Code-Reviews behandelt. PySpur modelliert ihn als Graph in einer Oberfläche und bietet Python nur für neue Nodes. Das ist ein Vorteil, wenn Nicht-Programmierer am Ablauf mitarbeiten oder wenn man den Datenfluss sehen will. Es ist ein Nachteil, wenn der Graph durch Diffs, Branches und Merge-Konflikte gehen soll. Wie der Graph exportiert oder versioniert wird, sagt die README nicht.

Lizenz und Wartungskosten

PySpur steht unter Apache-2.0. Das erlaubt kommerzielle Nutzung, Modifikation und Weitergabe, verlangt aber die Beibehaltung der Lizenzhinweise und enthält eine ausdrückliche Patentgewährung sowie eine Klausel zu Marken. Wer den Code verändert und weiterverteilt, muss die Änderungen kennzeichnen. Das ist keine Rechtsberatung, sondern die Zusammenfassung dessen, was die Lizenzkennung im Repository angibt. Zu den Wartungskosten lässt sich aus dem Material nur begrenzt etwas sagen. Der Update-Pfad über pip install pyspur ist einfach, aber die README dokumentiert keinen Migrationsweg für Datenbankschemata zwischen Versionen. Wer die empfohlene PostgreSQL-Konfiguration nutzt, sollte vor einem Upgrade prüfen, ob Migrationen mitgeliefert werden. Ob das der Fall ist, geht aus dem vorliegenden Material nicht hervor.

Redaktionelles Fazit

Wer agentische Abläufe mit Schleifen, RAG und menschlichen Freigabepunkten baut und dafür einen visuellen Graphen statt reiner Skripte braucht, findet in PySpur nach der README-Beschreibung einen passenden Rahmen. Wer eine reife, ausschließlich codebasierte Bibliothek ohne Serverkomponente sucht, ist hier falsch. Vor dem Einsatz zu prüfen: ob eine PostgreSQL-Instanz statt SQLite konfiguriert ist, ob die Python-Version mindestens 3.11 ist und ob die Entwicklungs- und Deployment-Pfade aus der README auf der eigenen Plattform laufen, denn Windows wird für die Entwicklung ausdrücklich nicht unterstützt.

Offizielle Quellen

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