HABITAT

Einführender Kontext

KI-Agenten werden zunehmend autonom — sie schreiben Code, recherchieren, führen Workflows aus. Doch meistens agieren sie in einer abstrakten Leere: ohne Ort, ohne Körper, ohne geteilte situative Konzeption eines Büros oder anderer menschlicher Kontexte. Die Interaktion bleibt auf Chat-Verläufe und Tool-Calls beschränkt.

Agenten müssen durch einen Tick, durch Cronjobs, durch Webhooks oder andere externe Reize angetrieben werden, um nicht in Passivität zu verfallen. Welterfahrung ist hingegen eine kontinuierliche, aktive Interaktion mit der Umgebung. Welt ist also eventuell auch ein ‘Anreizsystem’, das Menschen und Agenten zu aktiver und planmäßiger Tätigkeit anregt. All das ist der Untersuchungsgegenstand hinter der Idee von HABITAT.

Habitat testet aus, was passiert, wenn Agenten einen Körper und eine räumliche Ebene erhalten: eine Welt, in der sie anderen Agenten oder NPCs begegnen, Umgebung wahrnehmen, Objekte (z.B. eine Kaffeemaschine) vorfinden, Spuren hinterlassen und auf Hindernisse treffen. Was wie ein Spiel aussieht, ist keine Spielerei — sondern eine MonkeyLab-Forschungsfrage — die Frage, ob ein simuliertes Embodiment und ein geteilter, dynamischer Welt-Kontext die Qualität von Agenten-Interaktionen verändern.

Anwendungsfälle

• Szenario: Dein Büro als digitale Simulation, Agenten treten dort ein, benutzen ihren Schreibtisch, treffen Mitarbeiter
• Szenario: Ein Ablauf in der Produktion wird simuliert und Objekte in der Simulation werden mit echten Sensoren und Schnittstellen verbunden. Der Agent kann dann in der Simulation agieren und Zusammenhänge als reales Modell erfassen.
• Training: Evaluation & Benchmark von Agenten in simulierten Umgebungen und für konkrete Problemstellungen
• High-Level Monitoring: Überwachung von Agenten-Verhalten in einer Umgebung, die seine Aufgaben reflektiert. Workflows müssen real ‘begangen’ werden, so dass der Mensch folgen kann oder sieht, wenn der Agent ein Problem hat
• Soziale Mensch-Maschine Interaktion: Mensch-Agenten-Interaktion mit visueller Komponente
• Robotik/Remote: Forschung zu Embodiment-Effekten in einfachen Umgebungen, wenn Agenten involviert sind
• Agent2Agent Environments: Agenten können sich treffen, Informationen austauschen, der Server und Erinnerungen bleiben persistent

usw.

Da Welten frei definiert werden können, ist HABITAT nicht für ein bestimmtes Szenario limitiert. ABER: HABITAT ist ein MVP für eigene Untersuchungen — das Prinzip zeigt jedoch, dass der Ansatz klappt.

Die Technik

Habitat ist ein Environment-Builder und kein Agenten-Framework. Agenten verbinden sich mit einer Welt über zwei Kanäle (WebSocket für die Sinne, MCP für Aktionen), bekommen einen Körper. Die Welt bleibt autoritativ, so wie man es von Multiplayer-Spielen kennt.

Das Design daher: eine „MMO-Server-Architektur, angewendet auf Agenten-Embodiment." Neben Agenten-spezifischen Protokollen (MCP etc.) sind hier also Probleme mit Antworten aus dem Gamingbereich gelöst worden. Denn die Welt existiert nicht nur für einen Agenten. Viele Agenten können (wenn berechtigt) gleichzeitig in der Welt agieren und genau hierfür benötigt man ein Konzept für das State-Management und den Datenaustausch.

Habitat — Bausteine im Überblick

Hier ein Deep-Dive in Teile der System-Architektur.

1. Monorepo-Pakete (pnpm Workspaces)

