Agent NAS v0.2
Español

Arquitectura

Agent NAS tiene cuatro capas y una capa de sincronización opcional: Interface proyecta las capacidades en interfaces existentes, Trust es el único punto de autorización, Memory convierte las notas en conocimiento consultable y Store guarda un árbol con historial. La capa Memory se puede borrar y reconstruir entera, y Store simplemente usa almacenamiento maduro.

v0.2 Borrador de especificación Actualizado

Cuatro capas y sincronización opcional

  1. Interface (interfaz)

    Proyecta las capacidades en interfaces que los agentes, las personas y las herramientas ya usan. Las pasarelas no tienen estado y nunca deciden quién puede hacer qué.

    • Montaje (FUSE, NFS, SMB)
    • Git
    • Compatible con S3
    • WebDAV
    • MCP
    • API HTTP
    • CLI
    • A2A (opcional)
  2. Trust (confianza)

    El único punto de autorización. Un motor de políticas determinista sin ningún modelo en la decisión; primero se registra y después se actúa.

    • Sujetos y ejecuciones
    • Capability Lease
    • Motor de políticas
    • Human Gate
    • Trust Labels
    • Credential Broker
    • Flight Recorder
  3. Memory (memoria)

    Convierte las notas en conocimiento consultable y legible con presupuesto. Todo se puede reconstruir a partir de la capa inferior.

    • Convenciones de notas
    • Índices (texto completo, vectorial, grafo)
    • Budgeted Reads
    • Tareas de mantenimiento
    • Linaje
    • Cascade Forget
  4. Store (almacén)

    Un árbol con historial, sobre instantáneas maduras del sistema de archivos, Git o almacenamiento de objetos versionado. No entiende la memoria ni las etiquetas.

    • Tree
    • Commit
    • Agent Branch
    • Instantáneas del sistema de archivos
    • Git
    • Almacenamiento de objetos
Sync (sincronización, opcional)

Replicación y uso compartido entre nodos. Va al final a propósito: primero hay que dejar bien un solo nodo.

  • Remotos de Git
  • Transferencia de instantáneas
  • Enlaces de concesión
  • Paquetes de traspaso
  • La capa Memory es reconstruible. Borra todos los índices y reconstruye, y las notas de Store siguen siendo totalmente legibles.
  • Las pasarelas no tienen estado. Todo el estado persistente está en Store y en los registros de Trust; una pasarela puede reiniciarse libremente y escalar en horizontal.
  • Trust es el único punto de autorización. Eso incluye las tareas en segundo plano del propio NAS (indexación, mantenimiento): también se ejecutan como principals svc:* con concesiones.
  • Store no entiende la memoria ni la semántica de las etiquetas. Solo guarda un árbol con metadatos.
  • Primero se registra, después se actúa. Una operación con consecuencias debe escribir antes un registro de intención.

La cintura estrecha: seis sustantivos

Todo el diseño depende de seis sustantivos; las etiquetas, las compuertas, la memoria y los manifiestos de lectura son convenciones construidas encima.

SustantivoSignificadoInvariante clave
TreeUn árbol de directorios con historial.Cualquier commit se puede reproducir; hay un hash de contenido o una detección de cambios equivalente.
CommitUn cambio inmutable.Lleva metadatos de procedencia: principal, on_behalf_of, run, lease.
PrincipalUna entidad que puede autenticarse y rendir cuentas.El tipo es human, agent, service o node; un agent pertenece a un rol, no a una ejecución.
RunUna ejecución con principio, fin, propósito y un responsable.Tiene una concesión raíz; es dueña de una rama.
LeaseLa autorización de una ejecución.Tiene caducidad; solo se puede acotar más; es revocable; lleva presupuestos.
RecordUn registro de solo anexado.Encadenado por hashes; primero se registra, después se actúa.

La capa Store: contrato y motores opcionales

