三个核心概念
Thread、User、Assistant 决定了信息如何共享和访问
Thread（线程）
一次单独的对话。消息历史和临时文件默认作用于线程范围内，不会跨线程保留。
作用域最小
User（用户）
与你的 Agent 交互的人。内存和文件可以是某个用户私有的，也可以在用户之间共享。身份认证来自你的认证层。
推荐默认按用户隔离
Assistant（助手）
一个配置好的 Agent 实例。内存和文件可以绑定到某个助手，也可以在所有助手之间共享。
多个助手时可按助手划分
记住这个三角关系：Thread 是单次对话的边界，User 是人的边界，Assistant 是 Agent 实例的边界。后面所有的内存划分、沙箱隔离、认证授权，都基于这三个概念展开。
多租户架构
当你的 Agent 服务多个用户时，需要处理三个核心问题
1. 验证身份
用户是谁？自定义认证（Clerk、Supabase 或匿名）建立身份。认证成功后，用户的身份信息可用于划分数据作用域。
2. 控制访问
用户能访问什么？授权处理器在认证后运行，可以添加所有者标签、返回资源过滤器、或返回 HTTP 403 拒绝未授权操作。
3. 管理凭证
Agent 代理用户执行操作时用什么凭证？OAuth 2.0 流程、沙箱认证代理、工作区密钥——三种方式按需选择。
// 授权处理器示例：为资源添加所有者标签
// 用户只能看到自己的资源，实现多租户隔离
const authHandler = async (ctx) => {
return {
filters: { owner: ctx.user.identity }, // 按用户身份过滤资源
// 返回 HTTP 403 可拒绝未授权操作
};
};
三层认证模型：终端用户认证（谁在用）、Agent 代理用户认证（Agent 代表谁操作）、团队 RBAC（谁能部署和管理）。三层各司其职，互不干扰。
沙箱生命周期
关键决策：每次对话新建沙箱，还是对话之间共享？
线程范围（最常见）
每次对话一个沙箱。同一线程内复用，新线程从干净状态开始。
适合：数据分析机器人，每次都从干净环境开始。
隔离性最好
助手范围
所有对话共享一个沙箱。文件、安装的包在对话间持久化。
适合：编程助手，跨对话维护克隆的仓库和依赖。
需注意磁盘增长
为什么使用异步 Graph 工厂？沙箱创建需要
thread_id 或 assistant_id 来查找或创建正确的沙箱。Graph 工厂不接收完整的 Runtime（没有 server_info 或 execution_info），而是接受 RunnableConfig 并从 config["configurable"] 读取 thread_id 和 assistant_id。工厂是异步的，因为沙箱创建是一个 I/O 密集型操作，且需要仅在调用时可用的每次运行信息。
// 线程范围沙箱 —— 每个对话独立沙箱，新线程从干净状态开始
import { Daytona } from "@daytonaio/sdk";
import { DaytonaSandbox } from "@langchain/daytona";
import { createDeepAgent } from "deepagents";
import type { LangGraphRunnableConfig } from "@langchain/langgraph";
const client = new Daytona();
// 异步 graph 工厂：每次运行时动态创建 Agent（因为需要 thread_id 来查找/创建沙箱）
export async function agent(config: LangGraphRunnableConfig) {
const threadId = config.configurable?.thread_id as string;
let sandbox;
try {
// 先尝试查找已有沙箱（同一线程内复用）
sandbox = await client.findOne({ labels: { thread_id: threadId } });
} catch {
// 没有找到则创建新沙箱，打上 thread_id 标签以便后续复用
sandbox = await client.create({
labels: { thread_id: threadId },
autoDeleteInterval: 3600, // TTL: 空闲 1 小时后自动清理
});
}
return createDeepAgent({
model: "google-genai:gemini-3.1-pro-preview",
backend: await DaytonaSandbox.connect(sandbox.id), // 将沙箱作为文件系统后端
});
}助手范围沙箱
所有对话共享一个沙箱。Graph 工厂从配置中读取助手 ID，因此同一助手上的每个线程都返回到相同的环境。文件、安装的包和克隆的仓库在对话之间持久化。
// 助手范围沙箱 —— 所有对话共享同一个沙箱，文件和依赖跨对话持久化
import { Daytona } from "@daytonaio/sdk";
import { DaytonaSandbox } from "@langchain/daytona";
import { createDeepAgent } from "deepagents";
import type { LangGraphRunnableConfig } from "@langchain/langgraph";
const client = new Daytona();
// 按 assistant_id 查找沙箱：同一助手的所有线程复用同一沙箱
export async function agent(config: LangGraphRunnableConfig) {
const assistantId = config.configurable?.assistant_id as string;
let sandbox;
try {
sandbox = await client.findOne({ labels: { assistant_id: assistantId } });
} catch {
// 首次使用时创建，后续对话直接复用
sandbox = await client.create({ labels: { assistant_id: assistantId } });
}
return createDeepAgent({
model: "google-genai:gemini-3.1-pro-preview",
backend: await DaytonaSandbox.connect(sandbox.id),
});
}
助手范围注意：沙箱会随时间积累文件和状态。请配置 TTL、使用快照定期重置，或实现清理逻辑，防止磁盘和内存无限增长。
文件同步中间件
使用 beforeAgent / afterAgent 钩子在沙箱边界之间移动文件
import { createMiddleware } from "langchain";
import { createDeepAgent, CompositeBackend, StoreBackend } from "deepagents";
import { DaytonaSandbox } from "@langchain/daytona";
function safeFilename(key: string): string {
const name = key.split("/").pop()!;
// 防止路径遍历攻击：拒绝包含 .. 或通配符的文件名
if (name.includes("..") || /[*?]/.test(name)) {
throw new Error(`Invalid key: ${key}`);
}
return name;
}
// 创建文件同步中间件：在 Store（持久存储）和沙箱之间双向同步文件
const createSandboxSyncMiddleware = (backend: CompositeBackend) => {
return createMiddleware({
name: "SandboxSyncMiddleware",
beforeAgent: async (state, runtime) => {
// Agent 循环开始前：从 Store 读取技能和内存 → 上传到沙箱
const userId = runtime.serverInfo.user.identity;
const store = runtime.store;
const encoder = new TextEncoder();
const files: [string, Uint8Array][] = [];
// 收集该用户的所有技能文件
for (const item of await store.search(["skills", userId])) {
const name = safeFilename(item.key);
files.push([`/skills/${name}`, encoder.encode(item.value.content)]);
}
// 收集该用户的所有内存文件
for (const item of await store.search(["memories", userId])) {
const name = safeFilename(item.key);
files.push([`/memories/${name}`, encoder.encode(item.value.content)]);
}
if (files.length > 0) {
await backend.uploadFiles(files); // 批量上传到沙箱
}
},
afterAgent: async (state, runtime) => {
// Agent 循环结束后：从沙箱下载更新的内存 → 同步回 Store
const userId = runtime.serverInfo.user.identity;
const store = runtime.store;
const items = await store.search(["memories", userId]);
const results = await backend.downloadFiles(
items.map((item) => `/memories/${item.key}`), // 下载沙箱中的内存文件
);
const decoder = new TextDecoder();
for (const result of results) {
if (result.content) {
await store.put(
["memories", userId], // 命名空间：按用户隔离
result.path.split("/").pop()!, // 文件名
{ content: decoder.decode(result.content) }, // 更新后的内容
);
}
}
},
});
};
// 后端配置：默认路径走沙箱，/skills/ 和 /memories/ 走持久化 Store
const backend = new CompositeBackend(
await DaytonaSandbox.connect(sandbox.id), // 默认：沙箱后端
{
"/skills/": new StoreBackend({ // /skills/ 路径 → 持久化存储
namespace: (rt) => ["skills", rt.serverInfo.user.identity],
}),
"/memories/": new StoreBackend({ // /memories/ 路径 → 持久化存储
namespace: (rt) => ["memories", rt.serverInfo.user.identity],
}),
},
);
export const agent = createDeepAgent({
backend,
middleware: [createSandboxSyncMiddleware(backend)],
});
工作原理：
beforeAgent 钩子在每次 Agent 循环开始前，将 Store 中的技能脚本和内存文件上传到沙箱。afterAgent 钩子在循环结束后，将沙箱中更新的内存下载并同步回 Store。这样 Agent 在沙箱内就能访问到最新的持久化数据。
防护机制
生产环境的 Agent 自主运行，需要两层保护机制
权限（声明式）
控制 Agent 可以读取或写入哪些文件和目录。将 Agent 隔离到工作目录、保护敏感文件、强制只读内存。
声明式规则
中间件（钩子式）
包装模型和工具调用的钩子。用于速率限制、错误处理、数据隐私。在每次调用前后执行策略。
编程式控制
// 中间件生命周期钩子
// beforeModel → 模型调用前
// wrapModelCall → 包装模型调用
// wrapToolCall → 包装工具调用
// afterModel → 模型调用后
// beforeAgent → Agent 循环开始前
// afterAgent → Agent 循环结束后
注意：自定义中间件目前不能通过
langgraph deploy 配置。要使用中间件，请通过 LangSmith Deployment 直接部署你的 Agent 模块。
