Architecture
Agent NAS a quatre couches et une couche de synchronisation optionnelle : Interface projette les capacités dans des interfaces existantes, Trust est le seul point d’autorisation, Memory transforme les notes en connaissances interrogeables, et Store conserve un arbre avec historique. La couche Memory peut être supprimée et reconstruite en bloc, et Store utilise simplement un stockage éprouvé.
Quatre couches et une synchronisation optionnelle
- Interface
Projette les capacités dans des interfaces que les agents, les personnes et les outils utilisent déjà. Les passerelles sont sans état et ne décident jamais qui peut faire quoi.
- Montage (FUSE, NFS, SMB)
- Git
- Compatible S3
- WebDAV
- MCP
- API HTTP
- CLI
- A2A (optionnel)
- Trust (confiance)
Le seul point d’autorisation. Un moteur de politiques déterministe, sans modèle dans la décision ; enregistrer d’abord, agir ensuite.
- Principals et exécutions
- Capability Lease
- Moteur de politiques
- Human Gate
- Trust Labels
- Credential Broker
- Flight Recorder
- Memory (mémoire)
Transforme les notes en connaissances interrogeables et lisibles dans la limite d’un budget. Tout peut être reconstruit à partir de la couche inférieure.
- Conventions de notes
- Index (texte intégral, vectoriel, graphe)
- Budgeted Reads
- Tâches de maintenance
- Lignage
- Cascade Forget
- Store (stockage)
Un arbre avec historique, sur des instantanés de système de fichiers éprouvés, Git ou un stockage objet versionné. Il ne comprend ni la mémoire ni les étiquettes.
- Tree
- Commit
- Agent Branch
- Instantanés du système de fichiers
- Git
- Stockage objet
Réplication et partage entre nœuds. Placée en dernier à dessein : il faut d’abord réussir un seul nœud.
- Dépôts Git distants
- Transfert d’instantanés
- Liens d’habilitation
- Paquets de passation
- La couche Memory est reconstructible. Supprimez tous les index et reconstruisez : les notes de Store restent entièrement lisibles.
- Les passerelles sont sans état. Tout l’état persistant est dans Store et dans les enregistrements de Trust ; une passerelle peut redémarrer librement et monter en charge horizontalement.
- Trust est le seul point d’autorisation. Cela inclut les tâches d’arrière-plan du NAS lui-même (indexation, maintenance) : elles s’exécutent aussi comme des principals
svc:*détenteurs d’habilitations. - Store ne comprend ni la mémoire ni la sémantique des étiquettes. Il se contente de conserver un arbre avec des métadonnées.
- Enregistrer d’abord, agir ensuite. Une opération à conséquences doit d’abord écrire un enregistrement d’intention.
Le noyau étroit : six substantifs
Toute la conception repose sur six substantifs ; les étiquettes, les validations, la mémoire et les manifestes de lecture sont des conventions construites par-dessus.
| Substantif | Signification | Invariant clé |
|---|---|---|
| Tree | Une arborescence de répertoires avec historique. | N’importe quel commit peut être reproduit ; il existe un hachage de contenu ou une détection de changement équivalente. |
| Commit | Une modification immuable. | Porte des métadonnées de provenance : principal, on_behalf_of, run, lease. |
| Principal | Une entité qui peut être authentifiée et tenue pour responsable. | Le type est human, agent, service ou node ; un agent appartient à un rôle, pas à une seule exécution. |
| Run | Une exécution avec un début, une fin, un but et un responsable. | Détient une habilitation racine ; possède une branche. |
| Lease | L’autorisation d’une exécution. | A une expiration ; ne peut être que restreinte ; révocable ; porte des budgets. |
| Record | Un enregistrement en ajout seul. | Chaîné par hachage ; enregistrer d’abord, agir ensuite. |
La couche Store : contrat et moteurs optionnels
Le contrat Store est fourni par un moteur ou émulé par la passerelle. Une implémentation peut combiner des moteurs, par exemple Git pour le texte et des instantanés pour les gros fichiers ; le contrat ne prescrit ni le moteur, ni la fonction de hachage, ni le format sur disque.
- Commits atomiques.
- Forks peu coûteux : idéalement proches de O(1) ; au pire dégradés en copie, auquel cas les quotas et un TTL sont obligatoires.
- Instantanés immuables.
- Détection des changements : un hachage de contenu ou un équivalent.
- La différence entre deux commits.
- Export complet dans un format standard : un répertoire, l’historique Git et les métadonnées en texte brut de
.nas/.
| Moteur | Adapté à | Coût d’un fork | Remarque |
|---|---|---|---|
| Git (avec worktrees) | Texte, mémoire, compétences, petits codes sources | Faible | Les gros fichiers demandent LFS ou un stockage externe ; les fusions binaires sont médiocres. |
| Instantanés et clones de système de fichiers (ZFS, btrfs, APFS) | Grands répertoires, fichiers variés | Environ O(1) | Dépend du système de fichiers ; la copie entre machines demande send/receive. |
| Stockage objet versionné (forks Tigris, lakeFS, S3 plus un manifeste) | Jeux de données, gros fichiers | Environ O(1) | La passerelle doit fournir une vue de fichiers. |
| Répertoire simple plus copie | Démarrer avec Lite | O(n) | Seulement pour de petites données ; quotas et TTL obligatoires. |
Le chemin de reprise est hors du rayon d’impact
Les instantanés et les sauvegardes sont détenus par le principal propriétaire, et aucune habilitation ne peut inclure « supprimer un instantané » ou « supprimer une sauvegarde ». C’est la leçon la plus directe de l’incident d’avril 2026 : le chemin de reprise doit se trouver hors du rayon d’impact de ce qu’il protège.
- Le chiffrement au repos vient de la couche inférieure ; la classe de rétention
sensitiveutilise son propre domaine de clés, de sorte qu’elle peut être détruite en détruisant la clé. - La déduplication et la destruction sont en conflit : la classe
sensitiven’est pas dédupliquée entre domaines de clés.
Le parcours d’une exécution
- Demande. L’orchestrateur (ou le propriétaire) demande une habilitation pour une exécution : chemins, actions, expiration, objectif. Dans l’enveloppe de politiques, elle est émise automatiquement ; en dehors, elle passe par une Human Gate.
- Démarrage. Le NAS crée le
runet la branche<role>/<run_id>, et remet l’habilitation à l’exécution ; le sandbox monte la branche (ou fait ungit clone). - Travail. L’agent lit et écrit avec des outils de fichiers ordinaires. Les lectures s’accumulent dans le manifeste de lecture et la contamination de session évolue avec elles ; tout accès hors limites est refusé et enregistré.
- Commit. Les modifications sont versionnées dans un commit automatiquement (avec temporisation) ou explicitement, et chaque commit porte des métadonnées de provenance.
- Proposition.
proposecrée une Agent PR : le diff, l’intention, un résumé du manifeste de lecture, les résultats des vérifications et un résumé des étiquettes. - Décision. Le moteur de politiques décide : si les vérifications passent et que le risque est faible, fusion automatique ; si des données protégées, une action vers l’extérieur ou une violation de la Rule of Two sont en jeu, passage par une Human Gate ; si c’est clairement interdit, refus.
- Fusion et enregistrement. La fusion crée un commit avec provenance et écrit un Record.
- Clôture. L’habilitation expire ; la branche est recyclée après son TTL ; les manifestes de lecture et les Records sont conservés selon la politique de rétention.
Le chemin de lecture : requête, vérification de l’habilitation, vérification des étiquettes (la contamination actuelle de la session autorise-t-elle cette lecture ?), comptage du budget, lecture dans Store, enregistrement dans le manifeste de lecture, retour du contenu et des pointeurs de preuve.
Enregistrer d’abord, agir ensuite
Une opération à conséquences (fusion, suppression, partage, sortie de données, changement d’habilitation) doit d’abord écrire un enregistrement d’intention ; s’il ne peut pas être écrit, l’opération échoue (échec en mode fermé). Les lectures vont dans le manifeste de lecture, vidé par lots, sans exigence de synchronisme à chaque lecture.
Formes de déploiement
| Forme | Description | Adaptée à |
|---|---|---|
| Lite | Une seule machine, un seul utilisateur : un processus de passerelle plus un stockage local (Git ou instantanés de système de fichiers) ; L0 à L1. | Les particuliers et les développeurs qui essaient. |
| Overlay | Laisse le NAS ou le stockage objet existant tel quel : une passerelle se place devant et ne gère qu’un seul répertoire ou bucket ; les montages et la vue S3 passent par la passerelle. | Le point de départ le plus réaliste : ceux qui ont déjà un boîtier. |
| Team | Plusieurs utilisateurs et agents, un serveur ou un petit cluster ; L0 à L3 ; notifications de validation et salle de contrôle. | Les petites équipes. |
| Cloud | Un service hébergé multi-locataire avec une isolation forte ; L0 à L3. | Ceux qui n’ont pas leur propre matériel. |
Le principe : aucun matériel spécial n’est requis, et n’importe quelle machine allumée en permanence convient ; les accélérateurs sont optionnels, car de petits modèles suffisent pour les embeddings et les résumés, et des services externes peuvent aussi être appelés.
Construire une v0 avec des briques existantes
| Capacité | Briques utilisables dès aujourd’hui |
|---|---|
| Store et branches | Git et worktrees ; instantanés btrfs ou ZFS ; ou Tigris et lakeFS (stockage objet). |
| Ligne principale protégée | La protection de branche de Forgejo, Gitea ou GitHub ; ou les branches protégées de lakeFS. |
| Habilitations | Un serveur d’autorisation OAuth (par exemple Keycloak) avec échange de jetons, et un serveur de ressources qui vérifie le préfixe de chemin et l’action ; ou un service de signature de quelques centaines de lignes. |
| Enregistrements | Une table SQLite en ajout seul plus un hachage quotidien ; des trailers Git dans les commits ; un export OpenTelemetry. |
| Validations | Une revue de PR plus une notification push ; la CLI nas gate approve. |
| Mémoire | Du Markdown sous memory/ plus SQLite FTS5 ; ajoutez un magasin vectoriel plus tard. |
| Étiquettes | Marquer le répertoire d’import external ; garder la contamination de session de chaque exécution dans la passerelle. |
| Interfaces | Un montage NFS, SMB ou FUSE ; Git sur SSH ou HTTPS ; une passerelle S3 ; un petit serveur MCP. |
Ce que dit ce tableau : L0 et L1 n’exigent aucune invention nouvelle. Ce qui est nouveau, c’est le contrat qui les combine et les tests qui le vérifient ; voir la spécification.
Exploitation
- Sauvegardes : 3-2-1 ; les instantanés et les sauvegardes appartiennent au principal propriétaire et aucune habilitation ne peut y toucher ; faites un exercice de restauration chaque trimestre et gardez-en une trace.
- Mises à jour : les passerelles sont sans état et peuvent être mises à jour progressivement ; tout changement de format de Store doit s’accompagner d’un plan de migration et de retour arrière ; la couche Memory peut être reconstruite en bloc.
- Supervision : taux d’émission et de refus des habilitations ; longueur de la file des validations et taux d’approbation (un taux d’approbation qui reste au-dessus de 95 % indique que les validations sont trop fréquentes et qu’il faut les regrouper ou resserrer la politique) ; nombre et âge des branches ; fraîcheur des index ; vérification de la chaîne d’enregistrements ; quotas.
- Capacité : les branches ont un TTL et des quotas ; la corbeille a une durée de rétention ; les données dérivées ont un budget.
La salle de contrôle
L’interface destinée aux personnes peut être une page web, une CLI ou un chatbot. Elle n’est pas indispensable : L0 à L1 peuvent fonctionner entièrement avec une CLI et une plateforme Git existante.
- Chronologie d’activité : agrégée par exécution : qui a fait quoi, et ce qu’il a lu.
- Boîte des validations : les actions en attente d’approbation, présentées sous forme de Gate Cards.
- Annuaire des rôles : le Home de chaque rôle, ses habilitations, ses budgets et ses exécutions récentes.
- Navigateur de mémoire : notes et sources, quarantaine des notes non relues, propositions de maintenance.
- Branches et PR : branches non fusionnées et corbeille.
- Console d’oubli : demandes, aperçu du lignage et rapports.
Les personnes peuvent aussi regarder directement via SMB ou WebDAV : /humans/<user>/Agent Activity/ est une vue d’activité en lecture seule faite de fichiers ordinaires.
Citer cette page
Des adresses stables et une citation suggérée, pour les personnes, les moteurs de recherche et les agents.
- URL canonique
- https://agentnas.com/fr/architecture/
- Version Markdown
- https://agentnas.com/fr/architecture/index.md
- Citation suggérée
- Agent NAS project. “Architecture.” agentnas.com, 2026-11-11. https://agentnas.com/fr/architecture/