====== AGLX – Registry- und Discovery-Mechanismen ======

Die **Registry** ist das Adress- und Verzeichnis­system des AGLX-Netzwerks.  
Sie sorgt dafür, dass Agenten einander finden, sich authentifizieren und miteinander kommunizieren können.  
Registrys können lokal (z. B. im eigenen LAN) oder zentral über einen dedizierten Registry-Server betrieben werden.

===== Grundprinzip =====

Mit der Anpassung an die IANA-Vorgaben ist das AGLX-Discovery-System **hybrid** aufgebaut:  
Ein zentrales Register sorgt für übergreifende Erreichbarkeit, während lokale Registrys und Agenten über UDP im LAN weiterhin miteinander kommunizieren dürfen.

^ Prinzip ^ Beschreibung ^
| **Zentrales Register** | Eine offizielle Registry-Instanz verwaltet alle bekannten Agenten. Jeder Agent kann sich dort eintragen und das aktuelle Verzeichnis abrufen. |
| **Lokale UDP-Erkennung** | Innerhalb des eigenen LAN dürfen Agenten weiterhin Broadcasts verwenden, um sich gegenseitig zu erkennen. Diese Funktion ist auf interne Netze beschränkt. |
| **Verzeichnis-Aktualisierung** | Agenten können das zentrale Verzeichnis vollständig neu herunterladen oder inkrementell aktualisieren, wenn sie längere Zeit offline waren. |
| **Dezentrale Synchronisation** | Agenten können ihre lokalen Verzeichnisse untereinander austauschen, um eine aktuelle Liste aktiver Agenten zu erhalten. |
| **Hybrid-Discovery** | Kombination aus zentraler Registry (verlässlich) und Peer-to-Peer-Erkennung (lokal, dynamisch). |

===== Registrierung eines Agenten =====

Ein neuer Agent meldet sich zunächst am zentralen Register an:
<code diff>
AGLX/1.0 TCP
FROM: agent://node42.local
TO: registry://global.aglx.net
TYPE: registry.update
CONTENT-TYPE: application/json

{
  "agent_name": "Node42",
  "agent_type": "worker",
  "capabilities": [
    "data.analyze",
    "text.summarize"
  ],
  "address": "10.1.0.42",
  "port": 2594,
  "status": "READY",
  "ttl": 3600
}
</code>

Nach erfolgreicher Prüfung bestätigt das zentrale Register die Eintragung:

AGLX/1.0 TCP
FROM: registry://global.aglx.net
TO: agent://node42.local
TYPE: registry.ack
STATUS: 200 OK
AGENT-ID: 8b1e9b45-4a2c-4a83-9341-34f58f1c83c2

diff
Code kopieren

===== Herunterladen und Aktualisieren des Verzeichnisses =====

**Agenten können jederzeit das aktuelle Agentenverzeichnis abrufen:**
<code diff>
AGLX/1.0 TCP
FROM: agent://node42.local
TO: registry://global.aglx.net
TYPE: registry.fetch
CONTENT-TYPE: application/json

{
  "mode": "update",
  "since": "2025-10-20T00:00:00Z"
}
</code>

**Antwort des Registers:**
<code diff>
AGLX/1.0 TCP
FROM: registry://global.aglx.net
TO: agent://node42.local
TYPE: registry.list
CONTENT-TYPE: application/json

{
  "entries": [
    {
      "agent_id": "a7c...",
      "agent_uri": "agent://node51.local",
      "status": "READY",
      "last_seen": "2025-10-29T17:32:00Z"
    },
    ...
  ]
}
</code>

===== Aufbau eines Registry-Eintrags =====

^ Feld ^ Beschreibung ^ Beispiel ^
| **agent_id** | Eindeutige interne Kennung (UUID) | <code>8b1e9b45-4a2c-4a83-9341-34f58f1c83c2</code> |
| **agent_uri** | Offizielle Agent-Adresse | <code>agent://node42.local</code> |
| **agent_name** | Freier Anzeigename | <code>Node42</code> |
| **agent_type** | Typ des Agenten (worker, mentor, registry, etc.) | <code>worker</code> |
| **capabilities** | Auflistung der unterstützten Funktionen | <code>["data.analyze", "text.summarize"]</code> |
| **address** | IP-Adresse oder Hostname | <code>10.1.0.42</code> |
| **port** | TCP-Port (Standard: 2594) | <code>2594</code> |
| **ttl** | Gültigkeitsdauer des Eintrags in Sekunden | <code>3600</code> |
| **status** | Aktueller Status des Agenten | <code>READY</code> |
| **last_seen** | Letzte Bestätigung oder Heartbeat-Zeit | <code>2025-10-29T16:42:10Z</code> |

===== Dezentraler Austausch über UDP =====

Innerhalb lokaler Netze dürfen Agenten weiterhin UDP nutzen, um ihre Anwesenheit mitzuteilen oder auf vorhandene Agents zu reagieren.

**Beispiel:**
<code diff>
AGLX/1.0 UDP
FROM: agent://node15.local
TYPE: agent.announce
CONTENT-TYPE: application/json

{ 
  "agent_name": "Node15",
  "uptime": 1043
}
</code>

Lokale Agenten können solche UDP-Meldungen empfangen und daraus temporäre Einträge im lokalen Register erstellen.  
Diese temporären Daten können später mit dem zentralen Register synchronisiert werden.

===== Synchronisation zwischen Agenten =====

Wenn mehrere Agenten gleichzeitig aktiv sind, können sie ihre Registry-Daten austauschen, um das Netzwerk konsistent zu halten:
<code diff>
AGLX/1.0 TCP
FROM: agent://node17.local
TO: agent://node23.local
TYPE: registry.exchange
CONTENT-TYPE: application/json

{
  "known_agents": [
    {
      "agent_uri": "agent://node42.local",
      "status": "READY"
    },
    {
      "agent_uri": "agent://node51.local",
      "status": "BUSY"
    }
  ]
}
</code>

^ Mechanismus ^ Beschreibung ^
| **registry.fetch** | Vollständiges Herunterladen oder Aktualisieren des Agentenverzeichnisses vom zentralen Register. |
| **registry.exchange** | Peer-to-Peer-Austausch lokaler Agentenverzeichnisse. |
| **registry.sync** | Synchronisation zwischen Registrys (zentrale ↔ lokale Knoten). |

<box gl>
UDP-Broadcasts dürfen gemäß IANA-Vorgaben **nur innerhalb lokaler Netze** eingesetzt werden.  
Das zentrale Register ist daher der primäre Mechanismus zur Agentenerkennung und -aktualisierung.  
Der dezentrale Austausch bleibt als Ergänzung für lokale Netzwerke und redundante Updates erhalten.
</box>

===== Sicherheit und Vertrauen =====

Die Registrierung und Synchronisation erfolgen ausschließlich über TCP-Verbindungen mit optionaler Verschlüsselung.  
Für lokale UDP-Broadcasts werden keine sensiblen Daten übertragen.  

^ Mechanismus ^ Funktion ^
| **TLS oder DTLS** | Schutz der Kommunikation bei Registry-Transfers |
| **Signierte Agentenkennungen** | Eindeutige Identität und Authentifizierung |
| **Zonenbasierte Filterung** | Zugriffsbeschränkung auf definierte Netzbereiche |
| **TTL-Prüfung** | Automatische Entfernung abgelaufener Einträge |

===== Versionierung =====
  * **Modul:** Registry- und Discovery-System  
  * **Version:** 1.1 (IANA-konform)  
  * **Stand:** 27.10.2025 
  * **Autor:** Andreas Röne (Konzept)