# Interfaces

> Agent NAS usa archivos para el plano de datos y herramientas para el plano de control: los bytes viajan por montajes, Git y S3; la autorización, la aprobación, la memoria, la búsqueda y las explicaciones pasan por MCP, HTTP y una CLI. Cada interfaz es una proyección de los mismos datos, y las diferencias de semántica se expresan como errores explícitos en lugar de disimularlas.

## Principios

1. **Archivos para el plano de datos, herramientas para el plano de control.** Los bytes viajan por montajes, Git y S3; la autorización, la aprobación, la memoria, la búsqueda y las explicaciones pasan por MCP, HTTP y una CLI.
2. **Las pasarelas no tienen estado.** La autorización ocurre en un único punto de la capa Trust.
3. **Cada interfaz es una proyección.** Las diferencias de semántica se expresan con asignaciones de error explícitas (por ejemplo, “compuerta pendiente” se asigna a un `EACCES` con un archivo explicativo), y no se finge que S3 tenga ramas.
4. **Una superficie de herramientas estrecha.** No más de 10 herramientas MCP miran a los agentes; las acciones para personas y operadores viven en una interfaz de operador aparte.
5. **Los adaptadores aíslan el cambio de protocolo.** Los cambios de versión de MCP y A2A solo afectan a los adaptadores.

## Matriz de interfaces

| Interfaz | Plano | Dirigida a | Asignación | Nivel |
| --- | --- | --- | --- | --- |
| Montaje (FUSE, NFS, SMB) | Datos | Agentes, personas, cualquier programa | Una vista de rama; asignación de errores más abajo | L0 |
| Git (SSH, HTTPS) | Datos | Agentes, personas, CI | Una rama de ejecución es una rama de Git; un Agent PR es una solicitud de fusión | L0 |
| Compatible con S3 | Datos | Canalizaciones de datos, trabajos por lotes | Un bucket se asigna a una vista de rama de un árbol; un ID de versión es un commit | L0 (opcional) |
| WebDAV | Datos | Personas (Finder, Explorador) | Una vista de actividad de solo lectura | L0 (opcional) |
| CLI `nas` | Control | Personas, scripts | Uno a uno con la API HTTP | L0 |
| API HTTP | Control | Orquestadores, la sala de control | Todo `POST` con JSON; campos en `snake_case` | L1 |
| MCP | Control | Agentes | Nueve herramientas (más abajo) | L1, L2 |
| A2A | Control | Otros agentes | Una tarea se asigna a `inbox/` y `outbox/` | L4 (opcional) |

## La superficie de herramientas MCP

Solo nueve herramientas miran a los agentes:

