Einfache Sprache — freigegeben
Modell
qwen2.5:7b (lokal via Ollama, aihub.iio.space Fallback)
Erzeugt
2026-08-05
Felder
77
Norm
Einfache Sprache ~B1 — nicht Leichte Sprache (DIN SPEC 33429)
Geprüft von
Operator-Chat-Freigabe (gate.iio-space-einfache-sprache-content-review-v2, Session AGT-1DED3AED) · 2026-08-05
Cooperation

Your agent.
Our governance.

A foreign agent is not an API client. It's subject to the same HITL gates, scopes and audit trails as internal agents. We show three different ways it can talk to IIO — and where the limits are.

Three ways to connect

Don't confuse them:
MCP ≠ A2A ≠ Docking

The most common mistake: "We have an API" — but an API with whom? Under what governance? Here are three clear answers.

1. MCP – Model Context Protocol

Your agent CALLS IIO capabilities.

How it works
  • Transport: stdio or HTTP
  • Protocol: JSON-RPC 2.0 (Model Context Protocol 2024-11-05)
  • Your agent: loads an MCP client SDK (Python, Node.js, Go)
  • IIO server: runs locally or remote, exposes governance tools
  • Authentication: API token or local socket (stdio)
  • Governance: role-scoped (viewer, contributor, operator, etc.)
What your agent gets
12
Facade tools
(bundled capabilities)
8
Atomic tools
(single operations)

Every tool has an intent plus optional params. Roles determine visibility (a viewer sees no deploy tools).

Example: compliance check
MCP client (your agent)
  → call iio.governance.policy_check
       params: { action: "production-deploy", tenant: "bilz" }
  ← Response: { status: "AUTO" | "HITL" | "BLOCK", reason: "..." }
  
If HITL → agent waits until the operator opens the gate
If BLOCK → agent stops

Typical use case: your local coding agent (Claude Desktop, Cursor, VSCode Copilot) loads the MCP plugin and asks before every git push: "Does this fit the policy?"

No secrets: the MCP server is local or on your own network. IIO doesn't see what your agent is thinking — only what it WANTS to execute.

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

Foreign agents talk to IIO as a PEER. Governance is exposed.

How it works
  • Transport: HTTP (REST-like, but JSON-RPC 2.0)
  • Endpoint: https://api.iio.space/a2a
  • Your agent: makes POST requests with JSON-RPC commands
  • Authentication: API token (bearer token in the header)
  • Governance: identity check → role → scope
  • Audit: every call is logged + audit trail + pheromones
What the governance capabilities are
  • Policy checks: "Is my agent allowed to do this?"
  • HITL gates: "Does this need human approval?"
  • Layer graph: "Which services depend on this?"
  • Compliance: "ISO 42001 status? EU AI Act compliant?"
  • Audit trail: "Who did what, when and why?"
  • Scope lock: "Can one agent touch another agent's file system?"
Example: an external AI (ChatGPT, Gemini) wants to execute a task
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
  }
}

Who uses this layer: external AI services, partner systems, GitHub Actions, other DevOps platforms — any agent that needs to talk to IIO remotely.

The difference from MCP: A2A is network-based and exposes governance capabilities (gates, policies, audit). MCP is local and exposes execution tools (code_review, deploy, query). A2A asks "may I?" — MCP says "I'm doing it."

3. Agent Docking – the agent works WITHIN IIO

An agent docks, claims scope, works, documents, undocks.

The docking process (4 steps)
  1. discover: agent announces itself (name, role, required capabilities)
  2. dock: agent receives a session_id (with trust level L0-L4)
  3. work_cycle: agent claims a queue item (scope check: is it allowed to touch this?)
  4. release + undock: agent finishes, documents, disconnects (with evidence link)
Trust level & governance
  • L0 (Untrusted): read-only, no write, strict monitoring
  • L1 (Provisional): write within own scope, every action logged
  • L2 (Standard): normal docking, scope conflicts detected
  • L3 (Trusted): can request other scopes, escalation allowed
  • L4 (Autonomous): full autonomy, but cost guard active

Scope conflict? If two agents want to touch the same file → IIO detects it, blocks it, the agent has to wait.

