Deep Agents Memory

短期（StateBackend）：在单个线程（thread）内持久化，线程结束时丢失 长期（StoreBackend）：跨线程和跨会话持久化 混合（CompositeBackend）：将不同路径路由到不同的后端

FilesystemMiddleware 提供了以下工具：ls、read_file、write_file、edit_file、glob、grep

from deepagents import create_deep_agent

agent = create_deep_agent()  # 默认：StateBackend
result = agent.invoke({
    "messages": [{"role": "user", "content": "Write notes to /draft.txt"}]
}, config={"configurable": {"thread_id": "thread-1"}})
# 线程结束时 /draft.txt 将丢失

import { createDeepAgent } from "deepagents";

const agent = await createDeepAgent();  // 默认：StateBackend
const result = await agent.invoke({
  messages: [{ role: "user", content: "Write notes to /draft.txt" }]
}, { configurable: { thread_id: "thread-1" } });
// 线程结束时 /draft.txt 将丢失

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

store = InMemoryStore()

composite_backend = lambda rt: CompositeBackend(
    default=StateBackend(rt),
    routes={"/memories/": StoreBackend(rt)}
)

agent = create_deep_agent(backend=composite_backend, store=store)

# /draft.txt -> 临时 (StateBackend)
# /memories/user-prefs.txt -> 持久化 (StoreBackend)

import { createDeepAgent, CompositeBackend, StateBackend, StoreBackend } from "deepagents";
import { InMemoryStore } from "@langchain/langgraph";

const store = new InMemoryStore();

const agent = await createDeepAgent({
  backend: (config) => new CompositeBackend(
    new StateBackend(config),
    { "/memories/": new StoreBackend(config) }
  ),
  store
});

// /draft.txt -> 临时 (StateBackend)
// /memories/user-prefs.txt -> 持久化 (StoreBackend)

# 使用前例中的 CompositeBackend
config1 = {"configurable": {"thread_id": "thread-1"}}
agent.invoke({"messages": [{"role": "user", "content": "Save to /memories/style.txt"}]}, config=config1)

config2 = {"configurable": {"thread_id": "thread-2"}}
agent.invoke({"messages": [{"role": "user", "content": "Read /memories/style.txt"}]}, config=config2)
# 线程 2 可以读取线程 1 保存的文件

// 使用前例中的 CompositeBackend
const config1 = { configurable: { thread_id: "thread-1" } };
await agent.invoke({ messages: [{ role: "user", content: "Save to /memories/style.txt" }] }, config1);

const config2 = { configurable: { thread_id: "thread-2" } };
await agent.invoke({ messages: [{ role: "user", content: "Read /memories/style.txt" }] }, config2);
// 线程 2 可以读取线程 1 保存的文件

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend
from langgraph.checkpoint.memory import MemorySaver

agent = create_deep_agent(
    backend=FilesystemBackend(root_dir=".", virtual_mode=True),  # 限制访问路径
    interrupt_on={"write_file": True, "edit_file": True},
    checkpointer=MemorySaver()
)

# Agent 可以读写磁盘上的实际文件

import { createDeepAgent, FilesystemBackend } from "deepagents";
import { MemorySaver } from "@langchain/langgraph";

const agent = await createDeepAgent({
  backend: new FilesystemBackend({ rootDir: ".", virtualMode: true }),
  interruptOn: { write_file: true, edit_file: true },
  checkpointer: new MemorySaver()
});

安全性：切勿在 Web 服务器中使用 FilesystemBackend——请改用 StateBackend 或沙箱（sandbox）。

from langchain.tools import tool, ToolRuntime
from langchain.agents import create_agent
from langgraph.store.memory import InMemoryStore

@tool
def get_user_preference(key: str, runtime: ToolRuntime) -> str:
    """从长期存储中获取用户偏好设置。"""
    store = runtime.store
    result = store.get(("user_prefs",), key)
    return str(result.value) if result else "Not found"

@tool
def save_user_preference(key: str, value: str, runtime: ToolRuntime) -> str:
    """将用户偏好设置保存到长期存储中。"""
    store = runtime.store
    store.put(("user_prefs",), key, {"value": value})
    return f"Saved {key}={value}"

store = InMemoryStore()

agent = create_agent(
    model="gpt-4.1",
    tools=[get_user_preference, save_user_preference],
    store=store
)

• 后端类型与配置
• CompositeBackend 的路由规则
• FilesystemBackend 的根目录
• 文件操作的人机协同（Human-in-the-loop）

Agent 不能配置的内容

• 工具名称（ls、read_file、write_file、edit_file、glob、grep）
• 访问 virtual_mode 限制之外的文件
• 在没有正确配置后端的情况下进行跨线程文件访问

# 错误
agent = create_deep_agent(backend=lambda rt: StoreBackend(rt))

# 正确
agent = create_deep_agent(backend=lambda rt: StoreBackend(rt), store=InMemoryStore())

// 错误
const agent = await createDeepAgent({ backend: (c) => new StoreBackend(c) });

// 正确
const agent = await createDeepAgent({ backend: (c) => new StoreBackend(c), store: new InMemoryStore() });

# 错误：thread-2 无法读取 thread-1 的文件
agent.invoke({"messages": [...]}, config={"configurable": {"thread_id": "thread-1"}})  # 写入
agent.invoke({"messages": [...]}, config={"configurable": {"thread_id": "thread-2"}})  # 文件未找到！

// 错误：thread-2 无法读取 thread-1 的文件
await agent.invoke({ messages: [...] }, { configurable: { thread_id: "thread-1" } });  // 写入
await agent.invoke({ messages: [...] }, { configurable: { thread_id: "thread-2" } });  // 文件未找到！

# 当 routes={"/memories/": StoreBackend(rt)} 时：
agent.invoke(...)  # /prefs.txt -> 临时（未匹配）
agent.invoke(...)  # /memories/prefs.txt -> 持久化（匹配路由）

// 当 routes: { "/memories/": StoreBackend } 时：
await agent.invoke(...);  // /prefs.txt -> 临时（未匹配）
await agent.invoke(...);  // /memories/prefs.txt -> 持久化（匹配路由）

# 错误                               # 正确
store = InMemoryStore()              store = PostgresStore(connection_string="postgresql://...")

// 错误                                     // 正确
const store = new InMemoryStore();          const store = new PostgresStore({ connectionString: "..." });

backend = FilesystemBackend(root_dir="/project", virtual_mode=True)  # 安全

routes = {"/mem/": StoreBackend(rt), "/mem/temp/": StateBackend(rt)}
# /mem/file.txt -> StoreBackend, /mem/temp/file.txt -> StateBackend（匹配更长前缀）