El contrato de Store lo proporciona un motor o lo emula la pasarela. Una implementación puede combinar motores, por ejemplo Git para el texto e instantáneas para los archivos grandes; el contrato no prescribe el motor, la función hash ni el formato en disco.

  1. Commits atómicos.
  2. Bifurcaciones baratas: idealmente cercanas a O(1); en el peor caso degradándose a una copia, y entonces las cuotas y un TTL son obligatorios.
  3. Instantáneas inmutables.
  4. Detección de cambios: un hash de contenido o un equivalente.
  5. La diferencia entre dos commits.
  6. Exportación completa en un formato estándar: un directorio, el historial de Git y los metadatos .nas/ en texto plano.
MotorAdecuado paraCoste de bifurcarNota
Git (con worktrees)Texto, memoria, habilidades, bases de código pequeñasBajoLos archivos grandes necesitan LFS o almacenamiento externo; las fusiones binarias son malas.
Instantáneas y clones del sistema de archivos (ZFS, btrfs, APFS)Directorios grandes, archivos mixtosCercano a O(1)Depende del sistema de archivos; copiar entre máquinas necesita send/receive.
Almacenamiento de objetos versionado (forks de Tigris, lakeFS, S3 más un manifiesto)Conjuntos de datos, archivos grandesCercano a O(1)Necesita que la pasarela ofrezca una vista de archivos.
Directorio normal más copiaEmpezar con LiteO(n)Solo para datos pequeños; las cuotas y un TTL son obligatorios.

La vía de recuperación queda fuera del radio de impacto

Las instantáneas y las copias de seguridad están en manos del principal propietario, y ninguna concesión puede incluir “borrar una instantánea” ni “borrar una copia de seguridad”. Es la lección más directa del incidente de abril de 2026: la vía de recuperación debe quedar fuera del radio de impacto de lo que protege.

  • El cifrado en reposo viene de la capa inferior; la clase de retención sensitive usa su propio dominio de claves, de modo que se puede destruir eliminando la clave.
  • La deduplicación y la destrucción entran en conflicto: la clase sensitive no se deduplica entre dominios de claves.

El recorrido de una ejecución

  1. Solicitar. El orquestador (o el propietario) solicita una concesión para una ejecución: rutas, acciones, caducidad, propósito. Dentro del sobre de políticas se emite de forma automática; fuera de él pasa a una Human Gate.
  2. Empezar. El NAS crea el run y la rama <role>/<run_id> y entrega la concesión a la ejecución; el sandbox monta la rama (o hace un git clone).
  3. Trabajar. El agente lee y escribe con herramientas de archivos normales. Las lecturas se acumulan en el manifiesto de lectura y la contaminación de la sesión se actualiza con ellas; el acceso fuera de los límites se rechaza y se registra.
  4. Hacer commit. Los cambios se confirman con un commit de forma automática (con retardo) o explícita, y cada commit lleva metadatos de procedencia.
  5. Proponer. propose crea un Agent PR: el diff, la intención, un resumen del manifiesto de lectura, los resultados de las comprobaciones y un resumen de etiquetas.
  6. Decidir. El motor de políticas decide: si las comprobaciones pasan y el riesgo es bajo, se fusiona de forma automática; si hay datos protegidos, una acción hacia el exterior o una violación de la Rule of Two, pasa a una Human Gate; si está claramente prohibido, se rechaza.
  7. Fusionar y registrar. La fusión crea un commit con procedencia y escribe un Record.
  8. Cerrar. La concesión caduca; la rama se recicla tras su TTL; los manifiestos de lectura y los Records se conservan según la política de retención.

La ruta de lectura: solicitud, comprobación de la concesión, comprobación de etiquetas (¿permite la contaminación actual de la sesión esta lectura?), recuento del presupuesto, lectura desde Store, anotación en el manifiesto de lectura, y devolución del contenido y de los punteros de evidencia.

Primero se registra, después se actúa

Una operación con consecuencias (fusionar, borrar, compartir, enviar al exterior, cambiar una concesión) debe escribir antes un registro de intención; si no se puede escribir, la operación falla (fail closed). Las lecturas van al manifiesto de lectura, que se vuelca por lotes y no necesita ser síncrono en cada lectura.

Formas de despliegue

