Herausforderung
KI-Agenten leben heute in stark unterschiedlichen Umgebungen: als Dienste im Backend, als Werkzeuge in Entwickler-IDEs und als Begleiter auf mobilen Endgeräten. Jede dieser Umgebungen bringt eigene Sprachen, Laufzeit- und Verpackungsanforderungen mit, aber die eigentliche Agentenlogik — Modellzugriff, Werkzeugaufrufe, Zustand über mehrere Schritte — ist überall dieselbe.
Wer für jede Umgebung parallel entwickelt, endet mit drei oder vier voneinander abweichenden Implementierungen, die sich in Details unterscheiden und getrennt gepflegt werden müssen. Feinjustierungen am Prompt oder ein neues Werkzeug landen dann irgendwann nur in einer Version und driften auseinander.
AI Operator setzt an dieser Stelle an: ein gemeinsamer Baukasten, der Kernlogik, Werkzeugkatalog und Modell-Anbindung an einer Stelle hält und die Laufzeiten drumherum als eigenständige, aber kompatible Bausteine behandelt.
Ansatz
Vier Grundsätze prägen die Struktur:
- Polyglotter Monorepo — jede Sprache bekommt die Rolle, für die sie gebaut ist: Python für Modell- und Datenlogik, Go für performante Dienste, TypeScript für Oberflächen und geteilte Werkzeuge, Swift für den nativen Client.
- Kern getrennt von Laufzeit — die eigentliche Agentenlogik liegt in wiederverwendbaren Paketen, die Laufzeiten wählen aus.
- Werkzeuge sind erste Bürger — Werkzeugdefinitionen und -implementierungen leben im gemeinsamen Baukasten, nicht dupliziert pro Client.
- Ehrlicher Reifegrad — der Umfang ist in aktiver Entwicklung; die interne Dokumentation folgt dem Code, nicht umgekehrt.
Was wir gebaut haben
Monorepo-Struktur
Der Repository-Kopf gliedert sich in apps/, services/, packages/, infrastructure/, scripts/, docs/ und tests/. Diese Trennung erlaubt, ausführbare Anwendungen (apps/), lang laufende Dienste (services/) und geteilte Bibliotheken (packages/) unabhängig zu bauen und zu versionieren, ohne die geteilte Historie zu verlieren.
Go-Workspace
Ein go.work an der Wurzel bindet mehrere Go-Module in eine gemeinsame Workspace ein, ergänzt durch .golangci.yml als geteilte Linting-Konfiguration. So können Dienste parallel bearbeitet werden, ohne dass jedes Modul einzeln aus- und eingecheckt werden muss.
JavaScript/TypeScript-Ebene
package.json und pnpm-lock.yaml verwalten die Node-Seite mit pnpm-Workspaces. Oberflächen, geteilte Werkzeuge und Bibliotheken für Web-Clients leben unter packages/ und apps/.
Python-Kern
ruff.toml als Linter-Konfiguration und ein eigenes Wurzelverzeichnis für Python-Code trennen Modell- und Datenlogik sauber vom Rest. Diese Ebene enthält Modell-Anbindungen, Prompt-Bausteine und Werkzeugaufrufe.
Swift-Client
Ein nativer Client greift auf denselben Werkzeugkatalog zu und macht die Agentenlogik auf mobilen Endgeräten verfügbar — ohne die Web- oder Backend-Seite zu duplizieren.
Infrastruktur und Skripte
infrastructure/ und scripts/ bündeln Container-Definitionen, Deploy- und Wartungsskripte. Ein Makefile an der Wurzel fasst häufige Kommandos (Build, Test, Lint) zusammen.
Präsentation und interne Dokumente
presentation/ und docs/ enthalten interne Materialien zum Projektstand — bewusst getrennt vom externen Auftritt, damit Änderungen an der Doku nicht mit Code-Änderungen kollidieren.
Architektur
AI Operator ist ein polyglotter Monorepo: Vier Ökosysteme leben nebeneinander, verbunden durch geteilte Schnittstellen und einen gemeinsamen Werkzeugkatalog. Python trägt die Kernlogik rund um Modelle und Prompts, Go liefert Dienste mit klar definierten APIs, TypeScript stellt Oberflächen und geteilte Werkzeuge bereit, Swift bedient den mobilen Client.
Die Trennung apps/ ↔ services/ ↔ packages/ folgt einer bekannten Regel: packages/ enthält nur wiederverwendbare Bibliotheken ohne Nebeneffekte, services/ lang laufende Prozesse mit eigenem Deployment, apps/ konkrete Endanwendungen. Diese Grenzen halten die Abhängigkeitsrichtung sauber und verhindern, dass ein UI-Wechsel eine Backend-Bibliothek zwingt.
Der Go-Workspace (go.work) und pnpm-Workspaces (pnpm-lock.yaml) sorgen dafür, dass Änderungen über Modulgrenzen hinweg in einem Schritt gemacht werden können, ohne intermediäre Releases. .golangci.yml und ruff.toml halten die Codequalität in Go und Python auf einer geteilten Baseline.
Zahlen & Fakten
| Metrik | Wert |
|---|---|
| Sprachen im Repository | Python, TypeScript, Go, Swift (plus Shell, Makefile) |
| Struktur | Monorepo mit apps/, services/, packages/, infrastructure/, docs/, tests/ |
| Go-Workspace | go.work + .golangci.yml (geteilte Linting-Konfiguration) |
| JS/TS-Toolchain | pnpm + package.json (pnpm-Workspaces) |
| Python-Toolchain | Ruff (ruff.toml) |
| CI/Automatisierung | Makefile und scripts/ |
| Reifegrad | In aktiver Entwicklung — Funktionsumfang wächst schrittweise |
Was wir gelernt haben
Ein Monorepo diszipliniert die Sprachwahl. Wenn Python, Go, TypeScript und Swift im selben Repository leben, wird schnell sichtbar, welche Sprache für welche Aufgabe wirklich passt — und welche Doppelarbeit man sich mit einer schlechten Wahl einhandelt. Wir mussten früh entscheiden, wo Logik hin gehört, damit die Grenze zwischen den Ökosystemen scharf bleibt.
Werkzeugdefinitionen gehören in geteilte Pakete. Sobald mehrere Laufzeiten dieselben Werkzeuge aufrufen sollen, wird jeder Client, der sein eigenes Schema pflegt, zur Schuldenquelle. Der gemeinsame Werkzeugkatalog ist der wichtigste architektonische Hebel gegen Drift.
Aktive Entwicklung braucht ehrliche Dokumentation. Interne Dokumente in docs/ sind bewusst grob gehalten — sie beschreiben den Ist-Zustand, nicht einen idealisierten Endzustand. Das ist unbequem, aber es verhindert, dass neue Mitwirkende falschen Beschreibungen folgen.
Nächste Schritte
- Werkzeugkatalog konsolidieren und die Schnittstelle zwischen Python-Kern und Client-Laufzeiten stabilisieren.
- Test-Coverage in
tests/ausbauen, insbesondere für den Werkzeug-Katalog und die Kern-Agentenlogik. - Öffentliche Dokumentation entlang tatsächlich stabiler Bausteine, ohne den experimentellen Rest zu verbergen.
Verwandt
- Kontext: Über Alpine Ascent — der KI-Baukasten spiegelt unsere Arbeitsweise über mehrere Sprachen und Umgebungen.