II-Agent: ein Apache-2.0-Agentenframework mit Docker-Stack und BYOK
II-Agent: a new open-source framework to build and deploy intelligent agents
Auf einen Blick
- Was ist das?
- II-Agent kombiniert Backend, Frontend, Postgres, Redis und MinIO zu einem selbst hostbaren Agenten-Stack. Der Beitrag zeigt, wie der Start über make setup und make dev-all läuft, wo die Modellkonfiguration liegt und für wen sich der Betrieb lohnt.
- Für wen ist es gedacht?
- II-Agent passt zu Teams, die den kompletten Agenten-Stack selbst betreiben wollen und Docker, uv sowie Node.js ohnehin im Einsatz haben. Wer nur eine einzelne Bibliothek in eine bestehende Python-Anwendung einbinden möchte, greift mit einem reinen SDK-Ansatz wie LangChain oder LlamaIndex deutlich schlanker zu.
- Darf ich es kommerziell nutzen?
- Ja. Apache-2.0 ist eine freizügige Lizenz: Sie dürfen darauf aufbauende Software nutzen, verändern und verkaufen, solange Sie die Urheberrechts- und Lizenzhinweise beibehalten.
- Wird es noch gepflegt?
- Ja. Die letzten Commits kamen vor 30 Tagen.
- In welcher Sprache ist es geschrieben?
- Hauptsächlich Python, laut der Sprachstatistik von GitHub.
Die Antworten beruhen auf den GitHub-Daten des Projekts (zuletzt abgeglichen am 15. September 2026) und auf unserer Analyse. Sie sind keine Rechtsberatung.
TIEFGEHENDE OPEN-SOURCE-ANALYSE
Welches Problem II-Agent adressiert und für wen
Viele Agentenprojekte liefern eine Bibliothek, manchmal eine CLI, und überlassen den Rest dem Anwender. II-Agent geht den umgekehrten Weg: Das Repository beschreibt ein Framework zum Bauen und Betreiben intelligenter Agenten, das als vollständiger Dienst ausgeliefert wird. Dazu gehören laut README ein Backend, ein Frontend, PostgreSQL, Redis und MinIO als S3-kompatibler Speicher. Wer den Agenten produktiv nutzen will, bekommt also nicht nur die Agentenlogik, sondern auch die Infrastruktur, auf der sie läuft.
Die Zielgruppe benennt das README explizit: Solo-Entwickler, Forschungsteams und Unternehmen, die interne Werkzeuge bauen. Der Anspruch ist, dass man das Projekt ausführen, forken und erweitern kann, ohne einen Anbieter zu wechseln. Die Abkürzung BYOK steht für bring your own API keys, das heißt, die Modellzugänge und damit die Kostenhoheit bleiben beim Betreiber. Für Teams, die aus Compliance- oder Kostengründen keinen gehosteten Agentendienst einsetzen dürfen, ist das der eigentliche Kaufgrund.
Die Funktionsliste ist breit: mobile Anwendungen und Websites aus einem kurzen Prompt, illustrierte Bilderbücher, Video- und Bildgenerierung, Recherche in zwei Tiefen, Dokumentenverarbeitung für PDF, Excel, Word und PowerPoint sowie Integrationen für Gmail, Slack, GitHub, Notion, Google Calendar, Discord, Dropbox und Canva. Diese Breite ist eine Designentscheidung, die später zum Tragen kommt, weil sie den Betriebsaufwand mitbestimmt.
Aufbau: Backend, Frontend und drei Infrastrukturdienste
Aus dem Repository-Aufbau und den Make-Targets lässt sich der Datenfluss recht genau ablesen. Der Backend-Prozess lauscht auf Port 8000, das Frontend auf Port 1420 im Standardstart. PostgreSQL läuft auf 5432 und hält den persistenten Zustand, Redis auf 6379 übernimmt die Aufgabe, die üblicherweise für kurzlebige Zustände und Warteschlangen vorgesehen ist. MinIO stellt auf Port 9001 eine S3-kompatible Oberfläche bereit, mit den voreingestellten Zugangsdaten minioadmin/minioadmin, und dient als Ablage für Dateien, die im Verlauf eines Agentenlaufs entstehen.
Bemerkenswert ist, dass die drei Infrastrukturdienste als eigene Make-Targets adressierbar sind. make infra startet nur Postgres, Redis und MinIO, ohne Anwendungscode. Das ist nützlich, wenn das Backend lokal in einer virtuellen Umgebung laufen soll, während die Abhängigkeiten im Container bleiben. make backend-dev und make frontend-dev starten die beiden Anwendungsteile getrennt, was den Entwicklungszyklus verkürzt. Ein durchgängiger Start erfolgt über make dev-all.
Für den Produktivbetrieb existiert ein zweiter Weg über Docker Compose. Die Datei docker/.stack.env.example wird nach docker/.stack.env kopiert und mit eigenen Zugangsdaten befüllt, danach startet make stack den gesamten Stack. Damit läuft alles in Containern, ohne dass lokal Python oder Node.js installiert sein muss. Das ist der Pfad, den man auf einem Server wählen würde, nicht den Entwicklungsstart.
Inbetriebnahme: von make setup bis model_configs.yaml
Die Installation beginnt mit dem Klonen des Repositories und dem Wechsel in das Verzeichnis. Danach folgt make setup, das laut README die .env-Dateien anlegt und Abhängigkeiten installiert. Voraussetzung sind Docker, uv, das über curl -LsSf https://astral.sh/uv/install.sh | sh installiert wird, sowie Node.js mit npm.
Der zweite Schritt ist die Modellkonfiguration, und hier gibt es zwei Wege. Der erste setzt die Variable MODEL_CONFIGS im .env als Inline-JSON, zum Beispiel mit einem Objekt, das model_id, provider, api_key, display_name und is_default enthält. Der zweite Weg nutzt eine YAML-Datei: model_configs.example.yaml wird nach model_configs.yaml kopiert, die Schlüssel werden eingetragen, und im .env wird MODEL_CONFIGS_FILE=model_configs.yaml gesetzt. Wer mehrere Provider parallel betreiben will, fährt mit der YAML-Variante besser, weil die JSON-Variante in einer Umgebungsvariable schnell unübersichtlich wird.
Als Provider nennt das README OpenAI, Anthropic und Google, mit Beispielmodellen wie gpt-5.4, claude-opus-4-6 und gemini-3.1-pro-preview. Anthropic und Google lassen sich laut Dokumentation sowohl über die direkte API als auch über Vertex AI ansprechen; die Beispieldatei führt zusätzlich Azure und selbst gehostete Modelle auf. Zum Start gehört außerdem make db-migrate, das die Datenbankschemata anlegt. Für die tägliche Arbeit sind make lint, make format und make test vorgesehen, die Backend und Frontend gemeinsam behandeln.
Modellwahl als Laufzeitentscheidung
Die Trennung von MODEL_CONFIGS und MODEL_CONFIGS_FILE ist mehr als Konfigurationskosmetik. Sie erlaubt, Modelle zu deklarieren, ohne die Anwendung neu zu bauen, und mehrere Einträge mit unterschiedlichen Anbietern nebeneinander zu halten. Das README nennt als Funktion ausdrücklich, dass man den Anbieter mitten in einem Gesprächsverlauf wechseln kann. Technisch bedeutet das, dass die Modellkennung nicht fest im Agentenkern verdrahtet ist, sondern pro Anfrage aufgelöst wird.
Der Preis dafür ist Konfigurationsdisziplin. Jeder Eintrag braucht einen api_key, und diese Schlüssel liegen in einer Datei, die im Repository-Verzeichnis neben dem Code steht. Wer model_configs.yaml versehentlich committet, veröffentlicht Zugangsdaten. Das .env ist im Beispiel als Vorlage angelegt, was nahelegt, dass beide Dateien in .gitignore gehören. Ob das tatsächlich so ist, lässt sich aus dem vorliegenden Material nicht bestätigen; das sollte man vor dem ersten Commit selbst prüfen.
Ein zweiter Punkt betrifft die Modellbezeichnungen. gpt-5.4, claude-opus-4-6 und gemini-3.1-pro-preview sind Beispiele aus der Dokumentation. Solche Kennungen ändern sich bei den Anbietern regelmäßig, und ein veralteter Eintrag führt nicht zu einem Konfigurationsfehler beim Start, sondern zu einem Fehler erst im Lauf. Wer den Stack längerfristig betreibt, sollte die Modellliste als gepflegte Ressource behandeln, nicht als einmalig ausgefülltes Formular.
Grenzen: Betriebsgewicht und die Frage der Wartung
Der offensichtlichste Nachteil ist das Gewicht. Ein Agent, der drei Infrastrukturdienste, ein Backend und ein Frontend benötigt, ist für eine einzelne Automatisierungsaufgabe zu viel. Wer nur einen Agenten mit Werkzeugzugriff in ein bestehendes Python-Programm einbetten will, zahlt hier für Fähigkeiten, die er nicht nutzt: Oberfläche, Objektspeicher, Datenbankmigrationen. Das ist kein Fehler des Projekts, sondern eine Folge des Anspruchs, eine vollständige Anwendung zu sein.
Die Wartungslage lässt sich nur begrenzt beurteilen. Die Release-Historie zeigt v0.2 im Juni 2025, v0.3 im Juli und v0.4 Ende Juli 2025, also einen kurzen Abstand zwischen den Versionen. Der letzte Push liegt laut Repository-Metadaten im August 2026. Aus diesen Angaben allein folgt keine Aussage über die Qualität der Pflege; sie zeigen nur, dass das Projekt über einen längeren Zeitraum berührt wurde. Wer auf einen stabilen Stand angewiesen ist, sollte die Änderungen zwischen den Tags selbst durchsehen, statt sich auf die Versionsnummern zu verlassen.
Ein weiterer wunder Punkt ist die Breite der Integrationen. Gmail, Slack, GitHub, Notion, Google Calendar, Discord, Dropbox und Canva sind einzeln aufgeführte Anbindungen. Jede davon hängt an einer fremden API mit eigenen Kontingenten und eigenen Änderungen. Das README macht keine Angaben dazu, wie diese Anbindungen getestet oder versioniert werden. In der Praxis ist das der Teil, der am ehesten bricht, und man sollte vor dem Rollout genau die Integrationen prüfen, die man wirklich braucht, statt sich auf die Liste zu verlassen.
Alternative: SDK statt Anwendung
Der naheliegende Vergleich ist ein Agenten-SDK wie LangChain oder LlamaIndex. Der Unterschied liegt nicht im Funktionsumfang, sondern in der Form. Ein SDK ist eine Bibliothek, die man in eine bestehende Anwendung importiert; sie bringt keine Ports, keine Datenbank und keine Oberfläche mit. Man entscheidet selbst, wo der Zustand liegt und wie die Ausführung skaliert wird. Dafür muss man diese Entscheidungen auch selbst treffen, und genau das nimmt II-Agent einem ab.
Konkret heißt das: Bei einem SDK schreibt man die Schleife aus Modellaufruf, Werkzeugausführung und Ergebnisrückgabe in eigener Verantwortung, oft in wenigen Dutzend Zeilen. Bei II-Agent ist diese Schleife Teil des Backends, und die Ergebnisse landen in Postgres sowie in MinIO. Das ist bequemer, solange die mitgelieferte Struktur zur eigenen Anwendung passt. Sobald man eine andere Persistenz oder ein anderes Ausführungsmodell braucht, wird das Framework zum Hindernis, weil man gegen seine Annahmen arbeitet.
Ein zweiter Unterschied betrifft die Modellverwaltung. Ein SDK ruft in der Regel genau das Modell auf, das man im Code übergibt. II-Agent verwaltet eine Liste von Modellen in einer Konfigurationsdatei und löst sie zur Laufzeit auf. Für Teams, die mehrere Anbieter vergleichen oder ausfallsicher betreiben wollen, ist das ein Vorteil. Für Teams mit genau einem Modell und einer festen Preisvereinbarung ist es zusätzliche Indirektion ohne Gegenwert.
Kosten, Lizenz und was vor dem Einsatz zu klären ist
Die Lizenz ist Apache-2.0, was kommerzielle Nutzung, Änderung und Weitergabe erlaubt, solange die Lizenzbedingungen und Hinweise erhalten bleiben. Das README formuliert den Anspruch, dass es keine Blackbox und keine Anbieterbindung gibt. Die Modellkosten liegen vollständig beim Betreiber, weil die Schlüssel über MODEL_CONFIGS oder model_configs.yaml eingetragen werden. Eine Aussage über die Höhe dieser Kosten lässt sich aus dem Material nicht ableiten, und das README macht dazu auch keine Angaben.
Der eigentliche Aufwand liegt im Betrieb. PostgreSQL, Redis und MinIO müssen gesichert, aktualisiert und überwacht werden. Die Standardzugangsdaten von MinIO sind minioadmin/minioadmin, was für eine lokale Entwicklungsumgebung gedacht ist und vor jedem erreichbaren Deployment geändert werden muss. Dasselbe gilt für die Ports 8000, 1420, 5432, 6379 und 9001: Wer den Stack auf einem Server betreibt, braucht eine Vorstellung davon, welche davon nach außen sichtbar sein sollen.
Upgrades haben zwei Ebenen. Auf der Anwendungsebene sind es die Tags v0.2 bis v0.4 und die Migrationen über make db-migrate. Auf der Infrastrukturebene sind es die Container-Images hinter make stack-build. Beide sollten zusammen aktualisiert werden, weil eine neue Anwendungsversion ein geändertes Schema erwarten kann. Für die Modellkonfiguration gilt dasselbe wie für jede andere Konfiguration: Sie ist Teil des Deployments und nicht ein einmaliger Einrichtungsschritt. Wer das akzeptiert, bekommt einen vollständig selbst kontrollierten Agenten-Stack; wer es nicht will, ist mit einer Bibliothek besser bedient.
Redaktionelles Fazit
II-Agent passt zu Teams, die den kompletten Agenten-Stack selbst betreiben wollen und Docker, uv sowie Node.js ohnehin im Einsatz haben. Wer nur eine einzelne Bibliothek in eine bestehende Python-Anwendung einbinden möchte, greift mit einem reinen SDK-Ansatz wie LangChain oder LlamaIndex deutlich schlanker zu. Vor dem Rollout sollte man prüfen, ob make setup die Dateien .env, frontend/.env und model_configs.yaml korrekt aus den Beispielen erzeugt, ob MODEL_CONFIGS beziehungsweise MODEL_CONFIGS_FILE die vorgesehenen Provider enthält und ob die Migrationen über make db-migrate gegen die eigene Postgres-Instanz durchlaufen.
Community-Notizen