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 → 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

{
  "endpoint": "/registry/register",
  "method": "POST",
  "payload": {
    "agent_id": "agent://node17",
    "zone": "research-hub",
    "capabilities": ["vision.detect", "data.analyze"]
  },
  "signature": "ed25519:8ae4..."
}

Antwort:

{
  "status": "accepted",
  "trust_level": 0.82,
  "session_token": "ZT-9ff2",
  "expires": "2025-12-31T00:00:00Z"
}

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 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: