Kooperation

Ihr Agent.
Unsere Governance.

Ein fremder Agent ist kein API-Client. Er unterliegt denselben HITL-Gates, Scopes und Audit-Trails wie interne Agenten. Wir zeigen drei unterschiedliche Wege, wie er mit IIO kommuniziert — und wo die Grenzen liegen.

Drei Anschlussarten

Nicht verwechseln:
MCP ≠ A2A ≠ Docking

Der häufigste Fehler: "Wir haben eine API" — aber API mit wem? Mit welcher Governance? Hier sind drei klare Antworten.

1. MCP – Model Context Protocol

Dein Agent RUFT IIO-Fähigkeiten AUF.

Wie es funktioniert
  • Transport: stdio oder HTTP
  • Protokoll: JSON-RPC 2.0 (Model Context Protocol 2024-11-05)
  • Ihr Agent: Lädt MCP-Client-SDK (Python, Node.js, Go)
  • IIO-Server: Läuft lokal oder Remote, exponiert Governance-Tools
  • Authentifizierung: API-Token oder Local-Socket (stdio)
  • Governance: Rollen-gescoped (viewer, contributor, operator, etc.)
Was Ihr Agent bekommt
12
Facade-Tools
(gebündelte Fähigkeiten)
8
Atomare Tools
(Einzeloperationen)

Jedes Tool hat einen intent + optionale params. Rollen bestimmen Sichtbarkeit (ein viewer sieht keine Deploy-Tools).

Beispiel: Compliance-Check
MCP-Client (Dein Agent)
  → call iio.governance.policy_check
       params: { action: "production-deploy", tenant: "bilz" }
  ← Response: { status: "AUTO" | "HITL" | "BLOCK", reason: "..." }
  
Wenn HITL → Agent wartet, bis Operator das Gate öffnet
Wenn BLOCK → Agent stoppt

Typischer Use-Case: Dein lokaler Coding-Agent (Claude Desktop, Cursor, VSCode Copilot) lädt das MCP-Plugin und fragt vor jeder Git-Push: "Passt das in die Policy?"

Keine Geheimnisse: Der MCP-Server ist lokal oder bei dir im Netzwerk. IIO sieht nicht, was dein Agent denkt — nur was er ausführen WILL.

2. A2A – Agent-to-Agent (JSON-RPC 2.0 / HTTP)

Fremde Agenten sprechen mit IIO als PEER. Governance wird exponiert.

Wie es funktioniert
  • Transport: HTTP (REST-ähnlich, aber JSON-RPC 2.0)
  • Endpoint: https://api.iio.space/a2a
  • Dein Agent: Macht POST-Requests mit JSON-RPC Befehlen
  • Authentifizierung: API-Token (Bearer-Token im Header)
  • Governance: Identitätsprüfung → Role → Scope
  • Audit: Jeder Call wird geloggt + mit Audit-Trail + Pheromones
Was Governance-Capabilities sind
  • Policy Checks: "Darf mein Agent das tun?"
  • HITL Gates: "Braucht es Mensch-Freigabe?"
  • Layer Graph: "Welche Services sind abhängig?"
  • Compliance: "ISO 42001 Status? EU AI Act konform?"
  • Audit Trail: "Wer tat was wann und warum?"
  • Scope Lock: "Kann ein Agent das Dateisystem eines anderen anfassen?"
Beispiel: Externe KI (ChatGPT, Gemini) will Aufgabe ausführen
POST https://api.iio.space/a2a
Authorization: Bearer <token>
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": "task-12345",
  "method": "governance.check_action",
  "params": {
    "action_type": "code_deploy",
    "scope": "tenants/netplans",
    "reason": "Feature X deployment"
  }
}

Response:
{
  "jsonrpc": "2.0",
  "id": "task-12345",
  "result": {
    "decision": "HITL",
    "gate_id": "gate.netplans-code-deploy-20260804",
    "expires_in_seconds": 3600
  }
}

Wer diese Schicht nutzt: Externe KI-Services, Partner-Systeme, GitHub Actions, andere DevOps-Plattformen — jeder Agent, der Remote mit IIO kommunizieren soll.