| Herramienta | Qué hace | Acción de concesión necesaria | Nota |
| --- | --- | --- | --- |
| `nas_list` | Lista un directorio, con etiquetas y estado de revisión | `list` | Las rutas fuera de la concesión son invisibles. |
| `nas_read` | Lectura con presupuesto: vista, rango, presupuesto | `read` | [Budgeted Reads](https://agentnas.com/es/concepts/budgeted-reads/) |
| `nas_search` | Busca (texto completo, opcionalmente vectorial) y devuelve fragmentos y punteros | `read` | La cuarentena se excluye por defecto. |
| `nas_write` | Escribe un archivo dentro de la rama, con un `intent` opcional | `write` | La mayoría de los runtimes usan el montaje directamente y no lo necesitan. |
| `nas_branch` | Crea, marca puntos de control, restaura y lista ramas | `write` | [Agent Branch](https://agentnas.com/es/concepts/agent-branch/) |
| `nas_propose` | Crea un Agent PR | `propose` | Puede activar una compuerta. |
| `nas_lease` | Solicita una concesión hija más estrecha; consulta la concesión y los presupuestos actuales; solicita más autoridad (mediante una compuerta) | Ninguna | [Capability Lease](https://agentnas.com/es/concepts/capability-lease/) |
| `nas_remember` | Escribe una nota, con fuentes y tipo | `write` | [Agent Memory](https://agentnas.com/es/concepts/agent-memory/) |
| `nas_recall` | Recupera notas: con presupuesto, con fuentes y estado de revisión | `read` | [Agent Memory](https://agentnas.com/es/concepts/agent-memory/) |

> **Acciones solo para personas y operadores.** `explain`, `gate approve/deny`, `forget`, `trash restore`, `label admin`, `lease revoke` y `policy edit` **no se exponen** a los agentes. Estas acciones cambian las propias garantías y no debería poder invocarlas la parte a la que se restringe. Un agente puede **solicitar** algunas (más autoridad, olvido), pero no ejecutarlas.

## Semántica del montaje

- Un montaje enlaza **una rama y una concesión**; cuando la concesión caduca, el montaje pasa a solo lectura y después se desmonta.
- Commits automáticos (con retardo, por ejemplo tras 5 segundos de calma); `fsync` activa un commit.
- Las rutas fuera de la concesión **no aparecen en los listados de directorio:** esto reduce la fuga de información y la superficie de ataque de la inyección de prompts.
- Apto para sandboxes: no hace falta root; FUSE o NFS, uno de los dos, sin módulo del kernel; son posibles los montajes de solo lectura.

| Situación | Error POSIX | Nota |
| --- | --- | --- |
| Una ruta fuera de la concesión | `ENOENT` (`EACCES` cuando es visible pero está denegada) | El rechazo se registra. |
| Cuota o presupuesto agotados | `EDQUOT` | Permite que la ejecución se autolimite. |
| Compuerta pendiente | `EACCES`, con una explicación en `/.nas/pending` | Evita que el agente reintente para siempre. |
| Concesión caducada | `ESTALE`, y después solo lectura | La rama se conserva hasta que caduca su propio TTL. |

## Git

- Las ramas de ejecución se llaman `<role>/<run_id>`; `main` está protegida y un hook `pre-receive` en el servidor rechaza los push directos.
- `nas propose` crea un Agent PR.
- Los commits llevan automáticamente trailers como `Run:`, `Lease:` y `Principal:`.

## S3

- Un bucket corresponde a una vista de rama de un árbol; el ID de versión de un objeto es un commit.
- La semántica que S3 no tiene, como las ramas, se expresa con un prefijo de bucket o una cabecera de solicitud (`x-nas-branch`). Es una **proyección degradada:** las canalizaciones de datos pueden leer y escribir, pero no obtienen la experiencia completa de ramas.
- Las concesiones se pasan como credenciales temporales al estilo STS.

## A2A (opcional)

- Las tareas entrantes llegan como archivos de tarea en `inbox/`; los entregables van a `outbox/`.
- La Agent Card declara las habilidades del rol y las concesiones que necesita.
- **El NAS no es un participante de A2A;** lo es el runtime que actúa por el rol. El NAS solo almacena tareas y entregables, paquetes de traspaso y concesiones.

## Convenciones de la API HTTP

- **Todos los endpoints usan `POST`, con los parámetros en un cuerpo JSON;** los campos de respuesta son siempre `snake_case`.
- Las rutas llevan versión: `/v1/...`.
- Idempotencia: las operaciones de escritura aceptan una `idempotency_key`.
- Paginación: `cursor` más `limit`.
- Los presupuestos y los límites de frecuencia se devuelven en las cabeceras de la respuesta (bytes restantes, solicitudes restantes) para que los runtimes puedan autolimitarse.

Una solicitud y una respuesta de lectura con presupuesto se ven más o menos así:

*Lectura con presupuesto*

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

Los errores usan una estructura uniforme:

*Respuesta de error*

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

## Descubrimiento

- Los puntos de entrada legibles por máquinas son los mismos que en este sitio: `/.well-known/ai-catalog.json`, la Server Card de MCP y `llms.txt`.
- Un endpoint que resuelve y verifica los punteros de evidencia `nas://`.
- MCP `server/discover`.

---

URL canónica: https://agentnas.com/es/interfaces/
Actualizado: 2026-11-11 · Borrador de especificación v0.2 · CC BY 4.0