====== API & Schnittstellen ======
Das **Agent Collective Framework (ACF)** definiert mehrere Schnittstellenebenen (Interfaces),  
um eine saubere Trennung zwischen Planung (Cognitive Layer), Ausführung (Execution Layer)  
und Kommunikation (AGLX / Netzwerk) zu gewährleisten.

Ziel ist, dass alle Agenten unabhängig von Implementierungssprache oder Plattform  
über standardisierte Datenstrukturen und Protokolle miteinander interagieren können.

===== Übersicht =====
^ Schnittstellenebene ^ Richtung ^ Beschreibung ^
| **Cognitive → Execution** | intern | Übergibt Aufgaben vom Entscheidungsmodul an das Ausführungsmodul. |
| **Execution → Cognitive** | intern | Rückmeldung von Ergebnissen, Fehlern und Status. |
| **Agent ↔ Agent (AGLX)** | extern | Kommunikation zwischen Agenten über TCP/UDP mit gesicherten Sessions. |
| **Agent ↔ Registry** | extern | Registrierung, Authentifizierung, Policy-Updates und Credit-Synchronisierung. |
| **Agent ↔ DHT (Discovery)** | extern | Veröffentlichung und Suche nach Präsenzinformationen. |

===== 1. Cognitive → Execution =====
Diese Schnittstelle ist die interne Übergabe von Aktionen, die der Cognitive Layer geplant hat.

^ Feld ^ Beschreibung ^ Beispiel ^
| **action_id** | Eindeutige ID der Aktion | `act-73d2` |
| **capability** | Angeforderte Fähigkeit / Modul | `data.analyze` |
| **parameters** | Eingabedaten oder Referenzen | `{ "file": "/data/report.csv" }` |
| **constraints** | Rahmenbedingungen, Deadlines, Priorität | `{ "deadline": "2025-10-31T12:00Z" }` |
| **ethic_checked** | Boolean, ob Ethikprüfung erfolgreich war | `true` |

**Antwort (Execution → Cognitive):**
<code json>
{
  "action_id": "act-73d2",
  "status": "completed",
  "result": {
    "summary": "Analysis complete, 125 entries processed."
  },
  "duration_ms": 2332
}
</code>

===== 2. Agent ↔ Agent (AGLX Session) =====
Kommunikation erfolgt über das [[agent_collective_framework:protokoll:aglx|AGLX-Protokoll]]  
auf TCP/UDP-Basis. Jede Nachricht besitzt Kopf- und Nutzlastbereich.

**Header-Format (vereinfacht):**
<code>
[ Version | Type | Flags | Length | Signature | Payload ]
</code>

**Typische Nachrichtentypen:**
^ Typ ^ Beschreibung ^
| `HELLO` | Präsenzmeldung oder Verbindungsaushandlung |
| `TASK` | Übertragung einer Aufgabe |
| `RESULT` | Rückgabe von Ergebnissen |
| `PING` | Verbindungsprüfung |
| `ACK` | Empfangsbestätigung |
| `ERROR` | Fehlermeldung mit Code |

===== 3. Agent ↔ Registry =====
Registrierung, Authentifizierung und Synchronisierung mit der [[agent_collective_framework:registry|Registry]].

**Beispiel: Registrierungspayload**
<code json>
{
  "agent_id": "agent://node21",
  "zone": "research-hub",
  "public_key": "MIIBIjANBgkqhkiG9w0B...",
  "capabilities": ["vision.detect", "data.analyze"],
  "ethic_version": "1.1.0"
}
</code>

**Antwort der Registry:**
<code json>
{
  "status": "accepted",
  "session_token": "ZT-982f-11bb",
  "trust_level": 0.84,
  "expires": "2025-11-30T00:00:00Z"
}
</code>

===== 4. Agent ↔ Discovery (DHT) =====
Nutzung der [[agent_collective_framework:discovery:dht|DHT-Struktur]]  
zur Veröffentlichung von Präsenzinformationen.

**Beispiel: PUT-Eintrag**
<code json>
{
  "key": "hash(agent://node21)",
  "endpoint": "aglx://192.168.91.14:2594",
  "zone": "research-hub",
  "capabilities_bloom": "af9b22e...",
  "ttl": 3600
}
</code>

===== 5. Erweiterte Schnittstellen (optional) =====
^ Typ ^ Zweck ^
| **REST-API (HTTP)** | Ermöglicht Integration externer Systeme, Dashboards und Tools. |
| **MQTT / WebSocket-Bridge** | Für Echtzeitkommunikation mit UI oder IoT-Geräten. |
| **CLI / Telnet-Interface** | Lokale Steuerung und Debugging eines Agenten. |
| **RPC Layer (JSON-RPC / gRPC)** | Optionale Remote-Steuerung zwischen vertrauenswürdigen Zonen. |

===== Schnittstellenprinzipien =====
  * **Maschinenlesbarkeit:** JSON als Basisaustauschformat (leicht serialisierbar).  
  * **Erweiterbarkeit:** Alle Objekte können um benutzerdefinierte Felder ergänzt werden.  
  * **Sicherheit:** Authentifizierung und Signaturen über AGLX-Header.  
  * **Abwärtskompatibilität:** Versionierung aller Schnittstellen.  

===== Beispiel: Cognitive ↔ Execution-Kommunikation =====
<code>
[Cognitive Layer]
   |
   |  →  plan_action("data.analyze")
   |      check_ethics() ✅
   |      send_to_executor()
   |
[Execution Layer]
   |
   |  →  execute_task()
   |      return_result()
</code>

===== Zielbild =====
Die Schnittstellenarchitektur von ACF soll **vollständig interoperabel** sein —  
Agenten unterschiedlicher Hersteller oder Zonen sollen sich über dieselben Protokolle verständigen können,  
ohne zentrale Koordination oder proprietäre Gateways.

----

**Verwandte Seiten:**  
  * [[agent_collective_framework:implementierung|Implementierung & Referenzarchitektur]]  
  * [[agent_collective_framework:protokoll:aglx|AGLX-Protokoll]]  
  * [[agent_collective_framework:sicherheit|Sicherheit im Framework]]  
  * [[agent_collective_framework:integration:lokale_agenten|Integration lokaler Agenten]]