Der Unterschied zu MCP: A2A ist Netzwerk-basiert und exponiert governance capabilities (Gates, Policies, Audit). MCP ist lokal und exponiert execution tools (code_review, deploy, query). A2A sagt "darf ich?" — MCP sagt "ich mache".

3. Agent Docking – Der Agent arbeitet INNERHALB von IIO

Ein Agent dockt an, beansprucht Scope, arbeitet, dokumentiert, undockt.

Der Docking-Prozess (4 Schritte)
  1. discover: Agent meldet sich selbst an (Name, Rolle, erforderliche Fähigkeiten)
  2. dock: Agent erhält session_id (mit Trust Level L0-L4)
  3. work_cycle: Agent beansprucht ein Queue-Item (Scope-Check: kann er das anfassen?)
  4. release + undock: Agent schließt ab, dokumentiert, trennt sich (mit Evidence-Link)
Trust Level & Governance
  • L0 (Untrusted): Read-Only, kein Write, strict monitoring
  • L1 (Provisional): Write in eigenem Scope, jede Action geloggt
  • L2 (Standard): Normales Docking, Scope-Conflicts erkannt
  • L3 (Trusted): Kann andere Scopes anfragen, Escalation erlaubt
  • L4 (Autonomous): Volle Autonomie, aber Cost-Guard aktiv

Scope-Konflikt? Wenn zwei Agents dieselbe Datei anfassen wollen → IIO erkennt das, blockiert, Agent muss warten.

Agent Workflow mit IIO Docking
1. DISCOVER
   Agent → IIO: "Hallo, ich bin opencode-coder, brauche Coding-Rolle"
   IIO → Agent: "Hallo, dein queue-status ist 2 items open"

2. DOCK
   Agent → IIO: dock(agent_id="opencode", role="coding")
   IIO → Agent: { session_id: "sess-xyz", trust_level: "L2" }

3. WORK_CYCLE
   Agent → IIO: work_cycle(session_id="sess-xyz")
   IIO → Agent: { queue_item: "IIOSPACE-17", scope: "iio/public/iio-space-astro" }
   
   Agent prüft: "Kann ich auf iio/public/iio-space-astro schreiben?"
   IIO → Agent: scope_check(session_id, scope) → true (keine Konflikte)

4. WORK (Agent macht seinen Job)
   - Liest Dateien
   - Schreibt Code
   - Committed zu Git (mit Referenz zu session_id)
   - Jeder Schritt wird verlinkt mit Evidence

5. RELEASE & UNDOCK
   Agent → IIO: release(item_id, session_id, status="completed")
   IIO → Agent: { audit_link: "evidence/..." }
   
   Agent → IIO: undock(session_id)
   Session geschlossen, Worktree aufgeräumt

Typischer Use-Case: Coding-Agenten, die 30 Minuten an einem Feature arbeiten und sicherstellen müssen, dass sie nicht in denselben Code editieren wie ein anderer Agent.

Was ist "Evidence"? Eine maschinenlesbare Datei pro Agent-Sitzung, die dokumentiert: "Agent X hat Item Y mit Trust Level Z gemacht. Alle Commits, alle Fehler, alle HITL-Genehmigungen sind hier verlinkt."

Rollen-Modell – Was jede Rolle darf

viewer

Nur Lesen. Keine Writes, keine Secrets.

  • Query Audit-Trail
  • Layer Graph Abfragen
  • Status-Dashboard sehen
contributor

Schreiben im eigenen Scope. HITL für Production.

  • Code editieren
  • Commits machen
  • Tests triggern
  • Production-Deploy braucht HITL
reviewer

Code-Reviews. Feedback geben. Merges blockieren.

  • PRs reviewen
  • Merges genehmigen/ablehnen
  • Policy Violations blockieren
operator

HITL-Gates genehmigen. Fleet-Operationen.

  • HITL-Gates öffnen/sperren
  • Deploys freigeben
  • Service-Recovery (Restart, etc.)
operator_admin

Operator + Vertrauen ändern, Agents anmelden.

  • Alle Operator-Rechte
  • Trust Level setzen
  • Neue Agenten registrieren
