# Interfaces

> Agent NAS utilise des fichiers pour le plan de données et des outils pour le plan de contrôle : les octets circulent par montage, Git et S3 ; l’autorisation, l’approbation, la mémoire, la recherche et l’explication passent par MCP, HTTP et une CLI. Chaque interface est une projection des mêmes données, et les différences de sémantique s’expriment par des erreurs explicites au lieu d’être gommées.

## Principes

1. **Des fichiers pour le plan de données, des outils pour le plan de contrôle.** Les octets circulent par montage, Git et S3 ; l’autorisation, l’approbation, la mémoire, la recherche et l’explication passent par MCP, HTTP et une CLI.
2. **Les passerelles sont sans état.** L’autorisation a lieu en un seul point de la couche Trust.
3. **Chaque interface est une projection.** Les différences de sémantique s’expriment par des correspondances d’erreurs explicites (par exemple, « validation en attente » devient un `EACCES` accompagné d’un fichier explicatif), et S3 ne fait pas semblant d’avoir des branches.
4. **Une surface d’outils étroite.** Pas plus de 10 outils MCP face aux agents ; les actions pour les personnes et les opérateurs vivent dans une interface d’opérateur distincte.
5. **Les adaptateurs isolent l’évolution des protocoles.** Les changements de version de MCP et d’A2A n’affectent que les adaptateurs.

## Matrice des interfaces

| Interface | Plan | Destinée à | Correspondance | Niveau |
| --- | --- | --- | --- | --- |
| Montage (FUSE, NFS, SMB) | Données | Agents, personnes, tout programme | Une vue de branche ; correspondance des erreurs ci-dessous | L0 |
| Git (SSH, HTTPS) | Données | Agents, personnes, CI | Une branche d’exécution est une branche Git ; une Agent PR est une demande de fusion | L0 |
| Compatible S3 | Données | Pipelines de données, traitements par lots | Un bucket correspond à la vue de branche d’un arbre ; un identifiant de version est un commit | L0 (optionnel) |
| WebDAV | Données | Personnes (Finder, Explorateur) | Une vue d’activité en lecture seule | L0 (optionnel) |
| CLI `nas` | Contrôle | Personnes, scripts | Une correspondance un pour un avec l’API HTTP | L0 |
| API HTTP | Contrôle | Orchestrateurs, salle de contrôle | Tout en `POST` avec du JSON ; champs en `snake_case` | L1 |
| MCP | Contrôle | Agents | Neuf outils (ci-dessous) | L1, L2 |
| A2A | Contrôle | Autres agents | Une tâche correspond à `inbox/` et `outbox/` | L4 (optionnel) |

## La surface d’outils MCP

Seuls neuf outils s’adressent aux agents :