FormaDescripciónAdecuado para
LiteUna sola máquina y un solo usuario: un proceso de pasarela más almacenamiento local (Git o instantáneas del sistema de archivos); L0 a L1.Particulares y desarrolladores que lo prueban.
OverlayDeja en paz el NAS o el almacén de objetos existente: una pasarela se coloca delante y gestiona solo un directorio o un bucket; los montajes y la vista S3 pasan por la pasarela.El punto de partida más realista: quien ya tiene un equipo.
TeamVarios usuarios y agentes, un servidor o un clúster pequeño; L0 a L3; notificaciones de compuertas y una sala de control.Equipos pequeños.
CloudUn servicio alojado multiinquilino con aislamiento fuerte; L0 a L3.Quien no tiene hardware propio.

El principio: no se necesita hardware especial y vale cualquier máquina siempre encendida; los aceleradores son opcionales, porque bastan modelos pequeños para los embeddings y los resúmenes, y también se pueden llamar servicios externos.

Construir una v0 con piezas existentes

CapacidadPiezas que puedes usar hoy
Store y ramasGit y worktrees; instantáneas de btrfs o ZFS; o Tigris y lakeFS (almacenamiento de objetos).
Línea principal protegidaProtección de ramas en Forgejo, Gitea o GitHub; o ramas protegidas de lakeFS.
ConcesionesUn servidor de autorización OAuth (por ejemplo Keycloak) con intercambio de tokens, y un servidor de recursos que compruebe el prefijo de la ruta y la acción; o un servicio de firma de unos cientos de líneas.
RegistrosUna tabla SQLite de solo anexado más un hash diario; trailers de Git en los commits; exportación con OpenTelemetry.
CompuertasRevisión de PR más una notificación push; la CLI nas gate approve.
MemoriaMarkdown bajo memory/ más SQLite FTS5; un almacén vectorial se añade después.
EtiquetasMarca el directorio de importación como external; guarda la contaminación de sesión de cada ejecución en la pasarela.
InterfacesUn montaje NFS, SMB o FUSE; Git sobre SSH o HTTPS; una pasarela S3; un pequeño servidor MCP.

Lo que dice esta tabla: L0 y L1 no necesitan ninguna invención nueva. Lo nuevo es el contrato que los combina y las pruebas que lo verifican; consulta la especificación.

Operación

  • Copias de seguridad: 3-2-1; las instantáneas y las copias de seguridad pertenecen al principal propietario y ninguna concesión puede tocarlas; haz un simulacro de restauración cada trimestre y guarda un registro.
  • Actualizaciones: las pasarelas no tienen estado y se pueden actualizar de forma gradual; cualquier cambio de formato de Store debe llevar un plan de migración y de reversión; la capa Memory se puede reconstruir entera.
  • Supervisión: tasas de emisión y denegación de concesiones; longitud de la cola de compuertas y tasa de aprobación (una tasa de aprobación que se mantiene por encima del 95 % indica que las compuertas son demasiado frecuentes y conviene fusionarlas o endurecer la política); número y antigüedad de las ramas; frescura de los índices; verificación de la cadena de registros; cuotas.
  • Capacidad: las ramas tienen un TTL y cuotas; la papelera tiene un período de retención; los datos derivados tienen un presupuesto.

La sala de control

La interfaz para las personas puede ser una página web, una CLI o un chatbot. No es esencial: L0 a L1 pueden funcionar por completo con una CLI y una plataforma Git existente.

  • Línea de actividad: agregada por ejecución: quién hizo qué y qué leyó.
  • Bandeja de compuertas: acciones pendientes de aprobación, mostradas como Gate Cards.
  • Directorio de roles: el Home de cada rol, sus concesiones, presupuestos y ejecuciones recientes.
  • Explorador de memoria: notas y fuentes, la cuarentena de notas sin revisar, propuestas de mantenimiento.
  • Ramas y PR: ramas sin fusionar y la papelera.
  • Consola de olvido: solicitudes, vista previa del linaje e informes.

Las personas también pueden mirar directamente por SMB o WebDAV: /humans/<user>/Agent Activity/ es una vista de actividad de solo lectura hecha de archivos normales.

Citar esta página

Direcciones estables y una cita sugerida para personas, buscadores y agentes.

Cita sugerida
Agent NAS project. “Arquitectura.” agentnas.com, 2026-11-11. https://agentnas.com/es/architecture/