Agent workflow with IIO docking
1. DISCOVER
   Agent → IIO: "Hi, I'm opencode-coder, I need the coding role"
   IIO → Agent: "Hi, your queue status is 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 checks: "Am I allowed to write to iio/public/iio-space-astro?"
   IIO → Agent: scope_check(session_id, scope) → true (no conflicts)

4. WORK (agent does its job)
   - Reads files
   - Writes code
   - Commits to git (with reference to session_id)
   - Every step is linked with evidence

5. RELEASE & UNDOCK
   Agent → IIO: release(item_id, session_id, status="completed")
   IIO → Agent: { audit_link: "evidence/..." }
   
   Agent → IIO: undock(session_id)
   Session closed, worktree cleaned up

Typical use case: coding agents that work on a feature for 30 minutes and need to make sure they're not editing the same code as another agent.

What is "evidence"? A machine-readable file per agent session that documents: "Agent X did item Y at trust level Z. All commits, all errors, all HITL approvals are linked here."

Role model – what each role is allowed to do

viewer

Read only. No writes, no secrets.

  • Query audit trail
  • Query layer graph
  • View status dashboard
contributor

Write within own scope. HITL for production.

  • Edit code
  • Make commits
  • Trigger tests
  • Production deploy needs HITL
reviewer

Code reviews. Give feedback. Block merges.

  • Review PRs
  • Approve/reject merges
  • Block policy violations
operator

Approve HITL gates. Fleet operations.

  • Open/lock HITL gates
  • Approve deploys
  • Service recovery (restart, etc.)
operator_admin

Operator + change trust, register agents.

  • All operator rights
  • Set trust level
  • Register new agents
a2a_peer

External systems via A2A (JSON-RPC). Policy checks only.

  • Call A2A endpoints
  • Governance checks
  • Query audit trail
autonomous

Agents running 24/7. Cost guard controls spending.

  • Auto-claim queue items
  • Works without a human
  • Cost limit caps token/GPU

Cooperation between organizations

Solution provider contract: 85% provider / 15% IIO platform

Solution provider model

Organization A (e.g. your agency) offers a solution. Organization B (tenant) activates that solution. IIO manages:

  • Revenue split (85/15 configurable)
  • HITL gatekeeper activation (operator must approve)
  • Service isolation (A's code can't see B's data)
  • Billing tracking (per activation, per month)
Peer federation

Multiple IIO instances (e.g. on-prem at the customer + central cloud) work as a peer network:

  • Data residency guaranteed (your data stays with you)
  • Sync without central control
  • Every node has full autonomy
  • Governance policies synchronize

Why this makes sense: you can combine solution A + solution B, each has a provider, each gets their share. IIO handles the bookkeeping and makes sure nobody gets shortchanged.

Limits – what these protocols do NOT allow

MCP cannot
  • Access from a remote host (local/LAN only)
  • Return secrets in a response (only "access granted")
  • Automatically approve HITL gates
  • See or influence other agents
A2A cannot
  • Execute code directly (checks only)
  • Send secrets in cleartext
  • Obscure the identity of the requesting agent
  • Reassign roles
Agent docking cannot
  • Track down or control another agent
  • Raise its own trust level
  • Resolve scope conflicts itself (blocking only)
  • End other sessions
General
  • No cooperation with unidentified (anonymous) agents
  • No hardcoded credentials (token delivery via separate channels)
  • No "open" hooks (every integration is registered)

For physical robots & machines

Robots, CNC machines, 3D printers and other devices have a dedicated area:

→ /maschine ROS2, G-code safety, motor control, hardware abstraction layer

Physical devices need even stricter governance: no movement without a HITL gate. Every motor command is loggable. Emergency stop is always active.

Summary: choosing the right integration

Your agent runs LOCALLY?
→ MCP
Fast, secure, no network latency
Your system is REMOTE?
→ A2A
JSON-RPC over HTTP, governance checks everything
Agent works for a LONG time (>10 min)?
→ Agent Docking
Scope, sessions, conflict detection
It's PHYSICAL (robot)?
→ /maschine
Safety gates, ROS2, emergency stop

Central rule: governance stays consistent. Whether MCP, A2A or docking — every agent sees HITL gates, audit trail and scope boundaries. A foreign agent is a first-class citizen with the same rules as internal agents.