Appearance
文件系统与 Backends
长任务经常产生搜索结果、草稿、数据文件和验证日志。把所有内容塞进 messages 会快速消耗上下文， 因此 Deep Agents 把“文件工作区”作为核心能力，并通过 backend 决定路径背后真正连接什么存储。
文件工具与存储是两层
模型看到的是一组文件工具；应用配置的是实现这些工具的 backend。
| 公共工具 | 用途 | 设计注意 |
|---|---|---|
ls | 列出目录 | 限制根路径和返回数量 |
read_file | 分段读取文件 | 大文件按行或范围读取 |
write_file | 新建或覆盖文件 | 写前检查路径与大小 |
edit_file | 对现有内容做定向修改 | 明确匹配失败和多重匹配 |
glob | 按模式找路径 | 防止无界遍历 |
grep | 在文件中搜索文本 | 控制结果数量与二进制输入 |
不同语言、backend 与版本还可能提供删除、图片读取、二进制内容或 execute。教程不能假设所有 backend 都有完全相同的工具面；execute 只应在具备执行接口的 sandbox 或 shell backend 上出现。
前端类比
文件工具像统一的 Storage API，backend 则像内存对象、IndexedDB、服务端对象存储或远程工作区的 不同 adapter。相同的 read_file('/report.md') 可以由不同存储实现。
Deep Agents 原生语义：这些路径属于 Deep Agents 的虚拟文件命名空间。它们不天然等于宿主 绝对路径。路径能否持久化、是否跨 thread、是否允许执行，完全取决于 backend 和 LangGraph store/checkpointer 配置。
默认 StateBackend
不传 backend 时，两个 SDK 都使用 StateBackend，把文件存入当前 LangGraph thread 的 Agent state。
python
import os
from deepagents import create_deep_agent
agent = create_deep_agent(model=os.environ["DEEPAGENTS_MODEL"])
# 等价心智模型：backend 使用 StateBackendts
import { createDeepAgent } from 'deepagents'
const model = process.env.DEEPAGENTS_MODEL
if (!model) throw new Error('DEEPAGENTS_MODEL is required')
const agent = createDeepAgent({ model })
// 默认 backend 是 StateBackendStateBackend 适合原型、单个 thread 的草稿和中间结果。它不是跨用户长期记忆；如果没有持久 checkpointer，进程退出后也不能据此推断文件仍存在。
Backend 选择
| Backend | 数据位置 | 典型用途 | 关键风险 |
|---|---|---|---|
| StateBackend | LangGraph state | 当前 thread 中间文件 | 容量与生命周期依赖 state/checkpointer |
| StoreBackend | LangGraph Store | 跨 thread memory、共享资源 | namespace 与租户隔离 |
| FilesystemBackend | 受控宿主目录 | 本地开发、受信工作区 | 路径逃逸与宿主数据暴露 |
| CompositeBackend | 按路径委派其他 backend | 工作区与 memory 分层 | 路由顺序和前缀设计 |
| Sandbox backend | 隔离的远程或临时环境 | 代码执行、构建、测试 | 网络、凭据、生命周期和成本 |
| LocalShellBackend | 宿主文件与命令 | 可信本地调试 | 无隔离，不适合不可信输入 |
用 CompositeBackend 分层路由
下图把普通工作文件放入受控目录，把 /memories/ 路径交给 LangGraph Store：
Python 0.6.12 的构造形状如下。示例使用虚构本地工作目录，不应直接改为项目根目录：
python
import os
from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, FilesystemBackend, StoreBackend
from langgraph.store.memory import InMemoryStore
workspace = FilesystemBackend(root_dir="./workspace", virtual_mode=True)
memory = StoreBackend(
store=InMemoryStore(),
namespace=lambda _runtime: ("tutorial", "memory"),
)
backend = CompositeBackend(
default=workspace,
routes={"/memories/": memory},
)
agent = create_deep_agent(
model=os.environ["DEEPAGENTS_MODEL"],
backend=backend,
)生产环境不要使用固定共享 namespace。应从经过认证的 runtime context 中派生租户与用户标识， 并在进入 namespace 前完成校验。
路径设计原则
- 使用稳定前缀表达生命周期，例如
/workspace/、/artifacts/、/memories/。 - 默认拒绝
..、符号链接逃逸和不受控绝对路径。 - 把用户或租户边界放进 Store namespace，而不是只放进文件名。
- 限制单文件大小、总容量、glob/grep 命中数和保留时长。
- 大型工具结果写入 artifact，并在消息里返回路径与摘要。
- 对写操作记录调用者、thread、路径、内容摘要和结果。
Python 与 TypeScript 差异
- TypeScript
>=1.9.0的 V2 backend 支持带 MIME 类型的二进制内容；浏览器入口与 Node/server 入口不能混用 Node-only backend。 - Python 的
read_file可以根据 backend 处理图片内容，并在部分 backend 上提供删除能力。 - 两种语言的公共文本工具相近，但构造器、binary content 和生命周期接口不应机械互译。
Backend 不是安全策略的全部
即使路径被路由到安全存储，工具仍可能泄露数据到模型上下文或 trace。真正边界还包括模型可见的 路径、工具权限、sandbox 网络、凭据代理、审计与数据保留政策。