DeepAgents虚拟文件系统 / ai #72

lemooljiang(76)

Published in

HIVE CN 中文社区

Words

754

Reading

4 min

20m

Listen to this post

~5 min

虚拟文件系统 — Deep Agents 的 Context Engineering 核心。它提供了一整套文件操作工具，Agent 可以像人类一样按需读取、结构化存储、搜索定位。

Deep Agents 当前提供 7 个内置文件工具。下图展示了最初的六类核心读写与搜索能力，当前版本还加入了 delete

"虚拟文件系统"是一个抽象概念。具体的文件存到哪里，由后端（Backend）决定。

StateBackend（默认）：临时存储
默认就是 StateBackend，不需要显式指定。文件存在 LangGraph 的 Agent State 中。特点：

同一个对话线程内持久化（多轮对话不丢失）
对话结束后丢失（换一个 thread 就没了）
主 Agent 和子 Agent 共享文件
适合场景：大多数情况下的默认选择，Agent 的”草稿纸”。

FilesystemBackend：本地磁盘

from deepagents.backends import FilesystemBackend

agent = create_deep_agent(
    model=model,
    backend=FilesystemBackend(root_dir=".", virtual_mode=True)
)

文件直接读写本地文件系统。特点：

root_dir 指定 Agent 可访问的根目录；相对路径会被解析为绝对路径（Path(root_dir).resolve()），"." 即当前工作目录。
virtual_mode=True 启用路径沙箱（阻止 ..、~ 及越界的绝对路径），强烈建议开启。
若为默认的 virtual_mode=False，即使设了 root_dir 也不提供任何越界保护.。
文件修改是永久的、不可逆的
适合场景：本地开发 CLI（编程助手）、CI/CD 流水线。

LocalShellBackend：本地 Shell 执行

from deepagents.backends import LocalShellBackend

agent = create_deep_agent(
    model=model,
    backend=LocalShellBackend(root_dir=".", virtual_mode=True, env={"PATH": "/usr/bin:/bin"})
)

LocalShellBackend 是 FilesystemBackend 的扩展，在文件系统工具之外额外提供 execute 工具，可直接在宿主机运行 Shell 命令。特点：

命令通过 subprocess.run(shell=True) 执行，无任何沙箱隔离
支持 timeout（默认 120 秒）、max_output_bytes（默认 100,000）、env 等参数
root_dir 作为命令的工作目录，但命令可访问系统上任意路径
适合场景：本地开发环境的编程助手、你完全信任 Agent 行为的个人开发机。

StoreBackend：跨会话持久化

from langgraph.store.memory import InMemoryStore
from deepagents.backends import StoreBackend

agent = create_deep_agent(
    model=model,
    backend=StoreBackend(
        namespace=lambda rt: (rt.server_info.user.identity,),  # 按用户隔离数据
    ),
    store=InMemoryStore()  # 开发用；部署到 LangSmith 时可省略，平台自动提供
)

文件存在 LangGraph 的 Store 中。特点：

跨线程持久化——不同对话都能访问同一份文件
namespace 参数控制数据隔离：lambda rt: (rt.server_info.user.identity,) 按用户隔离，防止数据混用
开发用 InMemoryStore，部署到 LangSmith 时省略 store 参数（平台自动配置）
适合场景：长期记忆、跨会话的用户偏好、累积的知识库。

CompositeBackend：混合路由

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore

agent = create_deep_agent(
    model=model,
    backend=CompositeBackend(
        default=StateBackend(),            # 默认：临时存储
        routes={
            "/memories/": StoreBackend(
                namespace=lambda rt: (rt.server_info.user.identity,),
            ),
        }
    ),
    store=InMemoryStore()
)

Agent 写入 /workspace/plan.md → StateBackend（临时）
Agent 写入 /memories/preferences.txt → StoreBackend（持久化，按用户隔离）
ls、glob、grep 自动聚合所有后端的结果，路径前缀保留
这种设计让 Agent 既有快速的”草稿纸”（State），又有持久的”记忆库”（Store），通过路径前缀自然隔离。

沙箱后端：安全代码执行
当使用沙箱后端（Modal、Daytona、Runloop 等）时，除了文件系统工具外，Agent 还会获得一个额外的 execute 工具，可以在隔离环境中执行 Shell 命令

# 沙箱后端自动提供 execute 工具
agent = create_deep_agent(
    model=model,
    backend=sandbox  # 沙箱实例
)

cn-reader

miao

$ 1.441