====== AGLX – Protokollbeschreibung (TCP / UDP) ======

Das **AGLX-Protokoll** definiert, wie Agenten untereinander kommunizieren, Nachrichten austauschen und Aufgaben verteilen.  
Es arbeitet verbindungsorientiert über **TCP** und optional verbindungslos über **UDP** für leichte Status- oder Broadcast-Nachrichten.  
Das Design orientiert sich an etablierten Prinzipien aus HTTP, SMTP und MQTT, ist jedoch vollständig auf KI-Agentenkommunikation optimiert.

===== Grundprinzip =====

Jede AGLX-Nachricht besteht aus einem strukturierten Kopf (Header) und einem **JSON-basierten Nachrichtenkörper (Body)**.  
Der Header beschreibt, wer mit wem kommuniziert, der Body enthält die Nutzdaten – etwa eine Aufgabe, ein Ergebnis oder eine Systemnachricht.

^ Abschnitt ^ Beschreibung ^
| **Header** | Enthält Metainformationen wie Version, Absender, Empfänger, Nachrichtentyp, Priorität oder Transport-ID. |
| **Body (JSON)** | Beinhaltet die eigentlichen Nutzdaten, z. B. Aufgaben, Rückmeldungen, Status oder Credit-Informationen. |
| **Transportebene** | AGLX läuft über TCP (zuverlässig, verbindungsorientiert) oder UDP (leicht, verlusttolerant). |
| **Codierung** | UTF-8, ausschließlich in Textform; Binärdaten werden bei Bedarf Base64-kodiert. |

===== Nachrichtenformat =====

**Beispiel einer vollständigen Nachricht über TCP:**
<code diff>
AGLX/1.0 TCP
FROM: agent://alpha.local
TO: agent://beta.local
TYPE: task.assign
CREDITS: 2
CONTENT-TYPE: application/json
CONTENT-LENGTH: 156

{
  "task": "analyze.dataset",
  "priority": 3,
  "payload": {
  "dataset_url": "http://alpha.local/data/sample.csv"
}
</code>

===== Header-Felder =====

^ Feld ^ Beschreibung ^ Beispiel ^
| **AGLX/Version Transport** | Versions- und Transportangabe | `AGLX/1.0 TCP` |
| **FROM** | Absender der Nachricht (URI-basiert) | `agent://alpha.local` |
| **TO** | Empfänger (Agent oder Broadcast) | `agent://beta.local` |
| **TYPE** | Typ der Nachricht | `task.assign`, `status.report`, `credit.transfer` |
| **CREDITS** | Optionale Angabe über Credits oder Kosten | `2` |
| **CONTENT-TYPE** | Datentyp des Inhalts | `application/json` |
| **CONTENT-LENGTH** | Länge des JSON-Inhalts in Bytes | `156` |

===== UDP-Nachrichten =====

UDP wird für leichte, unkritische Nachrichten eingesetzt, etwa für Agentenmeldungen oder Netzwerk-Discovery.  
Der UDP-Header ist identisch aufgebaut, der Body kann jedoch kürzer oder unvollständig sein.

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

{
  "agent_name": "Gamma",
  "uptime": 3921
}
</code>

===== Nachrichtentypen (TYPE) =====

^ Typ ^ Beschreibung ^
| **task.assign** | Beauftragung eines Agenten mit einer Aufgabe |
| **task.result** | Rückmeldung mit einem Ergebnis oder Status |
| **status.report** | Periodische Zustandsmeldung |
| **credit.transfer** | Übertragung von Credits zwischen Agenten |
| **agent.announce** | Selbstdarstellung eines Agenten im Netzwerk |
| **registry.update** | Synchronisation mit der Registry |
| **mentor.feedback** | Mentoring- oder Bewertungskommunikation |

===== Verbindungshandshake (TCP) =====

Ein typischer TCP-Verbindungsaufbau verläuft in drei Schritten:

^ Schritt ^ Beschreibung ^
| **1. CONNECT** | Der sendende Agent baut eine TCP-Verbindung zum Zielagenten auf und sendet eine erste `AGLX/1.0`-Handshake-Nachricht. |
| **2. ACKNOWLEDGE** | Der Zielagent bestätigt die Verbindung mit einer `TYPE: handshake.ack`. |
| **3. READY** | Beide Seiten wechseln in den aktiven Kommunikationszustand und tauschen reguläre Nachrichten aus. |

===== Fehler- und Statuscodes =====

AGLX nutzt einfache numerische Statuscodes, angelehnt an HTTP.

^ Code ^ Bedeutung ^ Beschreibung ^
| **100** | Continue | Verbindung etabliert, bereit zum Empfang |
| **200** | OK | Aufgabe erfolgreich angenommen oder ausgeführt |
| **400** | Bad Request | Nachricht fehlerhaft formatiert |
| **401** | Unauthorized | Authentifizierung erforderlich |
| **404** | Agent Not Found | Zielagent nicht erreichbar |
| **500** | Internal Error | Interner Verarbeitungsfehler |

===== Sicherheit und Authentifizierung =====

Sicherheit kann auf mehreren Ebenen realisiert werden:
  * Transportverschlüsselung (z. B. TLS)
  * Agent-Signaturen (z. B. HMAC)
  * Netzwerksegmentierung und lokale [[agent_collective_framework:aglx:Trust-Zonen|Trust-Zonen]]

<box gl>
UDP-Nachrichten dienen nur der Agentenerkennung und leichten Statusmeldungen – **niemals** für sensible oder kreditrelevante Kommunikation.  
Finanzielle, reputations- oder aufgabenspezifische Daten müssen immer über TCP laufen.
</box>

===== Versionierung =====
  * **Protokollversion:** 1.0 (Draft)  
  * **Stand:** 27.10.2025 
  * **Autor:** Andreas Röne  
  * **Status:** Entwurf / Evaluierungsphase