# Schnittstellen

> Agent NAS nutzt Dateien für die Datenebene und Tools für die Steuerungsebene: Bytes laufen über Mounts, Git und S3; Autorisierung, Freigabe, Gedächtnis, Suche und Erklärung laufen über MCP, HTTP und eine CLI. Jede Schnittstelle ist eine Projektion derselben Daten, und Unterschiede in der Semantik werden als ausdrückliche Fehler ausgedrückt, statt sie zu verschleiern.

## Prinzipien

1. **Dateien für die Datenebene, Tools für die Steuerungsebene.** Bytes laufen über Mounts, Git und S3; Autorisierung, Freigabe, Gedächtnis, Suche und Erklärung laufen über MCP, HTTP und eine CLI.
2. **Gateways sind zustandslos.** Autorisiert wird an genau einer Stelle in der Trust-Schicht.
3. **Jede Schnittstelle ist eine Projektion.** Unterschiede in der Semantik werden durch ausdrückliche Fehlerabbildungen ausgedrückt (zum Beispiel wird „Gate ausstehend“ auf ein `EACCES` mit einer erklärenden Datei abgebildet), und bei S3 wird nicht so getan, als gäbe es Branches.
4. **Eine schmale Tool-Oberfläche.** Höchstens 10 MCP-Tools richten sich an Agenten; Aktionen für Menschen und Betreiber liegen in einer eigenen Betreiberschnittstelle.
5. **Adapter isolieren Protokolländerungen.** Versionswechsel bei MCP und A2A betreffen nur die Adapter.

## Schnittstellenmatrix

| Schnittstelle | Ebene | Zielgruppe | Abbildung | Stufe |
| --- | --- | --- | --- | --- |
| Mount (FUSE, NFS, SMB) | Daten | Agenten, Menschen, beliebige Programme | Eine Branch-Ansicht; Fehlerabbildung siehe unten | L0 |
| Git (SSH, HTTPS) | Daten | Agenten, Menschen, CI | Ein Run-Branch ist ein Git-Branch; ein Agent PR ist ein Merge Request | L0 |
| S3-kompatibel | Daten | Datenpipelines, Batch-Jobs | Ein Bucket entspricht einer Branch-Ansicht eines Trees; eine Versions-ID ist ein Commit | L0 (optional) |
| WebDAV | Daten | Menschen (Finder, Explorer) | Eine schreibgeschützte Aktivitätsansicht | L0 (optional) |
| CLI `nas` | Steuerung | Menschen, Skripte | Eins zu eins zur HTTP-API | L0 |
| HTTP-API | Steuerung | Orchestratoren, der Leitstand | Alles `POST` mit JSON; Felder in `snake_case` | L1 |
| MCP | Steuerung | Agenten | Neun Tools (siehe unten) | L1, L2 |
| A2A | Steuerung | Andere Agenten | Eine Aufgabe entspricht `inbox/` und `outbox/` | L4 (optional) |

## Die MCP-Tool-Oberfläche

Nur neun Tools richten sich an Agenten:

| Tool | Was es tut | Benötigte Lease-Aktion | Hinweis |
| --- | --- | --- | --- |
| `nas_list` | Ein Verzeichnis auflisten, mit Labels und Review-Status | `list` | Pfade außerhalb der Lease sind unsichtbar. |
| `nas_read` | Budgetiertes Lesen: Ansicht, Bereich, Budget | `read` | [Budgeted Reads](https://agentnas.com/de/concepts/budgeted-reads/) |
| `nas_search` | Suchen (Volltext, optional Vektor), liefert Ausschnitte und Zeiger | `read` | Quarantäne ist standardmäßig ausgeschlossen. |
| `nas_write` | Eine Datei im Branch schreiben, mit optionalem `intent` | `write` | Die meisten Laufzeitumgebungen nutzen direkt den Mount und brauchen es nicht. |
| `nas_branch` | Branches anlegen, Checkpoints setzen, wiederherstellen und auflisten | `write` | [Agent Branch](https://agentnas.com/de/concepts/agent-branch/) |
| `nas_propose` | Einen Agent PR erstellen | `propose` | Kann ein Gate auslösen. |
| `nas_lease` | Eine engere Kind-Lease anfordern; aktuelle Lease und Budgets abfragen; weitergehende Befugnis anfordern (über ein Gate) | Keine | [Capability Lease](https://agentnas.com/de/concepts/capability-lease/) |
| `nas_remember` | Eine Notiz schreiben, mit Quellen und Art | `write` | [Agent Memory](https://agentnas.com/de/concepts/agent-memory/) |
| `nas_recall` | Notizen abrufen: budgetiert, mit Quellen und Review-Status | `read` | [Agent Memory](https://agentnas.com/de/concepts/agent-memory/) |

> **Aktionen nur für Menschen und Betreiber.** `explain`, `gate approve/deny`, `forget`, `trash restore`, `label admin`, `lease revoke` und `policy edit` werden Agenten **nicht angeboten**. Diese Aktionen verändern die Garantien selbst und sollten nicht von der Partei aufrufbar sein, die eingeschränkt wird. Ein Agent darf einige davon **anfordern** (weitergehende Befugnis, Vergessen), aber nicht ausführen.

## Mount-Semantik

- Ein Mount bindet **einen Branch und eine Lease**; läuft die Lease ab, wird der Mount schreibgeschützt und danach ausgehängt.
- Automatische Commits (entprellt, zum Beispiel nach 5 ruhigen Sekunden); `fsync` löst einen Commit aus.
- Pfade außerhalb der Lease **erscheinen nicht in Verzeichnislisten:** Das verringert das Durchsickern von Informationen und verkleinert die Angriffsfläche für Prompt Injection.
- Sandbox-freundlich: kein Root nötig; FUSE oder NFS, eines von beiden, ohne Kernelmodul; schreibgeschützte Mounts sind möglich.

| Situation | POSIX-Fehler | Hinweis |
| --- | --- | --- |
| Ein Pfad außerhalb der Lease | `ENOENT` (`EACCES`, wenn sichtbar, aber verweigert) | Die Ablehnung wird protokolliert. |
| Kontingent oder Budget erschöpft | `EDQUOT` | Lässt die Ausführung sich selbst drosseln. |
| Gate ausstehend | `EACCES`, mit einer Erklärung in `/.nas/pending` | Verhindert, dass der Agent endlos wiederholt. |
| Lease abgelaufen | `ESTALE`, danach schreibgeschützt | Der Branch bleibt, bis seine eigene TTL abläuft. |

## Git

- Run-Branches heißen `<role>/<run_id>`; `main` ist geschützt, und ein serverseitiger `pre-receive`-Hook lehnt direkte Pushes ab.
- `nas propose` erstellt einen Agent PR.
- Commits tragen automatisch Trailer wie `Run:`, `Lease:` und `Principal:`.

## S3

- Ein Bucket entspricht einer Branch-Ansicht eines Trees; die Versions-ID eines Objekts ist ein Commit.
- Semantik, die S3 fehlt, etwa Branches, wird über ein Bucket-Präfix oder einen Request-Header (`x-nas-branch`) ausgedrückt. Das ist eine **abgeschwächte Projektion:** Datenpipelines können lesen und schreiben, bekommen aber nicht die volle Branch-Erfahrung.
- Leases werden als temporäre Zugangsdaten im STS-Stil übergeben.

## A2A (optional)

- Eingehende Aufgaben landen als Aufgabendateien in `inbox/`; Ergebnisse kommen nach `outbox/`.
- Die Agent Card erklärt die Skills der Rolle und die Leases, die sie braucht.
- **Das NAS ist kein A2A-Teilnehmer;** teilnehmen tut die Laufzeitumgebung, die für die Rolle handelt. Das NAS speichert nur Aufgaben und Ergebnisse, Übergabepakete und Leases.

## Konventionen der HTTP-API

- **Jeder Endpunkt nutzt `POST`, mit Parametern in einem JSON-Body;** Antwortfelder sind immer `snake_case`.
- Pfade sind versioniert: `/v1/...`.
- Idempotenz: Schreiboperationen akzeptieren einen `idempotency_key`.
- Paginierung: `cursor` plus `limit`.
- Budgets und Ratenlimits werden in Antwort-Headern zurückgemeldet (verbleibende Bytes, verbleibende Anfragen), damit sich Laufzeitumgebungen selbst drosseln können.

Eine budgetierte Leseanfrage und ihre Antwort sehen ungefähr so aus:

*Budgetiertes Lesen*

```http
POST /v1/files/read
{ "path": "/agents/cleo/memory/notes/customer-acme.md",
  "view": "outline", "budget_tokens": 400 }

200 OK
{ "view": "outline", "tokens": 212, "generated": false, "truncated": false,
  "content": "# Acme\n## Renewal (L12-L18)\n## Contacts (L19-L31)\n## Open issues (L32-L40)",
  "evidence": [
    { "pointer": "nas://home-box/agents/cleo/memory/notes/customer-acme.md@9f2c1de#L1-L40" }
  ] }
```

Fehler haben eine einheitliche Struktur:

*Fehlerantwort*

```json
{
  "error": {
    "code": "gate_required",
    "message": "This merge requires human approval.",
    "retryable": false,
    "request_id": "req_01JB7W2X4N",
    "details": { "gate_id": "gt_2Mx4" }
  }
}
```

## Auffindbarkeit

- Die maschinenlesbaren Einstiegspunkte entsprechen denen dieser Website: `/.well-known/ai-catalog.json`, die MCP Server Card und `llms.txt`.
- Ein Endpunkt, der `nas://`-Belegzeiger auflöst und prüft.
- MCP `server/discover`.

---

Kanonische URL: https://agentnas.com/de/interfaces/
Aktualisiert am: 2026-11-11 · Spezifikationsentwurf v0.2 · CC BY 4.0