面向 AI Agent 的文件系统 - AGFS

1. AGFS

简介

AGFS 是一个通过 RESTful API 对外提供存储服务的项目。它支持多种存储后端，包括内存、文件、数据库、消息队列等。

由于不需要 POSIX 接口的支持，可以通过远程调用的方式存储数据，这在 AI Agent 中非常有用。

AI Agent 在执行一些工作流时，经常会产生一些中间结果。这些结果需要共享给其他的 Agent 或者用于下一次的 Agent 执行， AGFS 能很好的满足这个需求，特别是在 Sandbox 环境中，AGFS 是一个很合适的选择。

插件化文件系统

每个后端服务对应一个插件（MemFS、QueueFS、KVFS、S3FS、SQLFS 等），挂载到统一的目录树中

架构组成

agfs-server（Go）提供 HTTP API + 插件管理。

agfs-shell（Python）提供交互式 Shell。

agfs-fuse（Go）支持 Linux FUSE 挂载。

agfs-mcp 提供 MCP 协议接入。

操作映射

传统方式	AGFS 方式
`redis.set("key", "value")`	`echo "value" > /kvfs/keys/mykey`
`sqs.send_message(queue, msg)`	`echo "msg" > /queuefs/q/enqueue`
`s3.put_object(bucket, key, d)`	`cp file /s3fs/bucket/key`
`mysql.execute("SELECT ...")`	`echo "SELECT ..." > /sqlfs2/.../query`

2. AGFS 部署

1
2
mkdir -p agfs/data
chmod -R 777 agfs/data

准备配置文件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
cat > agfs/config.yaml <<'EOF'
server:
  address: ":8080"
  log_level: info

plugins:
  serverinfofs:
    enabled: true
    path: /serverinfo
    config:
      version: "1.0.0"

  memfs:
    enabled: true
    path: /memfs
    config:
      init_dirs:
        - /tmp

  queuefs:
    enabled: true
    path: /queuefs
    config: {}

  kvfs:
    enabled: true
    path: /kvfs
    config:
      initial_data:
        welcome: "Hello from AGFS!"

  heartbeatfs:
    enabled: true
    path: /heartbeatfs

  localfs:
    enabled: true
    path: /local
    config:
      local_dir: /data

  sqlfs:
    - name: local
      enabled: true
      path: /sqlfs
      config:
        backend: sqlite
        db_path: /data/sqlfs.db
        cache_enabled: true
        cache_max_size: 1000
        cache_ttl_seconds: 5

  s3fs:
    - name: s3
      enabled: false
      path: /s3fs
      config:
        region: cn-beijing
        bucket: YOUR_BUCKET
        access_key_id: "YOUR_ACCESS_KEY_ID"
        secret_access_key: "YOUR_SECRET_ACCESS_KEY"
        prefix: agfs/
        endpoint: "YOUR_ENDPOINT"
        disable_ssl: false

  proxyfs:
    - name: remote
      enabled: false
      path: /proxyfs/remote
      config:
        base_url: "http://other-agfs-host:8080/api/v1"
EOF

运行容器

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
nerdctl run -d \
  --name agfs-server \
  --restart always \
  -p 8080:8080 \
  --privileged \
  --device /dev/fuse \
  --cap-add SYS_ADMIN \
  -v $(pwd)/agfs/data:/data \
  -v $(pwd)/agfs/config.yaml:/config.yaml \
  registry.cn-beijing.aliyuncs.com/opshub/c4pt0r-agfs:latest

也可以使用 SKIP_FUSE_MOUNT=true 环境变量跳过容器内 FUSE 挂载（仅 HTTP API，无需上述特权）。

删除容器

1
nerdctl rm -f agfs-server

查看 fuse 挂载点

1
2
3
nerdctl exec -it agfs-server df -h | grep agfs

agfs                      4.0T      2.0T      2.0T  50% /mnt/agfs

查看健康状态

1
curl http://127.0.0.1:8080/api/v1/health

1
{"status":"healthy","version":"1.4.0","gitCommit":"unknown","buildTime":"unknown"}

3. AGFS 功能使用

3.1 Key-Value 存储

通过 KVFS 插件，可以创建和管理键值对。

写入

1
2
curl -X PUT "http://127.0.0.1:8080/api/v1/files?path=/kvfs/keys/hello" \
  -d "world"

1
2
3
4
5
6
7
{"message":"Written 5 bytes"}
``

- 读取