| Outil | Ce qu’il fait | Action d’habilitation requise | Remarque |
| --- | --- | --- | --- |
| `nas_list` | Liste un répertoire, avec les étiquettes et l’état de relecture | `list` | Les chemins hors de l’habilitation sont invisibles. |
| `nas_read` | Lecture avec budget : vue, plage, budget | `read` | [Budgeted Reads](https://agentnas.com/fr/concepts/budgeted-reads/) |
| `nas_search` | Recherche (texte intégral, éventuellement vectorielle), renvoie des extraits et des pointeurs | `read` | La quarantaine est exclue par défaut. |
| `nas_write` | Écrit un fichier dans la branche, avec un `intent` facultatif | `write` | La plupart des runtimes utilisent directement le montage et n’en ont pas besoin. |
| `nas_branch` | Crée, pose un point de contrôle, restaure et liste les branches | `write` | [Agent Branch](https://agentnas.com/fr/concepts/agent-branch/) |
| `nas_propose` | Crée une Agent PR | `propose` | Peut déclencher une validation. |
| `nas_lease` | Demande une habilitation fille plus étroite ; interroge l’habilitation actuelle et les budgets ; demande une autorité plus large (via une validation) | Aucune | [Capability Lease](https://agentnas.com/fr/concepts/capability-lease/) |
| `nas_remember` | Écrit une note, avec des sources et un genre | `write` | [Agent Memory](https://agentnas.com/fr/concepts/agent-memory/) |
| `nas_recall` | Rappelle des notes : avec budget, sources et état de relecture | `read` | [Agent Memory](https://agentnas.com/fr/concepts/agent-memory/) |

> **Actions réservées aux personnes et aux opérateurs.** `explain`, `gate approve/deny`, `forget`, `trash restore`, `label admin`, `lease revoke` et `policy edit` ne sont **pas exposées** aux agents. Ces actions changent les garanties elles-mêmes et ne doivent pas pouvoir être appelées par la partie qu’elles contraignent. Un agent peut en **demander** certaines (autorité plus large, oubli) mais ne peut pas les exécuter.

## Sémantique du montage

- Un montage lie **une branche et une habilitation** ; à l’expiration de l’habilitation, le montage passe en lecture seule puis est démonté.
- Commits automatiques (avec temporisation, par exemple après 5 secondes de calme) ; `fsync` déclenche un commit.
- Les chemins hors de l’habilitation **n’apparaissent pas dans les listings de répertoires :** cela réduit les fuites d’information et la surface d’attaque de l’injection de prompt.
- Adapté au sandbox : pas de root nécessaire ; FUSE ou NFS, l’un des deux, sans module noyau ; les montages en lecture seule sont possibles.

| Situation | Erreur POSIX | Remarque |
| --- | --- | --- |
| Un chemin hors de l’habilitation | `ENOENT` (`EACCES` quand il est visible mais refusé) | Le refus est enregistré. |
| Quota ou budget épuisé | `EDQUOT` | Permet à l’exécution de s’autolimiter. |
| Validation en attente | `EACCES`, avec une explication dans `/.nas/pending` | Évite que l’agent réessaie indéfiniment. |
| Habilitation expirée | `ESTALE`, puis lecture seule | La branche est conservée jusqu’à l’expiration de son propre TTL. |

## Git

- Les branches d’exécution se nomment `<role>/<run_id>` ; `main` est protégée, et un hook `pre-receive` côté serveur rejette les pushs directs.
- `nas propose` crée une Agent PR.
- Les commits portent automatiquement des trailers tels que `Run:`, `Lease:` et `Principal:`.

## S3

- Un bucket correspond à la vue de branche d’un arbre ; l’identifiant de version d’un objet est un commit.
- Les sémantiques qui manquent à S3, comme les branches, s’expriment par un préfixe de bucket ou un en-tête de requête (`x-nas-branch`). C’est une **projection dégradée :** les pipelines de données peuvent lire et écrire, mais n’ont pas l’expérience complète des branches.
- Les habilitations sont transmises sous forme d’identifiants temporaires de type STS.

## A2A (optionnel)

- Les tâches entrantes arrivent sous forme de fichiers de tâche dans `inbox/` ; les livrables vont dans `outbox/`.
- L’Agent Card déclare les compétences du rôle et les habilitations dont il a besoin.
- **Le NAS n’est pas un participant A2A ;** c’est le runtime qui agit pour le rôle qui l’est. Le NAS ne fait que stocker les tâches et les livrables, les paquets de passation et les habilitations.

## Conventions de l’API HTTP

- **Chaque endpoint utilise `POST`, avec les paramètres dans un corps JSON ;** les champs des réponses sont toujours en `snake_case`.
- Les chemins sont versionnés : `/v1/...`.
- Idempotence : les opérations d’écriture acceptent une `idempotency_key`.
- Pagination : `cursor` plus `limit`.
- Les budgets et les limites de débit sont renvoyés dans les en-têtes de réponse (octets restants, requêtes restantes) pour que les runtimes puissent s’autolimiter.

Une requête de lecture avec budget et sa réponse ressemblent à peu près à ceci :

*Lecture avec budget*

```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" }
  ] }
```

Les erreurs utilisent une structure uniforme :

*Réponse d’erreur*

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

## Découverte

- Les points d’entrée lisibles par les machines sont les mêmes que sur ce site : `/.well-known/ai-catalog.json`, la fiche de serveur MCP et `llms.txt`.
- Un point d’accès qui résout et vérifie les pointeurs de preuve `nas://`.
- MCP `server/discover`.

---

URL canonique : https://agentnas.com/fr/interfaces/
Mis à jour le: 2026-11-11 · Brouillon de spécification v0.2 · CC BY 4.0