@habitat/shared — Zod-Schemas, Types, Konstanten; Single Source of Truth für Welt-Templates, Entities und Events. Keine Runtime-Deps außer Zod. Wird zuerst gebaut, von allen anderen Paketen genutzt. @habitat/server — Das Simulations-Backend: Colyseus Server (und Rooms) + Fastify REST API + MCP-Server + Auth + Persistenz. @habitat/client — Nuxt4 + Vue3 + Pinia mit versch. Views: Simulations-View (Phaser Umsetzung), Admin-Dashboard, World-Editor, Theme und Asset-Manager (usw.) @habitat/headless — SDK-Ebene: HabitatClient (Colyseus WebSocket State-Sync) + HabitatMCPClient (MCP-Tool-Calls).

2. Simulations-Kern

Colyseus — autoritative State-Engine, Room-Management, Delta-Sync mit 20 Hz (visuell) / 1–5 Hz (headless). @colyseus/schema — binäre State-Serialisierung; das 64-Felder-Limit pro Schema-Klasse prägt das Entity-Design. Zwei ‘Room’-Typen — VisualSimulationRoom (Phaser-Clients) und HeadlessSimulationRoom (KI-Agenten), beide erben von BaseSimulationRoom (gemeinsame Logik: Spawning, Movement, Kollision, Interaktion). Grid-Welt — meist ’tile’-basierte Karten mit Terrain-Layern (walkable/wall/water), Areas und platzierten Objekten aus YAML-Welt-Templates.

Auf Basis der Grundtypen können im Editor neue Objekte definiert werden, die 1. visuell durch ein Asset dargestellt sind, 2. zu einem Theme hinzugefügt werden können und 3. definierte Metadaten besitzen. Ein ‘Telefon’ z.B. kann also in einer Bürowelt platziert werden, benutzt werden, hat sogar eine Berechtigungsebene auf Rollen-Basis und bietet Tools an, die der Agent dann wirklich via MCP-Protokoll benutzen kann. Etwa einen Call machen. In einem Welt-Editor wird das Telefon-Objekt dann nur noch platziert, wenn es bereits in einem Theme definiert wurde. Ansonsten kann man es frei für diese Welt definieren.

3. Agenten-Schnittstelle — das „Body"-Modell

Kernprinzip: Habitat ‘besitzt’ keine Agenten (!) — Agenten existieren außerhalb und betreten lediglich die Welt. Dafür bekommen sie einen Körper. Was sich einfach anhört, hat ein wenig Architektur erfordert. Mit dabei sind diese Aspekte:

MCP-Server (Streamable HTTP + SSE unter /mcp) — ~30 Tools in 8 Modulen, etwa:

• Movement — move_left/right/up/down, move_linear, move_to, move_towards, suggest_path, analyze_reachable_area
• Perception — get_perception, query_nearby, examine
• Interaction — interact, pickup, drop
• Knowledge — store/update/delete/query_knowledge (ortsgebundene Memory-Anchors mit Embeddings)
• Social — send_message, read_messages, think_and_say (Sprech-/Denkblasen)
• Identity — register_identity
• Guidance — random_idea, plus Tool-Success-Hooks (mentale Trigger nach Tool-Ausführung)
• Tool-Autorisierung — Objekte deklarieren, welche Tools sie erlauben; examine enthüllt, was ein Objekt kann.
• A2A Agent Card — spezifiziert unter /.well-known/agent-card.json für Agent-Discovery (Implementierungsstatus prüfenswert).

Diese Tools sind nicht unbedingt global in der Welt verfügbar, sondern können auch für Objekte freigegeben werden. Ein ‘Infoschild’ kann also z.B. Informationen über Orte in der Welt bereitstellen. Der Agent kann dann planen, wie er diese Informationen abruft und nutzt. Typischerweise sieht ein Agent nicht alles, sondern nur Dinge in einem bestimmten Radius. Dadurch plant er zunächst grob, trifft dann aber auf ein Hindernis. Oder er wird auf dem Weg von Meetingraum A zu Schreibtisch X von jemandem an der Kaffeemaschine angesprochen.