```bash
curl "http://127.0.0.1:8080/api/v1/files?path=/kvfs/keys/hello"

1
world

列出所有 Key

1
curl "http://127.0.0.1:8080/api/v1/directories?path=/kvfs/keys/"

1
{"files":[{"name":"hello","size":5,"mode":420,"modTime":"2026-03-25T08:23:51.098035422Z","isDir":false,"meta":{"Name":"kvfs","Type":"file","Content":null}}]}

删除

1
curl -X DELETE "http://127.0.0.1:8080/api/v1/files?path=/kvfs/keys/hello"

3.2 消息队列

通过 QueueFS 插件，可以创建和管理消息队列。

创建队列

1
curl -X POST "http://127.0.0.1:8080/api/v1/directories?path=/queuefs/tasks"

入队

1
2
curl -X PUT "http://127.0.0.1:8080/api/v1/files?path=/queuefs/tasks/enqueue" \
  -d "my-message"

1
{"message":"Written 10 bytes"}

查看队列长度

1
curl "http://127.0.0.1:8080/api/v1/files?path=/queuefs/tasks/size"

1
1

出队

1
curl "http://127.0.0.1:8080/api/v1/files?path=/queuefs/tasks/dequeue"

1
{"id":"019d2418-6424-7570-873a-311aad406c44","data":"my-message","timestamp":"2026-03-25T08:24:31.52435231Z"}

查看队头

查看不会取出队头消息。

1
curl "http://127.0.0.1:8080/api/v1/files?path=/queuefs/tasks/peek"

1
{"id":"019d2419-7045-7d64-b9e7-8ccb24c9b0cb","data":"my-message","timestamp":"2026-03-25T08:25:40.165873217Z"}

3.3 内存文件系统

通过 MemFS 插件，可以创建和管理内存文件系统。

1
curl -X POST "http://127.0.0.1:8080/api/v1/directories?path=/memfs/my-memfs"

1
{"message":"directory created"}

写入文件

1
2
curl -X PUT "http://127.0.0.1:8080/api/v1/files?path=/memfs/my-memfs/note.txt" \
  -d "Hello AGFS"

1
{"message":"Written 10 bytes"}

读取文件

1
curl "http://127.0.0.1:8080/api/v1/files?path=/memfs/my-memfs/note.txt"

1
Hello AGFS

1
curl "http://127.0.0.1:8080/api/v1/directories?path=/memfs/my-memfs"

1
{"files":[{"name":"note.txt","size":10,"mode":420,"modTime":"2026-03-25T08:27:21.323579029Z","isDir":false,"meta":{"Name":"memfs","Type":"file","Content":null}}]}

查看文件元信息

1
curl "http://127.0.0.1:8080/api/v1/stat?path=/memfs/my-memfs/note.txt"

1
{"name":"note.txt","size":10,"mode":420,"modTime":"2026-03-25T08:27:21.323579029Z","isDir":false,"meta":{"Name":"memfs","Type":"file","Content":null}}

3.4 Agent 心跳管理

通过 HeartbeatFS 插件，可以创建和管理 Agent 心跳。

1
curl -X POST "http://127.0.0.1:8080/api/v1/directories?path=/heartbeatfs/agent-1"

1
{"message":"directory created"}

发送心跳

1
2
curl -X PUT "http://127.0.0.1:8080/api/v1/files?path=/heartbeatfs/agent-1/keepalive" \
  -d "ping"

1
{"message":"Written 4 bytes"}

查看状态

1
curl "http://127.0.0.1:8080/api/v1/files?path=/heartbeatfs/agent-1/ctl"

1
2
3
4
last_heartbeat_ts: 2026-03-25T08:32:37Z
expire_ts: 2026-03-25T08:37:37Z
timeout: 300
status: alive

3.5 本地文件系统

通过 localfs 插件，可直接读写容器内映射的本地目录。

写入文件

1
2
curl -X PUT "http://127.0.0.1:8080/api/v1/files?path=/local/test.txt" \
  -d "persistent data"

1
{"message":"Written 15 bytes"}

读取文件

1
curl "http://127.0.0.1:8080/api/v1/files?path=/local/test.txt"

1
persistent data

直接 cat $(pwd)/agfs/data/test.txt 也能看到相同内容。

3.6 使用 agfs-shell

进入容器

1
nerdctl exec -it agfs-server /bin/sh

启动 Shell

1
agfs-shell

Shell 操作示例

1
2
3
4
5
6
7
8
9
agfs:/> ls /
dev/
heartbeatfs/
kvfs/
local/
memfs/
queuefs/
serverinfo/
sqlfs/

1
2
3
4
agfs:/> echo "task-1" > /queuefs/tasks/enqueue
agfs:/> echo "value" > /kvfs/keys/mykey
agfs:/> cat /kvfs/keys/mykey
value

4. 插件管理

AGFS 支持运行时动态挂载和卸载插件，无需重启服务。

查看已挂载插件

1
curl http://127.0.0.1:8080/api/v1/mounts

1
{"mounts":[{"path":"/dev","pluginName":"devfs"},{"path":"/heartbeatfs","pluginName":"heartbeatfs"},{"path":"/kvfs","pluginName":"kvfs"},{"path":"/local","pluginName":"localfs"},{"path":"/memfs","pluginName":"memfs"},{"path":"/queuefs","pluginName":"queuefs"},{"path":"/serverinfo","pluginName":"serverinfofs"},{"path":"/sqlfs","pluginName":"sqlfs"}]}

动态挂载插件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
curl -X POST http://127.0.0.1:8080/api/v1/mount \
  -H "Content-Type: application/json" \
  -d '{
    "fstype": "s3fs",
    "name": "s3",
    "path": "/s3fs",
    "config": {
      "region": "cn-beijing",
      "bucket": "YOUR_BUCKET",
      "access_key_id": "YOUR_ACCESS_KEY_ID",
      "secret_access_key": "YOUR_SECRET_ACCESS_KEY",
      "prefix": "agfs/",
      "endpoint": "YOUR_ENDPOINT",
      "disable_ssl": false
    }
  }'

1
{"message":"plugin mounted"}

写入文件

1
2
curl -X PUT "http://127.0.0.1:8080/api/v1/files?path=/s3fs/test.txt" \
  -d "Hello AGFS"

1
{"message":"Written 10 bytes"}

卸载插件

1
2
3
curl -X POST http://127.0.0.1:8080/api/v1/unmount \
  -H "Content-Type: application/json" \
  -d '{"path": "/s3fs"}'

1
{"message":"plugin unmounted"}