AIエージェントのためのファイルシステム：1つ作って学んだこと
Claude Code のように、ノートPCやサーバー上で動く多くのエージェント型システムは、bash を通じてファイルをネイティブに扱います。しかし、ユーザーがファイルをアップロードしてそれを扱えるようにするエージェント型システムを構築すると、自分が動かしているサーバー上にファイルを保存できない、かつエージェントに bash ツールを渡せない、という独自の制限が発生します。
- どこからでもユーザーに公開されること — 悪意のある攻撃者が、サーバーをクラッシュさせたり他の何かを悪用したりできるコマンドを実行させられるため、必要なのはファイル操作だけにしたい
- たとえファイル操作だけ許可しても、ストレージ容量の制限があるので、すべてのユーザーのファイルをサーバーに保存できません。つまり S3 や Azure のようなリモートストレージに保存する必要がありますが、それをマウントすると grep のようなネイティブコマンドが遅くなります。最初に全文をダウンロードしないといけないためです。
- ストレージが無制限で、マウントの必要もなかったとしても、やはり隔離が必要です。つまり、エージェントが別のユーザーによってアップロードされたファイル、または同じユーザーでも別セッションでアップロードされたファイルにアクセスできないようにする必要があります。
これらの問題に対する他の解決策もありますが、それぞれトレードオフがあります：
- VM/サンドボックス基盤（E2B、Northflank） — 会話ごとに隔離された環境を立ち上げます。これでセキュリティと隔離の問題は解決します。ただし、コールドスタートの遅延、運用上のオーバーヘッド、そして規模が大きくなるほど効いてくるコストがあります。結局「間接的に」またサーバーを管理することになります。
- S3 マウント（mountpoint-s3、JuiceFS、s3fs） — リモートのオブジェクトストレージをローカルファイルシステムとしてマウントします。grep や類似のコマンドは動きますが、非効率です。各スキャンで、実質的にファイル全体をチャンク単位でダウンロードするような HTTP の範囲リクエストが順次発生するためです。エージェントのワークロードには遅すぎます。
- just-bash（Vercel Labs） — pluggable なファイルシステムバックエンドを備えた、bash の TypeScript による再実装です。私が欲しかったものに最も近いですが、TypeScript だけです。私のパイプラインは Python です。
- Localsandbox（CoPlane） — just-bash を包む Python ラッパーで、言語の問題も解決できたはずです。しかし、Deno ランタイムを介して Python から just-bash へ橋渡しするため、Celery 環境で入れたくないデプロイ依存が追加されてしまいます。
最近、法務向けのエージェント型 AI システムを構築しているときにこの問題に直面しました。ユーザーは、エージェントが扱うためにファイルをアップロードする必要がありました。必要だった解決策は、サーバーのように起動したり停止したりする必要のないデータベースのようなストレージであることに加えて、エージェントのツールとして公開できるネイティブなファイル操作をサポートし、さらにエージェントが自分のスコープされたワークスペースの外のものにはアクセスできないことでした。
そこで見つけたのが AgentFS です。これは AI エージェントのために特別に作られたファイルシステムで、Turso/SQLite をベースにしています。ユーザーとセッションごとにスコープされた隔離ストレージを提供し、ファイル操作はエージェントのツールとして直接配線できます。
統合オプションとしては、Python SDK、AgentFS + just-bash、AgentFS + FUSE の3つがありましたが、私は Python SDK を選びました。エージェントに実際のマウントを与える一方で、サーバーの他の部分を露出したままにする FUSE と違い、Python SDK は全面的にコントロールできます。エージェントができるのは、あなたが明示的にツールとして配線したことだけです。シェルエスケープは不可、任意コマンドは不可、環境変数のリークもありません。隔離は設計段階で組み込まれており、後付けではありません。
トレードオフは、ツール表面（tool surface）をあなたが責任を持つことです。SDK は基本（read、write、list）を同梱していますが、検索操作がありませんでした。grep も、find も、wc もありません。すべてをコンテキストに投げ込まずにファイルを辿る必要があるエージェントにとって、それらは任意ではありません。なので私はそれらを作り、SDK に直接統合してもらうための PR を出しました。
AgentFS は、ホスト型の本番利用では Turso DB に依存しています。ローカルでは、このパターンは既に機能します。ユーザーごとに SQLite のファイルを1つ用意し、それぞれを独立に（完全な読み書き権限で）オープンするだけです。しかし本番サーバーでは、何百もの別々のデータベースファイルを手作業で管理することはできません。必要なのは、接続を適切なユーザーのデータベースへルーティングできる単一のサーバープロセスです。
Turso Cloud はその一部を解決します。数千もの別々のデータベースを作成でき、さらに ATTACH を使ってそれらをまたいでクエリすることすら可能です。ただし、アタッチされたデータベースは現在読み取り専用です。1つのセッションで複数のユーザーデータベースから読み取ることはできますが、書き込むことはできません。ユーザーのスコープされたワークスペース内で、エージェントがファイルを作成・修正・削除する必要があるエージェント型システムでは、読み取り専用アクセスだけでは不十分です。
Turso は、完全な読み書きの ATTACH サポートがロードマップにあることを確認しています。AgentFS 側では、open() 呼び出しが connect() 関数を通過し、ローカルファイルの代わりに Turso 管理のデータベースを指すようにできます。つまり Turso が書き込みサポートを提供し次第、SDK 統合の道筋はそのまま明確になります。それまでは、完全な本番向けのマルチユーザー AgentFS はこの上流機能によりブロックされています。
