# インターフェース

> Agent NAS は、データ面にはファイルを、制御面にはツールを使います。バイトはマウント、Git、S3 を流れ、認可、承認、記憶、検索、説明は MCP、HTTP、CLI を通ります。どのインターフェースも同じデータの投影であり、意味の違いは、なかったことにせず、明示的なエラーで表します。

## 指針

1. **データ面にはファイル、制御面にはツール。** バイトはマウント、Git、S3 を流れ、認可、承認、記憶、検索、説明は MCP、HTTP、CLI を通ります。
2. **ゲートウェイは状態を持ちません。** 認可は Trust 層のただ 1 つの地点でだけ行われます。
3. **どのインターフェースも投影です。** 意味の違いは、明示的なエラーのマッピングで表します（たとえば「ゲート待ち」は、説明ファイルを添えた `EACCES` に対応します）。S3 にブランチがあるようには装いません。
4. **ツールの面は狭く。** エージェントに向けた MCP ツールは 10 個以内です。人間や運用者向けの操作は、別のオペレーター用インターフェースに置きます。
5. **アダプターがプロトコルの変化を隔離します。** MCP や A2A のバージョンの変化が及ぶのは、アダプターだけです。

## インターフェースの一覧

| インターフェース | 面 | 対象 | マッピング | レベル |
| --- | --- | --- | --- | --- |
| マウント（FUSE、NFS、SMB） | データ | エージェント、人間、あらゆるプログラム | ブランチのビュー。エラーのマッピングは下記 | L0 |
| Git（SSH、HTTPS） | データ | エージェント、人間、CI | 実行のブランチは Git のブランチ。Agent PR はマージリクエスト | L0 |
| S3 互換 | データ | データパイプライン、バッチ処理 | バケットは 1 つのツリーのブランチビューに対応。バージョン ID はコミット | L0（任意） |
| WebDAV | データ | 人間（Finder、エクスプローラー） | 読み取り専用のアクティビティビュー | L0（任意） |
| CLI `nas` | 制御 | 人間、スクリプト | HTTP API と 1 対 1 | L0 |
| HTTP API | 制御 | オーケストレーター、コントロールルーム | すべて `POST` と JSON。フィールドは `snake_case` | L1 |
| MCP | 制御 | エージェント | 9 つのツール（下記） | L1、L2 |
| A2A | 制御 | 他のエージェント | タスクは `inbox/` と `outbox/` に対応 | L4（任意） |

## MCP のツール面

エージェントに向けたツールは 9 つだけです。

| ツール | 何をするか | 必要なリースの操作 | 備考 |
| --- | --- | --- | --- |
| `nas_list` | ディレクトリを一覧する。ラベルとレビュー状態つき | `list` | リースの外のパスは見えません。 |
| `nas_read` | 予算つきの読み取り：ビュー、範囲、予算 | `read` | [Budgeted Reads](https://agentnas.com/ja/concepts/budgeted-reads/) |
| `nas_search` | 検索（全文、任意でベクトル）。スニペットとポインタを返す | `read` | 隔離エリアは既定で除外されます。 |
| `nas_write` | ブランチの中のファイルに書く。任意で `intent` を添える | `write` | ほとんどのランタイムはマウントを直接使うので、不要です。 |
| `nas_branch` | ブランチの作成、チェックポイント、復元、一覧 | `write` | [Agent Branch](https://agentnas.com/ja/concepts/agent-branch/) |
| `nas_propose` | Agent PR を作る | `propose` | ゲートが起動することがあります。 |
| `nas_lease` | より狭い子リースを申請する。現在のリースと予算を照会する。より広い権限を要求する（ゲート経由） | なし | [Capability Lease](https://agentnas.com/ja/concepts/capability-lease/) |
| `nas_remember` | ノートを書く。出典と種類つき | `write` | [Agent Memory](https://agentnas.com/ja/concepts/agent-memory/) |
| `nas_recall` | ノートを想起する：予算つきで、出典とレビュー状態つき | `read` | [Agent Memory](https://agentnas.com/ja/concepts/agent-memory/) |

> **人間と運用者だけの操作.** `explain`、`gate approve/deny`、`forget`、`trash restore`、`label admin`、`lease revoke`、`policy edit` は、エージェントには **公開されません**。これらの操作は保証そのものを変えるもので、制約を受ける側が呼べるべきではありません。エージェントは、一部（権限の拡大、忘却）を **要求** することはできますが、実行はできません。

## マウントの意味

- マウントは **1 つのブランチと 1 つのリース** に結びつきます。リースの期限が切れると、マウントは読み取り専用になり、その後アンマウントされます。
- 自動コミット（デバウンス。たとえば静かな状態が 5 秒続いたあと）。`fsync` がコミットを起動します。
- リースの外のパスは、**ディレクトリの一覧に現れません**。これは情報の漏えいを減らし、プロンプトインジェクションの攻撃面も小さくします。
- サンドボックスにやさしい：root は不要。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

- バケットは 1 つのツリーのブランチビューに対応し、オブジェクトのバージョン 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/ja/interfaces/
更新日: 2026-11-11 · 仕様ドラフト v0.2 · CC BY 4.0