# 인터페이스

> Agent NAS는 데이터 플레인에는 파일을, 컨트롤 플레인에는 도구를 씁니다. 바이트는 마운트, Git, S3로 오가고, 인가, 승인, 메모리, 검색, 설명은 MCP, HTTP, CLI를 거칩니다. 모든 인터페이스는 같은 데이터의 투영이며, 의미의 차이는 없는 척하지 않고 명시적인 오류로 드러냅니다.

## 원칙

1. **데이터 플레인에는 파일, 컨트롤 플레인에는 도구.** 바이트는 마운트, Git, S3로 오가고, 인가, 승인, 메모리, 검색, 설명은 MCP, HTTP, CLI를 거칩니다.
2. **게이트웨이는 상태를 갖지 않습니다.** 인가는 Trust 계층의 단 한 곳에서만 이루어집니다.
3. **모든 인터페이스는 투영입니다.** 의미의 차이는 명시적인 오류 매핑으로 드러냅니다(예를 들어 “게이트 대기 중”은 설명 파일이 딸린 `EACCES`로 매핑됩니다). S3에 브랜치가 있는 척하지 않습니다.
4. **좁은 도구 표면.** 에이전트에게 노출되는 MCP 도구는 10개를 넘지 않으며, 사람과 운영자를 위한 동작은 별도의 운영자 인터페이스에 둡니다.
5. **어댑터가 프로토콜 변화를 격리합니다.** MCP와 A2A의 버전 변경은 어댑터에만 영향을 줍니다.

## 인터페이스 매트릭스

| 인터페이스 | 플레인 | 대상 | 매핑 | 수준 |
| --- | --- | --- | --- | --- |
| 마운트 (FUSE, NFS, SMB) | 데이터 | 에이전트, 사람, 모든 프로그램 | 브랜치 뷰. 오류 매핑은 아래 참조 | L0 |
| Git (SSH, HTTPS) | 데이터 | 에이전트, 사람, CI | 실행 브랜치는 Git 브랜치이고, Agent PR은 병합 요청 | L0 |
| S3 호환 | 데이터 | 데이터 파이프라인, 배치 작업 | 버킷은 한 트리의 브랜치 뷰에 대응하고, 버전 ID는 커밋 | L0 (선택) |
| WebDAV | 데이터 | 사람 (Finder, 탐색기) | 읽기 전용 활동 뷰 | L0 (선택) |
| CLI `nas` | 제어 | 사람, 스크립트 | HTTP API와 일대일 대응 | L0 |
| HTTP API | 제어 | 오케스트레이터, 컨트롤 룸 | 모두 JSON을 쓰는 `POST`, 필드는 `snake_case` | L1 |
| MCP | 제어 | 에이전트 | 아홉 개의 도구 (아래) | L1, L2 |
| A2A | 제어 | 다른 에이전트 | 작업은 `inbox/`와 `outbox/`에 대응 | L4 (선택) |

## MCP 도구 표면

에이전트에게 노출되는 도구는 아홉 개뿐입니다.