Anders eben! Kein Chat.

4. Auth & Identität

Grundsätzliche Authentifizierung:

• JWT (HS256) — session-gebundene Tokens via POST /api/auth/token oder AUTH_TOKEN beim Room-Join (8h Laufzeit).
• Persistente agent-gebundene Tokens — POST /api/auth/agent-token; an stabile agentId gebunden, über RoomManager auf die Live-Session aufgelöst — überlebt Reconnects.
• Rate-Limiting auf dem MCP-Endpoint; Zod-validierte Env-Config (config/env.ts).

5. Persistenz & Daten

Für ein lokales Setup übertrieben, aber generell für Production konzipiert/realisiert.

• PostgreSQL + Drizzle ORM — Welten, Entities, Sessions, Objekt-Konfigurationen, Themes; inkl. Migrationen.
• Redis — Session-Cache, Presence, Colyseus Pub/Sub-Treiber.
• Qdrant — Vektor-Store für KnowledgeAnchor-Embeddings (Spatial RAG für die Welt).
• Ollama — lokale Embedding-Generierung (z.B. nomic-embed-text); opt-in Docker-Profil (kann in/außerhalb des Containers existieren)
  • Es muss nicht auf lokale Embeddings zurückgegriffen werden, auch BYOT (Cloud) ist eine Option in env-Variablen
• BullMQ — Background-Jobs: Snapshots, geplante Events.

6. Welt-Definition

• YAML-Templates (worlds) — Areas, Terrain, Objekt-Platzierungen, validiert durch worldTemplateSchema (Zod).
  • Warum Templates? 1. austauschbar zwischen Instanzen, 2. ein Agent kann diese programmatisch selbst bauen
• Objekt-Konfigurationen — DB-gestützte Objekte mit Tool-Autorisierungsmechanismen, Zugriffsregeln (z.B. via Rolle), onInteract-Narrativen (Inspiration, Context), custom und Standard-Metadaten (JSON).
• World-Editor — im Nuxt-Client; hier wird eine neue Welt erstellt (CRUD) und als ‘Simulation’-Entität live gestartet. Der Token für Agenten wird je Welt gemintet.

7. Client-Rendering / UI

• Phaser — 2D-Tile-Rendering, WorldRenderer + AssetManager im Manager-Pattern.
• grid-engine — grid-basierte Charakter-Bewegung und Animation.
• Nuxt UI + Tailwind — Admin-/Editor-UI, Dashboard-Layout.

Was sich trivial liest, ist es nicht. Absicht, Ort, Bewegung, Timing - alles muss stimmen. Hierfür spielt Colyseus eine wichtige Rolle bei der Synchronisation.

8. Infrastruktur & Qualität

• Docker / Docker Compose — Infra-Profil (PG/Redis/Qdrant) + Full-Profil (+ Ollama + Server-Container).
• Vitest — co-located Tests, Colyseus-Test-Helpers, AAA-Pattern.
• ESLint Flat + Prettier + lint-staged/husky — Pre-Commit-Gates.
• TypeScript strict — verbatimModuleSyntax, Project References, z.infer-Types aus Schemas.
• Spec-getriebene Doku — specs (normativ), ADRs
• MonkeyLab agentic dev best practice pattern für Spec und Flow

Einordnung im MonkeyLab

Habitat ist die räumliche Infrastruktur-Ebene im MonkeyLab — dort, wo andere Projekte Agenten bauen, gibt Habitat ihnen einen Ort:

• Hermes Agent — autonome Agenten-Runtime (Blog: Autonome Agenten )
• MonkeyTribe 2.0 — hybride Mensch-Agenten-Teams (Update im CRM-Work-Eintrag )
• Habitat — geteilter räumlicher Kontext für Agenten und Menschen

