====== API – Schnittstellenübersicht ======
Das **Agent Collective Framework (ACF)** definiert eine Reihe offener Schnittstellen (APIs),  
über die Agenten miteinander, mit ihren Zonen oder mit externen Anwendungen kommunizieren.  
Diese APIs sind so gestaltet, dass sie plattformunabhängig, sicher und maschinenlesbar funktionieren.

===== Ziel =====
  * Einheitliche Kommunikation zwischen Cognitive- und Execution-Layer  
  * Integration lokaler Tools, KI-Modelle und Datenquellen  
  * Austausch zwischen verschiedenen Zonen über standardisierte Protokolle  
  * Erweiterbarkeit für eigene Module und Anwendungsfälle  

===== API-Struktur im ACF =====
^ Ebene ^ Beschreibung ^
| **Interne APIs** | Kommunikation innerhalb eines Agenten (z. B. Cognitive ↔ Execution Layer). |
| **System-APIs** | Verbindungen zwischen Agenten und ACF-Diensten wie Registry, Discovery, Credit-System. |
| **Externe APIs** | Zugriff durch externe Systeme, Dashboards, oder Management-Tools. |

Die technische Definition und Beispielnutzung findest du unter  
→ [[agent_collective_framework:api:interfaces|API & Schnittstellen]].

===== Prinzipien =====
^ Prinzip ^ Beschreibung ^
| **Offen & dokumentiert** | Jede Schnittstelle folgt einem klar beschriebenen, öffentlichen Schema. |
| **Maschinenlesbar** | JSON ist das Standardformat für Datenaustausch; optional YAML oder CBOR. |
| **Sicher & signiert** | Jede Anfrage kann authentifiziert und signiert werden. |
| **Erweiterbar** | Entwickler können eigene Module oder Endpunkte hinzufügen. |
| **Versioniert** | Jede API besitzt eine eindeutige Versionsnummer, um Abwärtskompatibilität zu gewährleisten. |

===== Beispielhafte System-APIs =====
^ API-Endpunkt ^ Zweck ^
| `/registry/register` | Registrierung eines neuen Agenten in der Zone |
| `/registry/update` | Aktualisierung von Fähigkeiten oder Policy-Versionen |
| `/discovery/lookup` | Suche nach Agenten mit bestimmten Capabilities |
| `/credit/transfer` | Übertragung oder Verrechnung von Credits |
| `/reputation/report` | Übermittlung von Leistungs- und Bewertungsdaten |

===== Beispiel: JSON-Aufruf an Registry =====
<code json>
{
  "endpoint": "/registry/register",
  "method": "POST",
  "payload": {
    "agent_id": "agent://node17",
    "zone": "research-hub",
    "capabilities": ["vision.detect", "data.analyze"]
  },
  "signature": "ed25519:8ae4..."
}
</code>

**Antwort:**
<code json>
{
  "status": "accepted",
  "trust_level": 0.82,
  "session_token": "ZT-9ff2",
  "expires": "2025-12-31T00:00:00Z"
}
</code>

===== Erweiterbare Module =====
| Modul | Beschreibung |
|--------|---------------|
| **Ethics API** | Zugriff auf maschinenlesbare Ethik- und Policy-Regeln. |
| **Credit API** | Verwaltung von Credits, Transfers und Limits. |
| **Reputation API** | Ermittlung und Austausch von Vertrauenswerten. |
| **Governance API** | Einreichung neuer AIPs oder Abstimmungsprozesse. |
| **Monitoring API** | Statusabfragen, Logs und Heartbeats. |

===== Authentifizierung & Sicherheit =====
  * Alle API-Aufrufe erfolgen über signierte Tokens oder Zertifikate.  
  * Kommunikationskanäle sind verschlüsselt (mTLS oder über AGLX-Session).  
  * Zugriffskontrolle basiert auf Rollen in der [[agent_collective_framework:registry|Registry]] (z. B. member, observer, controller).  

===== Versionierung =====
| Ebene | Beispiel |
|--------|----------|
| **Major** | 3 → Neue Architektur oder inkompatible Änderung |
| **Minor** | 3.1 → Erweiterung mit Abwärtskompatibilität |
| **Patch** | 3.1.2 → Fehlerbehebungen oder Sicherheitsupdates |

Beispiel:  
`https://api.acf.zone/v3.1/registry/register`

===== Zielbild =====
Die API-Schicht des ACF ist das **Rückgrat der Interoperabilität**.  
Sie stellt sicher, dass unterschiedliche Agenten-Implementierungen  
– ob auf Server, Edge oder Desktop – dieselben Funktionen ansprechen können,  
ohne sich auf eine zentrale Infrastruktur verlassen zu müssen.

----

**Verwandte Seiten:**  
  * [[agent_collective_framework:api:interfaces|Technische Schnittstellen (Cognitive ↔ Execution)]]  
  * [[agent_collective_framework:registry|Registry & Zonen]]  
  * [[agent_collective_framework:sicherheit|Sicherheit im Framework]]  
  * [[agent_collective_framework:implementierung|Implementierung & Referenzarchitektur]]