| 도구 | 하는 일 | 필요한 리스 동작 | 비고 |
| --- | --- | --- | --- |
| `nas_list` | 디렉터리를 나열하며 라벨과 검토 상태를 함께 보여 줍니다 | `list` | 리스 밖의 경로는 보이지 않습니다. |
| `nas_read` | 예산 읽기: 뷰, 범위, 예산 | `read` | [Budgeted Reads](https://agentnas.com/ko/concepts/budgeted-reads/) |
| `nas_search` | 검색(전문 검색, 선택적으로 벡터)으로 스니펫과 포인터를 반환 | `read` | 격리된 노트는 기본적으로 제외됩니다. |
| `nas_write` | 브랜치 안에 파일을 쓰며, 선택적으로 `intent`를 지정 | `write` | 대부분의 런타임은 마운트를 직접 쓰므로 필요하지 않습니다. |
| `nas_branch` | 브랜치를 만들고, 체크포인트를 찍고, 복원하고, 나열 | `write` | [Agent Branch](https://agentnas.com/ko/concepts/agent-branch/) |
| `nas_propose` | Agent PR 생성 | `propose` | 게이트가 작동할 수 있습니다. |
| `nas_lease` | 더 좁은 하위 리스 요청, 현재 리스와 예산 조회, 더 넓은 권한 요청(게이트 경유) | 없음 | [Capability Lease](https://agentnas.com/ko/concepts/capability-lease/) |
| `nas_remember` | 출처와 종류를 붙여 노트 쓰기 | `write` | [Agent Memory](https://agentnas.com/ko/concepts/agent-memory/) |
| `nas_recall` | 노트 불러오기: 예산 안에서, 출처와 검토 상태 포함 | `read` | [Agent Memory](https://agentnas.com/ko/concepts/agent-memory/) |

> **사람과 운영자 전용 동작.** `explain`, `gate approve/deny`, `forget`, `trash restore`, `label admin`, `lease revoke`, `policy edit`은 에이전트에게 **노출되지 않습니다**. 이 동작들은 보장 자체를 바꾸므로, 제약을 받는 쪽이 호출할 수 있어서는 안 됩니다. 에이전트는 일부(더 넓은 권한, 망각)를 **요청**할 수는 있지만 실행할 수는 없습니다.

## 마운트 의미론

- 마운트는 **브랜치 하나와 리스 하나**에 묶입니다. 리스가 만료되면 마운트는 읽기 전용이 되었다가 해제됩니다.
- 자동 커밋(디바운스, 예를 들어 5초 동안 조용하면 커밋). `fsync`는 커밋을 일으킵니다.
- 리스 밖의 경로는 **디렉터리 목록에 나타나지 않습니다.** 정보 유출을 줄이고 프롬프트 인젝션의 공격 표면을 줄여 줍니다.
- 샌드박스 친화적: 루트 권한이 필요 없고, FUSE와 NFS 중 하나를 쓰며 커널 모듈이 필요 없고, 읽기 전용 마운트도 가능합니다.

| 상황 | POSIX 오류 | 비고 |
| --- | --- | --- |
| 리스 밖의 경로 | `ENOENT` (보이지만 거부될 때는 `EACCES`) | 거부는 기록됩니다. |
| 쿼터나 예산 소진 | `EDQUOT` | 실행이 스스로 속도를 조절하게 해 줍니다. |
| 게이트 대기 중 | `EACCES`, 설명은 `/.nas/pending`에 | 에이전트가 끝없이 재시도하는 것을 막습니다. |
| 리스 만료 | `ESTALE`, 이후 읽기 전용 | 브랜치는 자체 TTL이 끝날 때까지 유지됩니다. |

## Git

- 실행 브랜치의 이름은 `<role>/<run_id>`이며, `main`은 보호되고 서버 측 `pre-receive` 훅이 직접 푸시를 거부합니다.
- `nas propose`가 Agent PR을 만듭니다.
- 커밋에는 `Run:`, `Lease:`, `Principal:` 같은 트레일러가 자동으로 붙습니다.

## S3

- 버킷은 한 트리의 브랜치 뷰에 대응하고, 오브젝트 버전 ID는 커밋입니다.
- S3에 없는 의미(예: 브랜치)는 버킷 접두사나 요청 헤더(`x-nas-branch`)로 표현합니다. 이것은 **성능이 낮아진 투영**입니다. 데이터 파이프라인은 읽고 쓸 수 있지만 완전한 브랜치 경험은 얻지 못합니다.
- 리스는 STS 방식의 임시 자격 증명으로 전달됩니다.

## A2A (선택)

- 들어오는 작업은 `inbox/`에 작업 파일로 놓이고, 결과물은 `outbox/`에 들어갑니다.
- Agent Card는 역할의 스킬과 필요한 리스를 선언합니다.
- **NAS는 A2A의 참여자가 아닙니다.** 참여자는 역할을 대신해 동작하는 런타임입니다. NAS는 작업과 결과물, 핸드오프 번들, 리스를 보관할 뿐입니다.

## HTTP API 규약

- **모든 엔드포인트는 `POST`를 쓰며, 매개변수는 JSON 본문에 둡니다.** 응답 필드는 항상 `snake_case`입니다.
- 경로에는 버전이 붙습니다: `/v1/...`.
- 멱등성: 쓰기 동작은 `idempotency_key`를 받습니다.
- 페이지네이션: `cursor`와 `limit`.
- 예산과 속도 제한은 응답 헤더(남은 바이트, 남은 요청 수)로 알려 주어 런타임이 스스로 속도를 조절할 수 있게 합니다.

예산 읽기 요청과 응답은 대략 다음과 같습니다.

*예산 읽기*

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

오류는 하나의 통일된 구조를 씁니다.

*오류 응답*

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

## 탐색

- 기계가 읽을 수 있는 진입점은 이 사이트와 같습니다. `/.well-known/ai-catalog.json`, MCP Server Card, `llms.txt`.
- `nas://` 증거 포인터를 해석하고 검증하는 엔드포인트.
- MCP `server/discover`.

---

표준 URL: https://agentnas.com/ko/interfaces/
최종 수정: 2026-11-11 · 명세 초안 v0.2 · CC BY 4.0