a2a_peer

Externe Systeme über A2A (JSON-RPC). Policy-Checks nur.

  • A2A-Endpoints aufrufen
  • Governance Checks
  • Audit-Trail abfragen
autonomous

Agenten, die 24/7 laufen. Cost-Guard steuert Spending.

  • Queue-Items auto-claim
  • Arbeitet ohne Mensch
  • Cost-Limit limitiert Token/GPU

Kooperation zwischen Organisationen

Solution Provider Contract: 85% Provider / 15% IIO Platform

Solution Provider Model

Organisation A (z.B. deine Agentur) bietet eine Lösung an. Organisation B (Tenant) aktiviert diese Lösung. IIO verwaltet:

  • Revenue-Split (85/15 konfigurierbar)
  • HITL-gatekeeper Activation (Operator muss freigeben)
  • Service-Isolation (A's Code kann B's Daten nicht sehen)
  • Billing-Tracking (pro Activation, pro Monat)
Peer Federation

Mehrere IIO-Instanzen (z.B. onPremise beim Kunden + Cloud-Zentral) funktionieren als Peer-Netzwerk:

  • Daten-Residency garantiert (Deine Daten bleiben bei dir)
  • Sync ohne zentrale Kontrolle
  • Jeder Node hat volle Autonomie
  • Governance-Policies synchronisieren sich

Warum das sinnvoll: Du kannst A-Lösung + B-Lösung kombinieren, jede hat einen Provider, jeder bekommt seinen Teil. IIO kümmert sich um die Buchhaltung und stellt sicher, dass niemand klaut.

Grenzen – Was über diese Protokolle NICHT geht

MCP kann NICHT
  • ⊗ Vom Remote-Host aus zugreifen (nur lokal/LAN)
  • ⊗ Secrets im Response returnen (nur "Zugriff gewährt")
  • ⊗ HITL-Gates automatisch genehmigen
  • ⊗ Andere Agents sehen oder beeinflussen
A2A kann NICHT
  • ⊗ Direkt Code ausführen (nur Checks)
  • ⊗ Secrets im Cleartext senden
  • ⊗ Die Identität des anfragenden Agents verschleiern
  • ⊗ Rollen neu zuweisen
Agent Docking kann NICHT
  • ⊗ Einen anderen Agent aufspüren/kontrollieren
  • ⊗ Trust Level selbst erhöhen
  • ⊗ Scope-Konflikte selbst auflösen (nur blockieren)
  • ⊗ Andere Sessions beenden
Allgemein
  • ⊗ Keine Kooperation mit nicht-identifizierten Agents (Anonymous)
  • ⊗ Keine Credentials hardcoden (Token-Delivery über separate Kanäle)
  • ⊗ Keine "offenen" Hooks (jede Integration ist registered)

Für physische Roboter & Maschinen

Roboter, CNC-Maschinen, 3D-Drucker und andere Geräte haben einen dedizierten Bereich:

→ /maschine ROS2, G-Code Safety, Motor-Kontrolle, Hardware Abstraction Layer

Physische Geräte benötigen noch strengere Governance: Keine Bewegung ohne HITL-Gate. Jeder Motor-Befehl ist loggbar. Emergency-Stop ist immer aktiv.

Zusammenfassung: Die richtige Integration wählen

Dein Agent läuft LOKAL bei dir?
→ MCP
Schnell, sicher, keine Netzwerk-Latenz
Dein System ist REMOTE?
→ A2A
JSON-RPC über HTTP, Governor prüft alles
Agent arbeitet LANGE (>10 min)?
→ Agent Docking
Scope, Sessions, Conflict-Detection
Es ist PHYSIKALISCH (Roboter)?
→ /maschine
Safety-Gates, ROS2, Emergency-Stop

Zentrale Regel: Governance bleibt konsistent. Ob MCP, A2A oder Docking — jeder Agent sieht HITL-Gates, Audit-Trail und Scope-Grenzen. Ein fremder Agent ist ein First-Class Citizen mit denselben Regeln wie interne Agenten.