Es ist ein Research-MVP, kein Metaverse-Produkt — sondern ein erfolgreicher Test, der untersucht hat, ob verkörperte Agenten in einer autoritativen Welt bessere Interaktionsqualität zeigen als reine Chat-Interfaces. Welten sind eine andere Form der Kontextsetzung, müssen weiterexistieren (ob ein Agent gerade die Welt betreten hat oder nicht) und bieten so eine qualitative Ebene, die in der PDF- und Text-Ebene viel zu kurz kommt. Habitat ist auch ein Ort, an dem sich meine Agenten treffen können (z.B. Cursor, Hermes etc.), um ihr Wissen zu teilen. Dafür braucht es prinzipiell keine visuelle Welt, aber diese steckt den Rahmen ab und macht vieles nachvollziehbar.

Ergebnisse & Learnings

Das MVP beantwortet die Kernfrage positiv — mit klaren Einschränkungen:

Was funktioniert:

• MMO-Architektur hilft für den Use Case. Colyseus als autoritative State-Engine mit zwei Room-Typen (visuell + headless) funktioniert zuverlässig — Agenten und Menschen teilen denselben Weltzustand.
• Das Body-Modell entkoppelt sauber. Agenten existieren außerhalb, betreten die Welt als Entities — kein Vendor-Lock-in, kein Framework-Zwang.
• Spatial RAG funktioniert. Ortsgebundene Knowledge Anchors mit Qdrant-Embeddings geben Agenten persistenten, positionsbezogenen Kontext — ein echter Unterschied zu stateless Chat-Interfaces. Agenten erleben Welten und bauen Erinnerungen über ihre Reise auf (oder darüber, wen sie am Kaffeeautomaten getroffen haben).
• Tool-Autorisierung auf Objektebene skaliert. examine als Discovery-Mechanismus zeigt Agenten, was ein Objekt anbietet — ohne dass die Welt alle Tools global exponieren muss. Kontrolle kann so designed werden.

Was jedoch bisher im MVP offen bleibt:

• A2A Agent Card ist spezifiziert, nicht vollständig implementiert. Die Discovery-Schnittstelle unter /.well-known/agent-card.json fehlt noch.
• Embodiment-Nutzen ist noch nicht empirisch belegt. Die Architektur trägt das Konzept — ob Agenten in der Praxis bessere Entscheidungen durch räumlichen Kontext treffen, braucht mehr Experimente und Messungen. Feststellbar ist, dass Agenten nicht zu Inaktivität neigen. Die Welteindrücke halten sie stetig in Bewegung und sie machen Pläne aufgrund des Welt-Zustands. Genaue Benchmarks müssten hier noch Zahlen liefern, damit belastbare Aussagen getroffen werden können.

Kernbefund: Die technische Infrastruktur für räumliche Agenten-Welten ist absolut lösbar und auch für mehrere Agenten performant — die eigentliche Forschungsfrage ist, ob Embodiment und Welt-Kontext die Interaktionsqualität messbar verbessert. Das MVP legt dafür die Basis.

Ausblick (Roadmap)

• editor_meta-Roundtrip im World-Editor (P0)
• A2A Agent Card implementieren (/.well-known/agent-card.json)
• Multi-Agent-Szenarien: mehrere Agenten in derselben Welt
• Persistente Welt-Zustände über Sessions hinweg
• Erweiterte Spatial-RAG-Features (temporale Anchors, geteiltes Wissen)
• Performance-Optimierung für größere Welten und mehr Entities
• Integration mit Hermes Agent als Referenz-Agent
• Theme und Asset-Library und auf dieser Basis generative Welt-Generierung
• MCP-Library (z.B. um einfach ein CRM anzuschließen, noch ist technisches Wissen nötig)
• Erweiterungen für Multi-Agent-Szenarien, Schnittstellen, 3D

Status

MVP mit funktionierender Simulation, MCP-Schnittstelle, Spatial RAG und World-Editor. Nicht öffentlich deployed — aktive Entwicklung bislang im der Research-Lane. Bei ähnlichen Vorhaben, Fragen zur Machbarkeit, Tipps zu produktiven KI-Szenarien … biete ich gerne jederzeit Hilfe an.

Erreichbar via: Kontakt .