Der Edge Connector ist eine verwaltete Runtime, die die nara-Plattform mit deinen lokalen und On-Premises-Systemen verbindet. Er läuft als schlanker Daemon auf deiner Infrastruktur und hält deine Umgebung mit nara verbunden. So können Agents Tools gegen Ressourcen in deinem Netzwerk ausführen — Datenbanken, interne APIs, lokale Dateisysteme und andere Dienste, die nicht öffentlich erreichbar sind.
Der Edge Connector sitzt zwischen der nara-Plattform und deinen internen Systemen. Wenn ein Agent ein EDGE-Tool ausführen muss, läuft die Anfrage über folgenden Pfad:
Webapp / Agent | v nara Platform | v Edge Connector (deine Infrastruktur) | v Deine Systeme (Datenbanken, APIs, Dienste)Der Agent fordert eine Tool-Ausführung an. Während einer Konversation stellt der Agent fest, dass er ein Tool mit dem Ausführungstyp EDGE aufrufen muss.
Die Plattform leitet den Aufruf weiter. nara sendet die Anfrage an die Edge-Connector-Instanz, die dieses Tool registriert hat.
Der Edge Connector führt lokal aus. Der Edge Connector lädt die entsprechende Tool-Implementierung und führt sie gegen deine lokale Infrastruktur aus.
Das Ergebnis fließt zurück zum Agent. Das strukturierte Ergebnis wird durch die Plattform zurück an den Agent geliefert und in die Konversation eingebunden.
Der Edge Connector unterstützt zwei verschiedene Deployment-Modi, die jeweils auf unterschiedliche Einsatzzwecke zugeschnitten sind.
Desktop-Modus
Interaktiver Modus mit einem System-Tray-Icon. Gedacht für einzelne Arbeitsplätze, an denen sich ein Benutzer per Browser-OAuth authentifizieren und den Connector-Status visuell überwachen möchte. Das System Tray bietet Login, Statusanzeigen und eine Beenden-Aktion.
Server-Modus
Headless-Modus für Produktions-Deployments. Authentifiziert sich über die Umgebungsvariablen
DEPLOYMENT_ID und DEPLOYMENT_SECRET. Kein System Tray, keine interaktiven Eingaben. Ideal
für Dauerserver, Container und CI/CD-Umgebungen.
Das Verständnis dieser Kernkonzepte hilft dir, dich in der restlichen Edge-Connector-Dokumentation zurechtzufinden.
Bundles — Ein Bundle ist eine versionierte, paketierte Sammlung von Tool-Implementierungen. Wenn du eigenen Tool-Code schreibst, verpackst du ihn in ein Bundle (ein .tgz-Archiv mit kompiliertem JavaScript und einem Manifest) und lädst es auf die nara-Plattform hoch. Bundles werden bei jedem Upload automatisch versioniert.
Deployments — Ein Deployment ist eine benannte Umgebung, die eine laufende Edge-Connector-Instanz oder eine Gruppe von Instanzen repräsentiert. Jedem Deployment kann ein bestimmtes Bundle zugewiesen werden, das steuert, welche Tool-Implementierungen es ausführt. Deployments werden über das Admin-Panel oder die CLI verwaltet.
Implementierungen — Implementierungen sind die eigentlichen Code-Dateien, die du schreibst, um EDGE-Tool-Ausführungen zu behandeln. Jedes Tool hat eine zugehörige Implementierungsdatei (typischerweise TypeScript), die eine Handler-Funktion exportiert. Der Handler empfängt die Parameter des Tools, führt die erforderliche Logik aus und gibt ein strukturiertes Ergebnis zurück.
Tool-Referenzen — Eine .ref.json-Datei, die auf eine zuvor hochgeladene Tool-Version auf dem Server verweist. Wenn ein Bundle Referenzen statt Quellcode für ein Tool enthält, löst die Plattform die Referenz beim Sync zur korrekten Version auf. So kannst du lokale Quelldateien mit servergehosteten Tool-Versionen in einem einzigen Bundle kombinieren.
| Kriterium | Edge Connector | Cloud Connector |
|---|---|---|
| Läuft auf | Deiner Infrastruktur (Arbeitsplatz, Server, VM) | Von nara verwalteter Cloud-Infrastruktur |
| Netzwerkzugang | Voller Zugang zu deinem internen Netzwerk und deinen Systemen | Zugang nur zu öffentlichen APIs und nara-gehosteten Diensten |
| Authentifizierung | Browser-OAuth oder Deployment-Anmeldedaten | Automatisch von der Plattform verwaltet |
| Verwaltung | Du installierst, konfigurierst und wartest die Runtime | Vollständig verwaltet — Provisionierung, Start, Stop via CLI oder Admin-Panel |
| Ideal für | Interne Tools, On-Premise-Datenbanken, firewallgeschützte APIs | Zustandslose Tools, öffentliche API-Integrationen, keine Infrastruktur nötig |