基于 LangChain 1.6、LangGraph 1.7 与 DeepAgents 1.16 的 JavaScript / Node.js 实战
写在前面:为什么"会写 Agent"和"能交付 Agent"是两回事
如果用一个聊天模型加几个工具,做一个"查天气""查时间"的 Demo,很多框架都能在十几行代码里完成。
但复杂 Agent 很快就会遇到另一组问题:
- 模型该在什么时候停下来?
- 工具调用失败以后,要不要重试?
- 多轮工具调用产生的消息怎样正确拼回上下文?
- 对话太长、工具返回内容太大,上下文窗口装不下怎么办?
- 任务需要先规划,再分步骤执行,执行状态放在哪里?
- 哪些文件可以读、哪些文件只能写、哪些操作必须拒绝?
- 主 Agent 如何把独立任务交给子 Agent,并避免污染主上下文?
- 线上如何观测模型调用次数、工具耗时、失败原因和中断恢复?
这些问题如果全部从零实现,会消耗大量时间在状态管理、循环路由、持久化、上下文压缩和权限边界上。
LangChain、LangGraph 和 DeepAgents 的关系,可以先用下面这张图建立直觉:
text
业务 Agent
│
▼
DeepAgents Harness
规划 / 文件工作区 / 子 Agent / 摘要压缩 / 记忆 / 权限
│
▼
LangChain Agent 抽象
createAgent / messages / model / tools / middleware
│
▼
LangGraph 运行时
状态机 / 条件路由 / 循环 / Checkpointer / Store / 流式执行
这不是严格意义上的四层继承关系,而是按"职责"拆开的认知模型:
- LangChain 提供 AI 应用积木:模型、消息、工具、结构化输出、
createAgent和 Middleware。 - LangGraph 提供有状态工作流运行时:状态通道、节点、边、条件路由、循环、持久化和人工中断。
- DeepAgents 在 LangChain Agent 和 LangGraph 之上提供一套"带电池"的 Agent Harness,把文件系统、子 Agent、摘要压缩等复杂能力预先封装好。
- 业务 Agent 只需要组合领域工具、业务提示词、权限策略和验收逻辑。
这篇文章不会只停留在概念解释上。我们会从最简单的 createAgent 开始,一步步加入 Middleware、状态统计、上下文注入、请求拦截、工具包装,再进入 DeepAgents 的虚拟文件系统和子 Agent,最后讨论生产落地时需要补上的边界。
文中的示例使用 Node.js ESM,可以直接保存成 .mjs 文件运行。
一、先搭好最小运行环境
1.1 安装依赖
本文示例对应的核心依赖如下:
json
{
"type": "module",
"dependencies": {
"@langchain/langgraph": "^1.7.4",
"@langchain/openai": "^1.8.4",
"deepagents": "^1.16.5",
"dotenv": "^18.0.10",
"langchain": "^1.6.6",
"zod": "^4.6.7"
}
}
安装命令:
bash
pnpm add langchain @langchain/langgraph @langchain/openai deepagents dotenv zod
DeepAgents 使用 LangChain 运行时包作为 peer dependency,因此应用侧应尽量让这些包只保留一份版本,避免因重复安装产生 instanceof、消息类型或 Command 类型不一致的问题。
1.2 配置模型
本地 .env 中准备:
dotenv
MODEL_NAME=your-model-name
OPENAI_API_KEY=your-api-key
OPENAI_BASE_URL=https://your-compatible-endpoint/v1
一个可复用的模型初始化代码如下:
js
import "dotenv/config";
import { ChatOpenAI } from "@langchain/openai";
export const model = new ChatOpenAI({
model: process.env.MODEL_NAME,
apiKey: process.env.OPENAI_API_KEY,
configuration: {
baseURL: process.env.OPENAI_BASE_URL,
},
temperature: 0,
});
如果你的服务兼容 OpenAI Chat Completions 协议,通常只需要替换 baseURL、模型名称和密钥。
但要注意:只要 Agent 需要工具调用,模型本身就必须正确支持 tool calling。模型能聊天,不代表它能稳定地产生符合格式的工具调用。
二、createAgent:把最小 Agent 循环封装起来
2.1 一个真正能调用工具的 Agent
先定义时间工具:
js
import { z } from "zod";
import { createAgent, tool, HumanMessage } from "langchain";
import { model } from "./model.mjs";
const getCurrentTime = tool(
() => new Date().toISOString(),
{
name: "get_current_time",
description: "返回当前 UTC 时间的 ISO 8601 字符串",
schema: z.object({}),
}
);
const agent = createAgent({
model,
tools: [getCurrentTime],
systemPrompt: "你是一个严谨的助手。需要实时信息时,优先调用工具。",
});
const result = await agent.invoke({
messages: [new HumanMessage("现在几点?请返回 UTC 时间。")],
});
console.log(result.messages.at(-1)?.content);
这段代码里最重要的不是 invoke,而是 createAgent 背后帮你完成的事情:
- 接收初始的
messages; - 把
systemPrompt和工具定义交给模型; - 调用模型;
- 检查模型返回的
AIMessage是否包含tool_calls; - 如果有工具调用,执行对应工具并生成
ToolMessage; - 把工具结果重新放回消息历史,再次调用模型;
- 当模型不再请求工具时结束。
可以用伪代码表示这个循环:
text
messages = 用户输入
while true:
response = model(messages, tools, system_prompt)
messages += response
if response.tool_calls is empty:
break
for tool_call in response.tool_calls:
tool_message = execute(tool_call)
messages += tool_message
return messages
真实实现还要处理并行工具、异常、路由、限制和持久化,但核心循环就是如此。
2.2 createAgent 的几个核心参数
| 参数 | 作用 | 常见误区 |
|---|---|---|
model |
聊天模型或模型标识 | 工具型 Agent 必须使用支持 tool calling 的模型 |
tools |
顶层工具列表 | 工具名称不能重复,参数 schema 要描述清楚 |
systemPrompt |
静态系统提示词 | 动态上下文更适合放进 Middleware |
middleware |
生命周期扩展 | 不是"工具列表"的同义词,它可以改请求、改结果、加状态和路由 |
stateSchema |
自定义持久化状态 | 状态能跨步骤、跨调用保留,但需要按业务设计 |
contextSchema |
单次运行上下文 | 上下文是只读的,不会天然持久化 |
responseFormat |
结构化输出 | 适合最终结果需要被程序消费的场景 |
checkpointer |
运行检查点 | 人工中断、恢复、多轮会话时非常重要 |
store |
跨线程长期存储 | 与一次对话内的状态不是一回事 |
理解 createAgent 最有效的方法,是先把它看成一个"可扩展的 ReAct 循环",而不是一个黑盒。
外层开发者只需要提供模型、工具和提示词;当需要加日志、权限、重试、缓存、路由或上下文压缩时,就通过 Middleware 插入循环。
三、Middleware 到底是什么
3.1 用"洋葱模型"理解
Middleware 可以理解成插入 Agent 生命周期中的拦截器:
text
用户请求
│
├─ beforeAgent
│
├─ 模型调用循环
│ ├─ beforeModel
│ ├─ wrapModelCall 前处理
│ ├─ 真正调用模型
│ ├─ wrapModelCall 后处理
│ └─ afterModel
│
├─ 如果有 tool_calls
│ └─ wrapToolCall 前处理
│ ├─ 真正执行工具
│ └─ wrapToolCall 后处理
│
└─ afterAgent
当多个 wrapModelCall 或 wrapToolCall 同时存在时,它们的行为类似"洋葱模型":外层先进入,内层后进入;返回时顺序反过来。
因此,Middleware 的顺序本身也是业务逻辑的一部分。尤其是在多个中间件都修改消息、系统提示词或提前结束流程时,应当固定顺序并写测试。
3.2 生命周期 Hook 速查
| Hook | 调用时机 | 典型用途 |
|---|---|---|
beforeAgent |
每次 Agent 运行开始,一次 | 初始化、鉴权、注入初始状态 |
beforeModel |
每次模型调用前 | 消息校验、输入拦截、上下文整理 |
wrapModelCall |
包住每次模型调用 | 改 prompt、切模型、改工具、缓存、重试 |
afterModel |
模型返回后、工具执行前 | 校验输出、统计调用、修正工具参数 |
wrapToolCall |
包住每次工具执行 | 权限检查、参数清洗、结果包装、错误恢复 |
afterAgent |
每次 Agent 运行结束,一次 | 汇总指标、保存结果、清理资源 |
几个常见认识需要纠正:
beforeModel会在每一轮模型调用前执行,不是整个 Agent 只执行一次。afterModel发生在模型返回后,但工具尚未执行。wrapToolCall不是"换一个工具",而是拦截工具调用请求,并决定是否调用原始handler。beforeAgent和afterAgent才是每次invoke粒度的开始与结束。
3.3 stateSchema 和 contextSchema 的区别
Middleware 可以扩展状态,也可以声明只读上下文:
js
import { z } from "zod";
import { createMiddleware } from "langchain";
const metricsMiddleware = createMiddleware({
name: "MetricsMiddleware",
stateSchema: z.object({
modelCallCount: z.number().default(0),
}),
contextSchema: z.object({
tenantId: z.string(),
userExpertise: z.enum(["beginner", "expert"]).default("beginner"),
}),
});
两者的区别是:
stateSchema是 Agent 状态的一部分,可以被 Hook 修改,会随 LangGraph 状态一起流转;配置 Checkpointer 后,还能按线程持久化。contextSchema描述本次运行的外部上下文,是只读的,不会自动成为跨轮持久化状态。
简单说:
text
需要被 Agent 写入、累计、恢复 → stateSchema
由宿主应用传入且只读 → contextSchema
例如"本轮模型调用了几次"适合放状态;"当前租户、当前用户权限、用户偏好"更适合放上下文。
四、实战一:用 Middleware 做可观测性
先从最常见的诉求开始:记录 Agent 开始、每轮模型调用、模型返回内容和最终调用次数。
js
import { z } from "zod";
import {
createAgent,
createMiddleware,
HumanMessage,
} from "langchain";
import { model } from "./model.mjs";
const loggingMiddleware = createMiddleware({
name: "LoggingMiddleware",
stateSchema: z.object({
modelCallCount: z.number().default(0),
}),
beforeAgent: (state) => {
console.log("[Logging] Agent 开始,初始消息数:", state.messages.length);
},
beforeModel: (state) => {
console.log(
`[Logging] 即将调用模型,消息数:${state.messages.length},` +
`历史模型调用:${state.modelCallCount} 次`
);
},
afterModel: (state) => {
const lastMessage = state.messages.at(-1);
const preview =
typeof lastMessage?.content === "string"
? lastMessage.content.slice(0, 280)
: JSON.stringify(lastMessage?.content ?? "").slice(0, 280);
console.log("[Logging] 模型返回:", preview);
return {
modelCallCount: state.modelCallCount + 1,
};
},
afterAgent: (state) => {
console.log(
`[Logging] Agent 结束,累计模型调用:${state.modelCallCount} 次`
);
},
});
const agent = createAgent({
model,
tools: [],
systemPrompt: "你是一个简洁、严谨的助手。",
middleware: [loggingMiddleware],
});
const result = await agent.invoke({
messages: [
new HumanMessage("用一句话解释 LangChain Middleware 是什么。"),
],
});
console.log("最终回复:", result.messages.at(-1)?.content);
console.log("返回状态中的调用次数:", result.modelCallCount);
这里有两个值得注意的点。
第一,z.number().default(0) 让中间件状态有默认值,调用 invoke 时无需手动传入 modelCallCount。
第二,afterModel 返回的对象会被合并进 Agent 状态,因此最终 invoke 的结果里也能读取到 modelCallCount。
如果把 Middleware 当成"只打日志的装饰器",就低估它了。它返回的状态更新、抛出的异常和路由命令,都会实际改变 Agent 行为。
五、实战二:用 wrapModelCall 动态改写系统上下文
假设同一个 Agent 在不同业务场景下需要附加不同规则。最直接的方式是静态改 systemPrompt,但这样会让每个请求都重建 Agent。
更灵活的做法是在 wrapModelCall 中修改本次模型请求:
js
import { createMiddleware } from "langchain";
const addContextMiddleware = createMiddleware({
name: "AddContextMiddleware",
wrapModelCall: async (request, handler) => {
console.log("[Context] 给本次模型请求追加业务规则");
return handler({
...request,
systemMessage: request.systemMessage.concat(
"\n\n补充规则:请优先给出结论,再用一句话解释依据。"
),
});
},
});
request.systemMessage 是 SystemMessage,concat 会生成新的系统消息。不要直接修改消息对象内部内容,使用新请求对象更安全,也更容易推理。
这个 Hook 还可以做很多事:
- 根据
request.runtime.context切换模型; - 对用户输入做脱敏;
- 根据租户裁剪可用工具;
- 在上下文接近上限时裁剪消息;
- 模型失败后切换备用模型重试;
- 在调用前做缓存命中判断。
一个原则是:wrap 函数承担的是横切逻辑,不应该把核心业务工具塞进 Middleware。 领域动作仍然应该是 Tool,Middleware 负责控制这些动作怎样被执行。
六、实战三:在模型调用前短路结束
有些请求不应该继续交给模型。例如输入中出现敏感标记、用户无权访问、系统正在维护,需要在模型调用前直接返回。
js
import {
AIMessage,
createMiddleware,
} from "langchain";
const blockedContentMiddleware = createMiddleware({
name: "BlockedContentMiddleware",
beforeModel: {
canJumpTo: ["end"],
hook: (state) => {
const lastMessage = state.messages.at(-1);
const text =
typeof lastMessage?.content === "string"
? lastMessage.content
: JSON.stringify(lastMessage?.content ?? "");
if (/\bBLOCKED\b/i.test(text)) {
console.log("[Blocked] 检测到拦截标记,跳过模型调用");
return {
messages: [
new AIMessage("该请求已被 Middleware 拦截,无法处理。"),
],
jumpTo: "end",
};
}
},
},
});
这里有三个细节。
第一,canJumpTo: ["end"] 是中间件向运行时声明自己可能跳往哪些目标。没有声明却返回对应 jumpTo,行为会不可靠。
第二,仅仅返回一条 AIMessage 并不一定足够。为了让这条消息成为调用方看到的最终回答,还需要把它写回 messages,并明确跳转到结束节点。
第三,原始 Demo 的输入里写的是 Block,判断条件却是 includes("BLOCKED"),两者并不一致,所以那个示例实际上不会触发拦截。本文统一使用 BLOCKED 并忽略大小写。真实业务还应处理空白字符、不可见字符和同义词,最好直接在结构化字段上做判断,而不是依赖容易漏判的自然语言关键词。
这类短路逻辑非常适合放在 beforeModel,因为它在模型产生成本之前就结束流程。
七、实战四:用 wrapToolCall 统计并包装工具结果
Middleware 不仅可以修改模型请求,还可以包住每一次工具调用。
下面这个例子做四件事:
- 把时间工具直接注册到 Middleware;
- 记录工具名称和参数;
- 在工具结果后追加统一标记;
- 通过
Command更新工具调用计数和消息状态。
js
import { z } from "zod";
import { Command } from "@langchain/langgraph";
import {
createAgent,
createMiddleware,
HumanMessage,
ToolMessage,
tool,
} from "langchain";
import { model } from "./model.mjs";
const getCurrentTime = tool(
() => new Date().toISOString(),
{
name: "get_current_time",
description: "返回当前 UTC 时间的 ISO 8601 字符串",
schema: z.object({}),
}
);
const extendedToolsMiddleware = createMiddleware({
name: "ExtendedToolsMiddleware",
stateSchema: z.object({
toolInvocationCount: z.number().default(0),
}),
// Middleware 也可以向 Agent 注入工具
tools: [getCurrentTime],
wrapToolCall: async (request, handler) => {
const toolName = request.tool?.name ?? request.toolCall.name;
console.log("[Tool] 即将执行:", toolName, request.toolCall.args);
const result = await handler(request);
if (!ToolMessage.isInstance(result)) {
return result;
}
const wrappedResult = new ToolMessage({
content: `${result.content}\n[wrapToolCall] 已由 Middleware 包装`,
tool_call_id: result.tool_call_id,
name: result.name,
});
return new Command({
update: {
toolInvocationCount: request.state.toolInvocationCount + 1,
messages: [wrappedResult],
},
});
},
afterAgent: (state) => {
console.log(
`[Tool] Agent 结束,累计工具调用:${state.toolInvocationCount} 次`
);
},
});
const agent = createAgent({
model,
// getCurrentTime 由 Middleware 注入,这里可以留空
tools: [],
systemPrompt: "你是一个助手。需要实时时间时必须调用工具。",
middleware: [extendedToolsMiddleware],
});
const result = await agent.invoke({
messages: [new HumanMessage("给我当前时间")],
});
console.log(result.messages);
console.log("工具调用次数:", result.toolInvocationCount);
这个例子最值得注意的是 Command。
普通 handler 返回 ToolMessage;如果我们返回自定义 Command,就可以同时更新:
messages:模型下一轮能看到的工具结果;- 自定义 state 字段:例如调用次数、状态标签、业务 ID;
- 路由信息:在更复杂的场景中决定下一步节点。
7.1 替换 ToolMessage 时必须保留 tool_call_id
当你在 wrapToolCall 中重建 ToolMessage 时,务必保留原结果的 tool_call_id。
因为模型之前返回的 AIMessage 中包含一个 tool call ID,后续的 ToolMessage 必须用相同 ID 与之对应。否则下一次模型请求可能直接报格式错误,尤其是 OpenAI、Anthropic、Gemini 等对工具调用配对要求严格的服务。
7.2 简单的 +1 在并行工具调用下不一定可靠
上面的计数示例适合作为入门。如果模型在同一轮返回多个并行工具调用,多个执行分支可能同时读到相同的旧状态,再各自写回 count + 1,最终出现覆盖。
生产环境建议:
- 使用外部指标系统按事件计数;
- 使用 LangGraph 的 reducer 合并并发状态更新;
- 或者把调用记录追加到独立事件列表,而不是依赖单个数值的读改写。
这也是 Middleware 设计的典型取舍:逻辑越接近运行时状态,就必须越关注并发和持久化语义。
八、从 createAgent 走向 DeepAgents
到这里,createAgent + Middleware 已经可以覆盖不少单 Agent 需求。
但复杂 Agent 还会遇到文件工作区、任务规划、子 Agent、上下文压缩、长期记忆和权限控制。DeepAgents 的价值就在于此:它把这些能力封装成一个 Harness。
DeepAgents 不是 LangGraph 的替代品,也不是一个"自动替你完成业务"的黑盒。它更像是给复杂 Agent 准备好的生产级操作台。
8.1 一个最小 DeepAgent
js
import { createDeepAgent } from "deepagents";
import { model } from "./model.mjs";
const agent = createDeepAgent({
model,
systemPrompt: "你是一个擅长调研和文件整理的助手。",
});
const result = await agent.invoke({
messages: [
{
role: "user",
content: "调研 LangGraph 的核心能力,并把结果写到 summary.md。",
},
],
});
console.log(result.messages.at(-1)?.content);
createDeepAgent() 返回的仍然是 LangChain 的 ReactAgent 形态,底层编译为 LangGraph 图。因此 Checkpointer、Store、Studio、LangSmith、流式执行等 LangGraph 能力仍然可以使用。
本地 deepagents@1.16.5 的默认装配大致包括:
- 文件系统 Middleware;
- 子 Agent Middleware 与
task工具; - 上下文摘要 Middleware;
- 工具调用与工具结果配对修复 Middleware;
- 可选的 Skills、Memory、提示词缓存、人工中断和模型拒答处理;
- 默认较高的递归上限,用来支持长任务。
不同模型 Harness Profile 还可能追加规划等能力。若要确保业务 Agent 始终拥有待办规划,可以显式加入 todoListMiddleware(),不要只依赖模型默认行为。
8.2 DeepAgents 帮你省掉的不是"提示词",而是运行时复杂度
| 能力 | 解决的问题 | 为什么自己实现很麻烦 |
|---|---|---|
| 文件系统工具 | 读写工作记忆、生成中间产物 | 路径解析、虚拟根目录、大小限制、权限、符号链接 |
| 任务规划 | 长任务拆解和进度跟踪 | 工具 schema、状态更新、并行冲突、何时结束 |
| 子 Agent | 隔离上下文、并行处理独立任务 | 任务描述、上下文继承、权限边界、结果回传 |
| 摘要压缩 | 上下文超长 | 摘要阈值、保留窗口、旧消息卸载、恢复 |
| 工具配对修复 | 修复缺失或孤立的 ToolMessage | 不同模型的工具调用格式与严格程度不同 |
| 长期记忆 | 跨会话保存偏好和知识 | Store、命名空间、加载时机、污染控制 |
这些能力彼此关联。单独做一个文件读写工具不难,难的是让它与状态、权限、上下文压缩和子 Agent 一起稳定工作。
九、实战五:带权限的虚拟文件工作区
下面是最能体现 DeepAgents 价值的一段代码:Agent 可以像操作 / 一样操作文件,但真实文件被限制在一个固定目录中。
js
import "dotenv/config";
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { ChatOpenAI } from "@langchain/openai";
import {
createFilesystemMiddleware,
FilesystemBackend,
} from "deepagents";
import {
createAgent,
HumanMessage,
ToolMessage,
} from "langchain";
const model = new ChatOpenAI({
model: process.env.MODEL_NAME,
apiKey: process.env.OPENAI_API_KEY,
configuration: {
baseURL: process.env.OPENAI_BASE_URL,
},
temperature: 0,
});
const workspaceDir = path.join(
path.dirname(fileURLToPath(import.meta.url)),
"workspace"
);
fs.mkdirSync(workspaceDir, { recursive: true });
fs.writeFileSync(
path.join(workspaceDir, "secret.txt"),
"机密:不得读取",
"utf8"
);
// 第一条匹配生效;没有匹配时默认放行
const permissions = [
{
operations: ["read"],
paths: ["/secret.txt"],
mode: "deny",
},
{
operations: ["read", "write"],
paths: ["/notes/**", "/todo.md"],
mode: "allow",
},
{
operations: ["read", "write"],
paths: ["/**"],
mode: "deny",
},
];
const agent = createAgent({
model,
tools: [],
systemPrompt: `
你是文件整理助手。
工作区根路径是 /。
只能使用 ls、read_file、write_file、edit_file、glob、grep 操作文件。
所有路径都必须以 / 开头。
`,
middleware: [
createFilesystemMiddleware({
// 只暴露需要的工具,从工具层面禁用 execute 和 delete
tools: ["ls", "read_file", "write_file", "edit_file", "glob", "grep"],
permissions,
backend: new FilesystemBackend({
rootDir: workspaceDir,
virtualMode: true,
}),
}),
],
});
const result = await agent.invoke(
{
messages: [
new HumanMessage(
"先读取 /secret.txt,再把内容写入 /todo.md,并说明是否成功。"
),
],
},
{
recursionLimit: 20,
}
);
console.log(result.messages);
const denied = result.messages.some(
(message) =>
ToolMessage.isInstance(message) &&
message.status === "error" &&
/permission denied/i.test(String(message.content))
);
console.log(denied ? "权限校验按预期生效" : "未观察到预期的权限拒绝");
9.1 virtualMode 的意义
设置:
js
new FilesystemBackend({
rootDir: workspaceDir,
virtualMode: true,
});
之后,模型看到的是虚拟根目录 /,实际路径会映射到 workspaceDir 内部。
这样做的意义是:
- 模型不需要知道服务器真实路径;
- 所有文件操作都被约束在业务工作区内;
- 不同用户或不同任务可以挂载不同工作区;
- 提示词更稳定,不会因为部署机器路径变化而失效。
9.2 权限规则的真实语义
当前版本的文件系统权限有几个关键规则:
- 只支持
read和write两类操作; - 规则按声明顺序检查;
- 第一个同时匹配"操作类型 + 路径 glob"的规则生效;
- 如果没有任何规则匹配,默认放行;
- 路径会先规范化,
FilesystemBackend还会检查符号链接真实目标。
因此,生产策略通常要按这个顺序组织:
text
最具体的 deny 规则
↓
明确的 allow 规则
↓
全局兜底 deny
只写"禁止某个文件"而忘记兜底规则,可能留下大量默认可访问路径。
9.3 权限参数应该放在 Middleware,而不是 Backend
示例源码的 FilesystemBackend 构造器旁有一条 // permissions 注释,但当前 API 中真正执行权限校验的位置是:
js
createFilesystemMiddleware({
permissions,
backend: new FilesystemBackend({
rootDir: workspaceDir,
virtualMode: true,
}),
});
FilesystemBackend 负责落实文件访问,createFilesystemMiddleware 负责工具注册、路径策略和权限检查。两者职责不同。
9.4 execute 是另一条安全边界
文件路径权限只约束文件系统工具,不应被误解成通用沙箱权限。
如果 Backend 支持命令执行,execute 可能绕过按路径声明的读权限。当前 DeepAgents API 明确提示:在可执行后端上同时配置路径权限会产生配置风险,通常应显式禁用 execute,或者由真正隔离的沙箱和操作系统权限体系承担安全边界。
DeepAgents 的安全原则不是"相信模型会遵守提示词",而是"只给模型允许使用的工具,并在工具和沙箱层强制约束"。
十、文件、状态、长期记忆应该怎么选
复杂 Agent 经常把所有东西都塞进 messages,最后上下文爆炸。DeepAgents 提供多种存储层次,应该按生命周期区分。
| 载体 | 生命周期 | 适合存放 |
|---|---|---|
| Agent State | 一个线程,可被 Checkpointer 恢复 | 当前任务进度、计数字段、待办状态 |
StateBackend |
默认文件状态,通常随线程和检查点流转 | 当前会话的临时文件 |
FilesystemBackend |
真实磁盘 | 工作区产物、用户上传文件、大型中间结果 |
StoreBackend |
跨线程、长期保存 | 用户偏好、组织知识、跨会话记忆 |
| 子 Agent 上下文 | 单次委派 | 独立调研、代码分析、批量搜索 |
一个实用判断标准是:
text
下一轮模型必须逐字看到的内容 → messages
Agent 工作过程中需要读写的材料 → filesystem
跨任务保留的稳定事实 → store / memory
可以独立完成并可丢弃过程的任务 → subagent
不要把几十页文档直接放进每一轮消息。更合理的做法是写入文件,让模型通过 grep、glob、read_file 按需分段读取。
同理,不要把长期用户偏好当成当前任务状态。长期事实应进入 Store 或记忆文件,当前运行所需的租户信息则可以通过 contextSchema 传入。
十一、实战六:用子 Agent 隔离上下文
主 Agent 处理所有任务时,最容易出现两个问题:
- 调研过程产生大量中间消息,导致主上下文迅速膨胀;
- 多个互不依赖的任务串行执行,浪费时间。
子 Agent 的核心价值,是让独立任务拥有自己的上下文窗口,只把最终结果交回主 Agent。
js
import { z } from "zod";
import { createDeepAgent } from "deepagents";
import { model } from "./model.mjs";
import { webSearch } from "./tools/web-search.mjs";
const researcher = {
name: "researcher",
description:
"负责调研复杂主题。输入要足够完整,输出结构化摘要和来源列表。",
systemPrompt: `
你是一名研究助手。
先拆解问题,再搜索资料,只返回结论、关键证据和来源。
不要复述搜索过程。
`,
tools: [webSearch],
responseFormat: z.object({
summary: z.string(),
keyPoints: z.array(z.string()),
sources: z.array(z.string()),
confidence: z.number().min(0).max(1),
}),
};
const agent = createDeepAgent({
model,
tools: [webSearch],
subagents: [researcher],
systemPrompt: `
你是主协调 Agent。
可以独立完成的简单任务直接处理。
需要大量搜索或多个相互独立的调研任务时,使用 task 工具委派给合适的子 Agent。
`,
});
const result = await agent.invoke({
messages: [
{
role: "user",
content:
"调研 DeepAgents 的文件系统、子 Agent 和上下文压缩能力,分别给出结论并汇总。",
},
],
});
console.log(result.messages.at(-1)?.content);
这里的 task 工具由 SubAgent Middleware 自动提供。主模型通过两个关键字段做委派:
description:完整任务说明;subagent_type:目标子 Agent 名称。
11.1 isolated 与 fork 的区别
当前 DeepAgents 子 Agent 默认使用 isolated 模式:
- 只能看到本次委派的任务描述;
- 看不到主 Agent 的完整对话;
- 中间过程留在自己的上下文中;
- 结束后返回一个结果。
另一种 fork 模式会继承父对话,适合"基于当前讨论继续深入"的后台任务。但 fork 会复制上下文,也会增加 token 成本和缓存失配风险,不应作为默认选择。
11.2 子 Agent 的任务描述必须自包含
在 isolated 模式下,下面这种调用没有意义:
text
"继续研究刚才那个问题。"
因为子 Agent 并不知道"刚才那个问题"是什么。好的任务描述应该包含背景、目标、输入、约束和输出格式。
11.3 子 Agent 权限是替换,不是合并
这是一个容易踩坑的细节:
- 如果子 Agent 没有声明
permissions,它继承父 Agent 的权限; - 如果声明了
permissions,这些规则会整体替换父 Agent 的权限,而不是叠加。
因此给子 Agent 单独配置权限时,要把它需要的白名单、黑名单和兜底规则完整写出来。
十二、DeepAgents 默认运行栈怎样与 LangGraph 对接
因为 createDeepAgent 最终返回 LangGraph 原生 Agent,所以可以接入现有的运行时能力。
12.1 Checkpointer:支持恢复和人工中断
js
const agent = createDeepAgent({
model,
checkpointer: true,
interruptOn: {
send_email: {
allowedDecisions: ["approve", "edit", "reject"],
},
},
});
高风险工具不应该仅靠"提示词提醒模型谨慎"。更可靠的方式是:
- 把危险动作封装成明确工具;
- 在
interruptOn中要求人工审批; - 用 Checkpointer 保存中断前的图状态;
- 审批或修改参数后从原线程恢复。
人工中断不是日志功能,而是工作流的一部分。业务需要定义谁能审批、审批超时怎么办、拒绝后的替代路径是什么。
12.2 Store:跨会话的长期记忆
checkpointer 更关注"同一条会话线程怎样恢复",store 更关注"不同线程之间怎样共享长期事实"。
一个典型划分:
text
thread_id = 当前会话
checkpointer = 这条会话的执行现场
store = 用户、组织、项目层面的长期知识
filesystem = 本次任务的工作台
不要把所有信息都持久化。长期记忆需要写入策略、去重策略、过期策略和删除能力,否则 Agent 会把过时事实当成当前事实。
12.3 流式执行与可观测性
DeepAgents 可以使用 LangGraph 的流式接口,也可以使用其更面向 Agent 的投影接口观察消息、工具调用和子 Agent。
对于生产系统,至少应记录:
- 模型调用次数和 token;
- 每次工具调用的输入、输出、耗时和错误;
- 子 Agent 的委派任务和最终结果;
- 中断、恢复和拒绝记录;
- 递归步数和上下文压缩事件;
- 结构化输出校验失败;
- 租户、用户、任务等业务维度。
建议用 LangSmith 或现有 OpenTelemetry 体系统一追踪,而不是只在 Middleware 里 console.log。
十三、生产落地时必须补上的几个边界
13.1 用执行上限防止无限循环
recursionLimit 是图运行的保险丝,不是性能调优按钮。
入门示例可以把上限设得较小:
js
const result = await agent.invoke(
{ messages: [new HumanMessage("完成任务")] },
{ recursionLimit: 20 }
);
DeepAgents 为了长任务会设置较大的默认递归上限,但业务仍应结合模型调用限额、工具调用限额、超时时间和取消信号做总预算。
13.2 区分"模型失败"和"工具失败"
模型调用的重试策略与工具执行的重试策略不同:
- 限流、网络抖动适合模型重试;
- 参数校验失败重试同一个工具通常没有意义;
- 读取临时文件失败可以重试;
- 支付、邮件、删除等非幂等工具不能盲目重试。
重试必须有次数、退避和幂等键。
13.3 提示词不是权限系统
下面这段话只能算"软约束":
text
请不要读取 secret.txt。
真正的约束至少包括:
- 不向模型暴露不需要的工具;
- 在
wrapToolCall或文件系统 Middleware 中做策略检查; - 使用虚拟根目录;
- 文件权限设置显式兜底
deny; - 命令执行放入隔离沙箱;
- 高风险操作启用人工审批;
- 密钥通过服务端注入,不进入模型上下文。
13.4 不要把所有上下文都塞进状态
"可以持久化"不等于"应该持久化"。
大文件、二进制内容、重复工具返回和中间搜索结果更适合放进文件系统;只有下一步推理真正需要的摘要和引用应留在消息历史中。
13.5 为结构化输出定义失败策略
结构化输出很适合把 Agent 结果交给下游程序,但模型不保证每次都完美符合 schema。
业务需要决定:
- 校验失败后重试几次;
- 是否返回部分结果;
- 是否进入人工处理队列;
- 是否记录原始输出用于分析;
- 回退模型是否支持同一输出格式。
13.6 给 Middleware 写测试
Middleware 经常承载安全、预算和路由逻辑,不能只靠手工观察日志。
至少应覆盖:
- Hook 是否在预期轮次执行;
- 短路后最终消息是否正确;
- 工具结果的
tool_call_id是否保留; - 多个 Middleware 的顺序是否符合预期;
- 状态更新是否被正确合并;
- 异常是否会被错误吞掉;
- 并行动作下计数和权限是否仍然可靠。
十四、什么时候用 createAgent,什么时候用 DeepAgents
可以用一个简单决策表判断:
| 场景 | 推荐方案 |
|---|---|
| 单轮问答、文本分类 | 直接调用模型 |
| 少量工具、单 Agent、强定制 | createAgent |
| 工具 + 预算 + 日志 + 权限策略 | createAgent + Middleware |
| 长任务、文件工作区、上下文压缩 | createDeepAgent |
| 独立调研、并行任务、隔离上下文 | DeepAgents 子 Agent |
| 高风险动作需要人工审批 | Agent + Checkpointer + HITL |
| 确定性很强的业务流程 | 显式 LangGraph 图,Agent 只处理开放式节点 |
| 合规审计要求极高 | LangGraph + 外部策略引擎 + 沙箱 + 审计存储 |
一个常见误区是:只要任务复杂,就应该让 Agent 自己决定一切。
更好的设计通常是混合式:
- 固定、可重复、强审计的步骤由 LangGraph 节点或普通代码完成;
- 需要理解自然语言、动态选择工具、归纳结果的步骤交给 Agent;
- 危险边界通过权限、审批和沙箱强制约束;
- 验收由独立代码或规则完成,而不是让同一个模型自证正确。
十五、一套推荐的代码组织方式
把全部逻辑写进一个 index.mjs 只适合演示。生产项目可以按下面的结构拆分:
text
src/
├─ model.mjs
├─ agents/
│ ├─ research-agent.mjs
│ └─ workspace-agent.mjs
├─ middleware/
│ ├─ logging.mjs
│ ├─ guardrails.mjs
│ └─ metrics.mjs
├─ tools/
│ ├─ search.mjs
│ └─ database.mjs
├─ policies/
│ └─ filesystem-permissions.mjs
├─ runtime/
│ ├─ checkpointer.mjs
│ └─ store.mjs
└─ index.mjs
几个原则:
- 模型配置集中管理,避免每个 Agent 各自读取环境变量;
- 权限策略独立成文件,便于测试和审计;
- Middleware 只放横切能力,领域动作放 Tool;
- 子 Agent 的 description 和 systemPrompt 要像 API 文档一样明确;
- Checkpointer、Store 和 Backend 的生命周期由应用运行时统一创建;
- 不要在源码中硬编码密钥、租户策略或生产路径。
十六、最后的完整心智模型
如果把整篇文章压缩成几句话:
createAgent封装的是一个"模型调用、工具执行、消息回流"的循环;- Middleware 是插入这个循环的扩展点,可以读取和更新状态、改写模型请求、包装工具结果、做短路和路由;
- DeepAgents 是在
createAgent与 LangGraph 之上的 Harness,预先组合了文件系统、子 Agent、摘要压缩等复杂能力; - 复杂 Agent 的本质不是写一个更长的提示词,而是设计清楚状态、工具、权限、上下文和恢复边界;
- 生产环境最终需要的是可观测、可限制、可恢复、可审计的系统,而不是一个偶尔能跑通的任务 Demo。
可以记住这个分工:
text
LangChain 给积木
LangGraph 给运行时
DeepAgents 给复杂 Agent 的装配台
Middleware 给横切扩展
Tool 给领域能力
Policy 给安全边界
测试 给迭代信心
从 createAgent 写起,能够帮助你看清 Agent 的基本运行原理;当文件、计划、上下文压缩和子 Agent 开始重复出现时,再引入 DeepAgents,才能既保持可控性,又避免重复造基础设施。
复杂 Agent 的门槛,往往不在于"让模型调一次工具",而在于让它在一个有边界、有预算、有记忆、有恢复能力的环境中持续完成任务。理解这些边界之后,再回头看 createAgent 和 Middleware,它们就不再是 API 清单,而会变成你设计生产级 Agent 的清晰切面。
参考资料
- LangChain JavaScript Agents
- LangChain JavaScript Middleware
- LangGraph JavaScript Overview
- Deep Agents JavaScript Overview
- Deep Agents JavaScript GitHub
版本提示:本文示例以
langchain@1.6.6、@langchain/langgraph@1.7.4、deepagents@1.16.5为基线。Agent 框架仍在快速演进,升级后请优先核对 Middleware Hook、权限配置和 Backend API 的类型定义。