File System 中间件完全指南：四种后端让你的 Agent 学会“读写文件”
在构建复杂 Agent 时，上下文（Context）管理 是最关键的问题之一。当工具调用结果非常庞大时——例如网络搜索或 RAG 返回的大量信息——上下文窗口会被迅速填满，导致 Agent 无法持续运行。
File System 中间件 正是为了解决这一问题而设计的：它把文件系统作为 Agent 的外部记忆，在需要时写入文件、在需要时再读取，从而支持 Agent 的连续长期运行。
本文将系统梳理 File System 中间件的四种后端，帮助你根据数据生命周期选择合适的存储方式。
一、整体结构
File System 中间件的整体结构可以概括为：
二、FilesystemBackend：本地真实文件
FilesystemBackend 把 Agent 的文件直接映射到本地磁盘的真实文件。通过 root_dir 指定根目录，并通过 virtual_mode 以“沙箱”形式锁定访问范围。
典型配置：
from deepagents.backends import FilesystemBackend
backend = FilesystemBackend(
root_dir="./agent_files",
virtual_mode=True
)
适用场景：
- 需要长期保存在本地的数据
- 需要明确限定文件访问范围
- 需要真正操作本地磁盘文件
三、StateBackend：单次调用的临时草稿
StateBackend 将文件存储在 Agent 的运行状态中，生命周期与单次调用绑定，任务结束后通常不再保留，因此非常适合“草稿纸”式的中间结果。
典型配置：
backend=lambda runtime: StateBackend(runtime)
适用场景：
- 任务草稿
- 中间结果
- 单次调用内的临时数据
- 一次性、不需要长期保留的小型文件
四、StoreBackend：跨线程的长期记忆
StoreBackend 通过外部 Store 对象存储文件，可实现跨线程、跨进程、永久存活的长期记忆。一个文件写入后，可以在多个 Agent 实例中复用。
典型配置：
from langgraph.store.memory import InMemoryStore
from deepagents.backends import StoreBackend
store = InMemoryStore()
agent = create_agent(
model=model,
store=store,
middleware=[
FilesystemMiddleware(
backend=lambda runtime: StoreBackend(runtime)
)
]
)
适用场景：
- Agent 长期记忆
- 跨线程、跨会话共享数据
- 多 Agent 实例协同工作
- 需要长期保留的笔记、配置或用户偏好
五、CompositeBackend：多后端的“热插拔”
当任务同时涉及临时数据与长期记忆时，可以使用 CompositeBackend 把多个后端组合起来。它支持 default 默认后端和 routes 路径路由，可以根据文件路径灵活选择存储位置。
典型配置：
from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore
composite_backend = lambda runtime: CompositeBackend(
default=StateBackend(runtime),
routes={
".": StoreBackend(runtime),
}
)
agent = create_deep_agent(
backend=composite_backend,
store=InMemoryStore()
)
适用场景：
- 长期数据与临时数据混用
- 多种信息源协作
- 在同一 Agent 中混合使用 State 和 Store
- 复杂任务的统一记忆管理
六、四种后端对比
| 对比项 | FilesystemBackend | StateBackend | StoreBackend | CompositeBackend |
|---|---|---|---|---|
| 存储位置 | 本地磁盘 | 运行状态 | Store 对象 | 多种后端组合 |
| 是否真实文件 | 是 | 否 | 否 | 视配置而定 |
| 生命周期 | 长期 | 临时 | 长期 | 灵活 |
| 跨线程共享 | 是 | 否 | 是 | 部分支持 |
| 路径路由 | 不支持 | 不支持 | 不支持 | 支持 |
| 适合场景 | 本地文件管理 | 草稿、临时结果 | 长期记忆、共享数据 | 多类型文件混合管理 |
| 复杂度 | 中 | 低 | 中 | 较高 |
七、如何选择后端？
简单选择策略：
- 只需要临时草稿：
StateBackend - 需要本地真实文件：
FilesystemBackend - 需要长期记忆或跨线程共享：
StoreBackend - 需要混合多种存储：
CompositeBackend
八、总结
File System 中间件为 Agent 提供了一种外部记忆机制，可以显著降低上下文窗口的压力。四种后端各有侧重：
FilesystemBackend：真实文件，本地管理。StateBackend：临时草稿，自动清理。StoreBackend：长期记忆，跨线程共享。CompositeBackend：灵活组合，按需路由。
在实际开发中，应根据数据的生命周期和共享需求选择合适的后端。对于密码、Token 等敏感数据，应避免明文写入文件，必要时使用加密或环境变量管理。
核心原则：先限制 Agent 的文件访问范围，再赋予文件读写权限。