用 LangGraph 画完图之后,真正落地一个复杂 Agent,还有一堆活要自己补:文件读写、上下文压缩、长期记忆、子 Agent 调度、权限控制......
这些活,每个 Agent 都要重新干一遍。
DeepAgents 的思路是把它们做成中间件 和内置能力 。这篇用 6 个基础脚本 + 1 个完整项目,从
createAgent的中间件机制一路拼出一个会分工、会写报告的多 Agent 深度调研助手。
一、DeepAgents 在生态里的位置
先把三个框架摆在一起:
| LangChain | LangGraph | DeepAgents | |
|---|---|---|---|
| 定位 | AI 开发积木 | 复杂工作流底层蓝图 | 面向生产的高阶封装 |
| 提供什么 | LLM、Loader、Splitter、Embedding、VectorStore、Parser... | 节点、边、状态、持久化、中断恢复 | createAgent / createDeepAgent + 内置中间件 |
| 编排形态 | 线性链 | 网状图 | 开箱即用的 Agent 骨架 |
| 适合 | 简单链路 | 复杂多 Agent 协作 | 快速落地复杂 Agent 应用 |
用一句话概括三者的关系:
LangChain 给你一堆积木,LangGraph 给你搭积木的图纸,DeepAgents 直接给你一个装好水电的精装房------你只需要装修业务逻辑。
它封装掉的正是那些「每个 Agent 都要做一遍」的基建:
- 状态管理与循环路由;
- 持久化执行;
- 任务规划(
write_todos); - 长期记忆(
AGENTS.md); - 子 Agent 调度(
task); - 上下文压缩(摘要);
- 文件系统与权限。
所以这条演进路线是:基础模块 → 工作流编排 → 生产级 Agent 封装。 你依然可以往下钻到 LangGraph 的图,但大多数时候,不需要。
createAgent 和 createDeepAgent 有什么区别
createAgent(langchain) |
createDeepAgent(deepagents) |
|
|---|---|---|
| 定位 | 单 Agent 快速启动 | 完整多 Agent 系统 |
| 内置 | messages 循环、model / tools / systemPrompt / middleware | 在 createAgent 之上再加规划、文件、子 Agent、技能、记忆 |
| 适合 | 单兵作战、加中间件做增强 | 主 Agent + 子 Agent 协作的复杂任务 |
下文先讲 createAgent 的中间件机制------这是整个框架的地基;再讲 createDeepAgent 如何把这些能力组装成一个团队。
二、第一个 Agent:createAgent + 文件系统中间件
demo/src/deepagents/filesystem-agent.mjs 是最小可运行例子:一个只有文件工具的 Agent,外加一套权限规则。
2.1 建 Agent
js
import { ChatOpenAI } from "@langchain/openai";
import {
createFilesystemMiddleware, // 文件系统中间件
FilesystemBackend, // 落实文件操作的后端
} from "deepagents";
import { createAgent, HumanMessage } 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 agent = createAgent({
model,
tools: [], // 注意:tools 是空的
systemPrompt: `
工作区根路径为 /。用 ls、read_file、write_file、edit_file 操作文件,
路径以 / 开头。中文回答。
`,
middleware: [
createFilesystemMiddleware({
permissions,
backend: new FilesystemBackend({
rootDir: workspaceDir,
virtualMode: true,
}),
}),
],
});
第一个反直觉的点:tools: [] 是空的,但 Agent 会 ls、read_file、write_file、edit_file。
工具是中间件注入的。这就是「中间件是 Agent 的一部分」------它不只是加日志,还可以给 Agent 加状态、加工具、加提示词、改流程。
FilesystemBackend 负责把「虚拟路径」映射到真实磁盘:
js
const workspaceDir = path.join(
path.dirname(fileURLToPath(import.meta.url)),
"workspace"
);
virtualMode: true 之后,Agent 看到的是 /、/secret.txt,实际落在 workspace/secret.txt。隔离真实路径,也方便把同一套 Agent 搬到不同目录。
2.2 权限:harness 该管的边界
js
const permissions = [
{ operations: ["read"], paths: ["/secret.txt"], mode: "deny" },
{ operations: ["write"], paths: ["/todo.md"], mode: "allow" },
{ operations: ["write"], paths: ["/**"], mode: "deny" },
];
翻译成业务语言:
| 操作 | 路径 | 结果 |
|---|---|---|
| 读 | /secret.txt |
拒绝 |
| 写 | /todo.md |
允许 |
| 写 | 其他任何路径 | 拒绝 |
这套规则的设计意图很清楚:给 Agent 一个精确的可写面。 能读什么、能写什么,由 harness 决定,而不是靠模型自觉。
注意顺序:allow /todo.md 必须写在 deny /** 前面。规则按顺序匹配、命中即止,兜底规则永远放最后。
2.3 验证「拒绝」真的生效
expectDenied 不是去看模型怎么说,而是去翻工具消息:
js
const denied = messages.some(
(m) =>
m.getType?.() === "tool" &&
m.status === "error" &&
/permission denied/.test(String(m.content))
);
console.log(denied ? "OK: 已拒绝" : "未触发拒绝(异常)");
这一步很关键。权限是否生效,要看工具层的 status: "error",而不是听模型汇报。 模型完全可能说「我不能读」,但其实它压根没调用工具。
bash
node src/deepagents/filesystem-agent.mjs
demo 最后一行执行的是:
js
await expectDenied("禁止写", "只调用 write_file, 路径 /hack.txt, 内容 text。");
写被拒绝的路径,工具返回 permission denied,验证通过。
三、中间件:Agent 的「插件系统」
文件系统中间件是现成的,但真正让 DeepAgents 灵活的是你可以自己写中间件。
一个请求的生命周期大致是:
erlang
用户请求 → beforeAgent → [beforeModel → 模型 → afterModel]* → afterAgent → 响应
中间件可以挂在任意阶段,也可以包住模型调用和工具调用:
| Hook | 时机 | 典型用途 |
|---|---|---|
beforeAgent |
Agent 开始前 | 初始化日志、注入上下文 |
beforeModel |
每次调模型前 | 改提示词、拦截请求、统计 |
afterModel |
每次模型返回后 | 记录 token、累加状态 |
afterAgent |
Agent 结束后 | 汇总指标、落盘 |
wrapModelCall |
包住一次模型调用 | 改请求 / 改响应 / 重试 |
wrapToolCall |
包住一次工具调用 | 审计参数、包装返回值 |
stateSchema |
声明时 | 给 Agent 增加自定义状态字段 |
demo/src/middleware-test.mjs 一次展示了三种能力。
3.1 给 Agent 加状态:模型调用计数
js
const loggingMiddleware = createMiddleware({
name: "LoggingMiddleware",
stateSchema: z.object({
modelCallCount: z.number().default(0),
}),
beforeAgent: (state) => {
console.log("\n [Logging] agent 开始,消息数:", state.messages.length);
},
beforeModel: (state) => {
console.log(`[Logging] 即将调用模型,已调用 ${state.modelCallCount} 次`);
},
afterModel: (state) => {
return { modelCallCount: state.modelCallCount + 1 };
},
afterAgent: (state) => {
console.log(`[Logging] agent 结束,累计模型调用:${state.modelCallCount} 次`);
},
});
stateSchema 声明的字段会进入 Agent 的状态,也会出现在 invoke() 的返回值里:
js
const { messages, modelCallCount } = await agent.invoke({
messages: [new HumanMessage(text)],
});
中间件不该只是一个旁观的日志器------它可以有状态,可以影响结果。 这个计数后面还能拿来做成本统计、循环检测。
3.2 改模型调用:wrapModelCall
js
const addContextMiddleware = createMiddleware({
name: "AddContextMiddleware",
wrapModelCall: async (request, handler) => {
console.log("[Add Context] 注入额外 system 上下文");
return handler({
...request,
systemMessage: request.systemMessage.concat("\n\n 请用一句话简洁回答"),
});
},
});
wrapModelCall 是典型的洋葱模型:拿到 request 和下一层 handler,想改什么改什么,最后把 handler 的结果返回。
这里给 system message 追加了一句「请用一句话简洁回答」------不用改业务代码里的 systemPrompt,一个中间件就完成了全局追加。 多租户场景下按用户追加不同约束,也是同一个套路。
3.3 短路:beforeModel 直接跳到结束
js
const blockedContentMiddleware = createMiddleware({
name: "BlockedContentMiddleware",
beforeModel: {
canJumpTo: ["end"],
hook: (state) => {
const last = state.messages.at(-1);
const text = typeof last?.content === "string"
? last.content
: String(last?.content ?? "");
if (text.includes("BLOCKED")) {
console.log("[Blocked] 检测到 Blocked,短路结束");
return {
messages: [new AIMessage("该请求已被 middleware 拦截,无法处理")],
jumpTo: "end",
};
}
},
},
});
两个要点:
canJumpTo: ["end"]是在声明这个中间件有跳转权限;- 返回
jumpTo: "end"才真正执行跳转。
这给了 harness 一个「一票否决」的能力:敏感词、越权请求、额度耗尽,在模型调用前就能终止,不花一分 token。
3.4 中间件的顺序
js
middleware: [
loggingMiddleware,
addContextMiddleware,
blockedContentMiddleware,
]
before* 按声明顺序执行,after* 反过来,wrap* 层层包裹。所以:
- 日志中间件放最外层,能记录到完整的调用次数;
- 拦截中间件放里层,先注入上下文、再判断拦截,还是反过来,取决于你希望拦截看到什么。
四、记忆:把「记住」落成文件
上下文窗口之外,Agent 还需要「跨会话记住」。DeepAgents 的做法不是做一个黑盒向量库,而是把记忆写进文件。
demo/src/deepagents/memory-agent.mjs:
js
const projectMemoryPath = "/AGENTS.md"; // 项目记忆
const preferencesMemoryPath = "/memory/preferences.md"; // 用户偏好
const agent = createAgent({
model,
tools: [],
systemPrompt: [
"你是项目助手。工作区根路径为 /,可用 ls、read_file、write_file、edit_file。",
"根据 <agent_memory> 回答:用户要求记住时,必须立刻 edit_file,且按类型写入对应文件",
`- ${projectMemoryPath}: 项目说明、技术栈、架构、仓库约定等`,
`- ${preferencesMemoryPath}: 用户个人偏好(语言、包管理器、回答风格等)`,
"不要混写:项目事实不要写入 preferences,个人偏好不要写入 AGENTS.md。",
].join("\n"),
middleware: [
createFilesystemMiddleware({ backend }),
createMemoryMiddleware({
backend,
sources: [projectMemoryPath, preferencesMemoryPath],
}),
],
});
createMemoryMiddleware 负责两件事:
- 读 :把
sources里的文件内容注入上下文(system prompt 里的<agent_memory>); - 写:配合文件工具,让 Agent 在用户说「记住」时更新对应文件。
4.1 为什么用文件而不是向量库
| 文件记忆 | 向量库记忆 | |
|---|---|---|
| 可读性 | 人可以直接看、直接改 | 存进去是 embedding,难核对 |
| 可控性 | git diff 能看到每次变化 | 黑盒更新 |
| 适用 | 少量、高价值的长期事实 | 大量、模糊的语义检索 |
| 风险 | 需要控制文件大小 | 可能召回旧偏好 |
demo 跑完后的真实产物,就是这么两份小文件:
md
<!-- workspace-memory/AGENTS.md -->
## 主入口脚本
- `src/deepagents/memory-agent.mjs`
md
<!-- workspace-memory/memory/preferences.md -->
## 包管理器
- 常用包管理器:pnpm
Agent 先在第一轮读出 <agent_memory> 回答「这个项目是做什么的」,再在后续轮次把「pnpm」「入口脚本」分别写进正确的文件,最后同时答出两个问题。
记忆的关键不是「存下来」,而是「分类存」。 把用户偏好写进项目文档、把项目事实写进偏好,下一次对话就会得到互相矛盾的上下文。所以 system prompt 里那句「不要混写」不是废话。
4.2 虚拟路径与真实路径
Agent 看到的是 /AGENTS.md,磁盘上是:
bash
workspace-memory/AGENTS.md
workspace-memory/memory/preferences.md
FilesystemBackend 的 rootDir 做了这层映射。好处是同一套 prompt 可以跑在不同用户的目录下,Agent 不需要知道宿主机路径。
五、摘要:上下文快满了怎么办
多轮对话迟早会撞上上下文窗口。DeepAgents 的解法是摘要中间件:到阈值就把旧消息压缩成摘要,写进文件,再带着摘要继续聊。
demo/src/deepagents/summarization-agent.mjs:
js
const summaryPrompt = `你是对话摘要助手。请用中文总结以下对话,包含:
1. 讨论的主要话题
2. 达成的关键结论或决定
3. 继续对话所需的重要上下文
保持简洁,不要罗列无关细节。
待摘要的对话:
{conversation}
摘要:`;
const agent = createAgent({
model,
tools: [],
systemPrompt:
"你是会话助手。记住用户提到的关键事实,中文简短回答。若看到「此前对话摘要」,请据此继续对话。",
middleware: [
createSummarizationMiddleware({
model,
backend,
historyPathPrefix: "/conversation_history",
summaryPrompt,
trigger: { type: "messages", value: 8 },
keep: { type: "messages", value: 4 },
}),
],
});
三个参数决定行为:
| 参数 | 含义 |
|---|---|
trigger |
消息数到 8 就触发摘要(demo 故意调低,方便看到效果) |
keep |
保留最近 4 条,之前的压缩 |
historyPathPrefix |
摘要写到 /conversation_history/ 下 |
跑完在磁盘上能看到真实的摘要文件:
md
<!-- conversation_history/session_46942268.md -->
## Summarized at 2026-10-03T13:28:39.480Z
Human: 请记住:我的宠物猫叫小橘。
AI: 好的,已记住你的宠物猫叫小橘。
Human: 请记住:我住在北京。
AI: 好的,已记住你住在北京。
Human: 请记住:我喜欢喝拿铁。
这就是「压缩」的落地形态:不是丢掉旧消息,而是把旧消息换成一个可追溯的摘要文件,同时释放上下文窗口。出了问题还能回去翻原文。
5.1 两个版本的差别
仓库里有 summarization-agent.mjs 和 summarization-agent2.mjs,核心配置一样,差别在于:
- 第一个同时挂了
createFilesystemMiddleware和createSummarizationMiddleware,并额外监听历史目录,打印「已触发摘要」; - 第二个只有摘要中间件,用来验证摘要中间件自己就能通过 backend 写历史文件,不依赖文件系统中间件。
这是个很好的对照实验:中间件之间的能力是解耦的,按需组合即可。
生产环境不用把阈值调得这么低。注释里写得很清楚:可省略
trigger/keep,由模型 profile 自动推断。
六、完整项目:一个主 Agent + 三个子 Agent
基础能力讲完,来看 deep-research-assistant------一个真实的深度调研系统。
入口只有一句:
bash
node src/cli.mjs "调研国家统计局公开的2023年省级GDP数据,提取前6名......"
它背后是一张多 Agent 协作图:
6.1 组装:createDeepAgent
js
export function createIntelligenceDeskAgent() {
const apiKey = process.env.OPENAI_API_KEY?.trim();
if (!apiKey) throw new Error("OPENAI_API_KEY is not set");
const backend = new FilesystemBackend({
rootDir: projectDir,
virtualMode: true,
});
return createDeepAgent({
model,
systemPrompt: orchestratorPrompt,
subagents: [researchSubAgent, analystSubAgent, editorSubAgent],
memory: [path.join(projectDir, "AGENTS.md")],
backend,
skills: ["/skills/"],
});
}
对比 createAgent,多了五个关键参数:
| 参数 | 作用 |
|---|---|
subagents |
可被 task 工具委派的子 Agent 列表 |
memory |
长期记忆文件 |
backend |
文件系统后端(虚拟路径映射) |
skills |
技能目录,按需加载的写作 / 调研指南 |
systemPrompt |
主 Agent 的编排规则 |
createDeepAgent 会自动挂上规划(write_todos)、文件系统、子 Agent 委派(task)这些能力------主 Agent 不用自己实现调度逻辑,只负责「决定派谁去」。
6.2 三个子 Agent,三种分工
| 子 Agent | 职责 | 关键手段 | 产出 |
|---|---|---|---|
researcher |
调研一个子主题 | web_search(Bocha API),最多 3 次 |
/workspace/sources/findings_*.md |
analyst |
数值计算与数据分析 | QuickJS 沙箱里执行 JS | /workspace/sources/analysis_*.md |
editor |
审阅报告草稿 | 只给意见,不改文件 | 审阅建议(返回给主 Agent) |
researcher:限制比能力更重要
js
const researchSubAgent = {
name: "researcher",
description:
"通过联网搜索调研单一子主题。每次只分配一个子主题;多个独立子主题可并行启动多个调研员。",
systemPrompt: dedent`
你是一名专业调研员,负责调研**一个**分配给你的子主题,并写入**一份**调研结果文件。
## 工作流程(严格遵守,禁止空转循环)
1. **可选**: 用 write_todos 列出最多 3 条中文执行步骤
2. 最多调用 3 次 web_search(硬性上限,绝不超过)
3. 将搜索结果整理为结构化摘要,包含关键事实与来源 URL
4. 调用 write_file **一次**,保存到 /workspace/sources/findings_*.md
5. 用一句话确认已完成,然后**立即停止**
`,
tools: [webSearch],
};
这段 prompt 里全是「上限」:最多 3 步、最多 3 次搜索、只写一次文件、写完立刻停。
为什么把限制写这么死? 因为调研类 Agent 最容易出的问题不是能力不足,而是空转:反复搜索相似关键词、不断更新 todo、写了改改了写,token 烧完了报告还没出来。多 Agent 并行的场景下,一个子 Agent 空转,整体成本会成倍放大。
webSearch 工具本身很简单,包的是 Bocha 的搜索 API:
js
export const webSearch = tool(
async (input) => {
const count = input.count ?? 10;
return bochaWebSearch(input.query, count);
},
{
name: "web_search",
description: "使用 Bocha 联网搜索 API 检索互联网网页......",
schema: z.object({
query: z.string().min(1).describe("搜索关键词,优先使用中文"),
count: z.number().int().min(1).max(20).optional(),
}),
}
);
analyst:LLM 不擅长算数,但擅长写代码
js
const analystSubAgent = {
name: "analyst",
description:
"使用 eval REPL 进行数值计算与结构化数据分析。适用于计算、排名、同比对比或 JSON/CSV 分析。",
systemPrompt: dedent`
你是一名数据分析师,所有计算必须通过 eval REPL 完成,**禁止**猜测数字。
...
`,
middleware: [createCodeInterpreterMiddleware()],
};
createCodeInterpreterMiddleware() 来自 @langchain/quickjs,给子 Agent 一个 QuickJS 沙箱:模型写 JS、沙箱里执行、拿回结果。
这是整个项目里我最喜欢的设计:
LLM 不擅长计算,但擅长写代码并完成计算。 把「算」这件事交给确定性执行环境,模型只负责把问题翻译成代码。
沙箱保证算错了、写出死循环,也不会影响主进程。
editor:审阅与修订分离
js
const editorSubAgent = {
name: "editor",
description:
"审阅报告草稿的准确性、结构与完整性。在 /workspace/reports/draft_*.md 写好后使用。",
systemPrompt: dedent`
你是一名资深情报编辑,负责**审阅**报告草稿,**不要**亲自改写报告。
...
返回简洁的审阅意见和具体、可操作的修改建议。
**不要**写入报告文件,只提供反馈。
`,
};
编辑只出意见,主 Agent 自己改。这个分离很关键:
- 审阅者的视角独立,不会陷入「自己写、自己觉得挺好」的盲区;
- 修改权仍在主 Agent,整体思路不会被编辑改跑偏;
- 职责单一,prompt 也更容易写清楚。
6.3 技能不是子 Agent
sources 之外还有一个容易混的概念:skills。
objectivec
skills/
├── web-research/SKILL.md
└── report-writer/SKILL.md
md
---
name: web-research
description: 结构化多来源联网调研,支持并行委派调研员子 Agent
---
# 联网调研技能
...
技能是给主 Agent 看的流程指南 ,不是可以 task 调用的 Agent。两份 SKILL.md 里都专门写了警告:
本技能是主 Agent 的流程指南,不是子 Agent。联网搜索请委派
researcher子 Agent,不要 将web-research作为 subagent_type 调用。
主 Agent 的 prompt 里也把合法值列死了:
md
**仅**以下 subagent_type 合法:researcher、analyst、editor、general-purpose。
技能解决「怎么做」,子 Agent 解决「谁来做」。 混用会导致主 Agent 试图 task("web-research"),然后报一个看不懂的错。
七、跑一遍:文件就是消息总线
这个项目最值得学的架构决策是:子 Agent 之间不靠对话历史传递信息,靠文件。
一轮完整调研的产物链:
7.1 真实产物
问题先落盘:
md
<!-- workspace/sources/question.txt -->
调研国家统计局公开的2023年省级地区生产总值(GDP)数据:
提取GDP总量前6名省份的具体数值及同比增速,
计算六省GDP总和、各省占全国GDP的比重,并按增速从高到低排名。
调研员把事实和来源写成结构化摘要:
md
<!-- workspace/sources/findings_gdp_2023.md(节选) -->
| 排名 | 省份 | 2023年GDP总量 | 同比增速 | 数据出处 |
|------|------|----------------|------------|-----------|
| 1 | 广东 | 135673.16 | 4.8% | 安徽产业网汇总(与公报一致) |
| 2 | 江苏 | 128222.20 | 5.8% | 同上 |
| 3 | 山东 | 92069.00 | 6.0% | 同上 |
| 4 | 浙江 | 82553.00 | 6.0% | 同上 |
| 5 | 四川 | 60132.90 | 6.0% | 同上 |
| 6 | 河南 | 59132.39 | 4.1% | 同上 |
分析师给出可复现的计算过程:
md
<!-- workspace/sources/analysis_gdp_provinces.md(节选) -->
### 1. 六省GDP总和计算
- 总和 = 135673.16 + 128222.20 + 92069.00 + 82553.00 + 60132.90 + 59132.39
= **557,782.65 亿元**
### 2. 各省占全国GDP比重(全国:1,260,582 亿元)
- 广东:135673.16 ÷ 1260582 × 100% = 10.76%
最终报告:
md
<!-- workspace/reports/report_gdp_2023_20240415.md(节选) -->
## 摘要
...六省GDP合计 557,782.65 亿元,占全国GDP总量(1,260,582 亿元)的 44.25%。
按同比增速从高到低排序,山东、浙江、四川并列第一(6.0%),
江苏次之(5.8%),广东第三(4.8%),河南第四(4.1%)。
7.2 为什么用文件做消息总线
| 好处 | 说明 |
|---|---|
| 上下文隔离 | 每个子 Agent 只读自己需要的文件,不被别人的对话淹没 |
| 可追溯 | 每一步都有落盘产物,错了能回看是哪一步 |
| 可恢复 | 进程挂了,文件还在,不必从头调研 |
| 可并行 | 三个调研员同时写不同的 findings_*.md,互不阻塞 |
| 可人工介入 | 不满意某份 findings,直接改文件再让主 Agent 继续 |
这也是多 Agent 系统里被反复验证的一条经验:
对话历史适合「同一个人继续想」,文件系统适合「不同的人协作」。 跨 Agent 传信息,优先走文件。
如果同时开了 LangSmith 的 tracing(前一篇讲过),每次 task 委派、每次 web_search、每次 write_file 都会出现在一条 trace 里,哪个调研员慢、哪一步空转,一目了然。
八、踩坑清单
8.1 拦截中间件的关键词大小写对不上
middleware-test.mjs 里判断的是大写:
js
if (text.includes("BLOCKED")) { ... }
而循环里的输入是:
js
for (const text of ["这句话包含Block 关键词"]) { ... }
Block ≠ BLOCKED,拦截根本不会触发 ,请求会照常发给模型。想看到短路效果,把输入改成包含 BLOCKED 的文本,或者把判断改成 toLowerCase()。
这类「逻辑写对了、数据对不上」的 bug,在中间件里特别隐蔽------日志一片正常,只是功能没生效。
8.2 deep-research-assistant 缺 AGENTS.md
agent.mjs 里配了:
js
memory: [path.join(projectDir, "AGENTS.md")]
但仓库里并没有 deep-research-assistant/AGENTS.md(只有 demo 的 workspace-memory/AGENTS.md)。跑之前先补一份项目说明,否则记忆源是空的。memory 配的是路径,不是「会自动创建的文件」。
8.3 cli.mjs 的流式循环是空的
js
for await (const [namespace, chunk] of await agent.stream(
{ messages: [new HumanMessage(query)] },
{ streamMode: "updates", subgraphs: true, recursionLimit }
)) {
// 空的
}
agent.stream 返回的 chunk 没有被消费和打印,所以终端里只能看到开头几行日志,看不到过程。要观察执行,最简单的做法是先打印出来:
js
for await (const [namespace, chunk] of await agent.stream(...)) {
console.log(namespace, JSON.stringify(chunk).slice(0, 200));
}
或者干脆用 agent.invoke() 拿最终结果。
8.4 skills 和 subagents 别混
subagents里的名字才是task的合法subagent_type;skills是 Markdown 指南,主 Agent 自己读,不参与委派。
在 prompt 里把两者写混,模型就会尝试调用一个不存在的子 Agent。
8.5 权限规则顺序
js
[
{ operations: ["write"], paths: ["/todo.md"], mode: "allow" },
{ operations: ["write"], paths: ["/**"], mode: "deny" },
]
allow 必须在 deny /** 前面。兜底规则放最前,会把所有写操作都关掉,包括你刚放行的那个。
8.6 别在 OneDrive 目录用 pnpm
两个子项目的 lockfile 都是 pnpm 的,但在 OneDrive 同步目录下,pnpm 的原子重命名容易报 EPERM。直接用 npm:
bash
npm install
8.7 virtualMode 下不要给模型传真实路径
Agent 的路径体系是虚拟的:/workspace/sources/...。在 prompt 里写 D:\... 或 C:\Users\...,模型要么找不到,要么把宿主机路径泄漏进报告。所有对模型可见的路径,都以 / 开头。
8.8 摘要阈值别照抄 demo
trigger: 8 / keep: 4 是为了几轮对话就能看到摘要效果。真实业务里这么低的阈值会频繁摘要,丢失细节。让模型 profile 自动推断,或者按 token 而不是消息条数触发。
8.9 多 Agent 要调大 recursionLimit
cli.mjs 里写的是 300:
js
const recursionLimit = 300;
主 Agent 规划、委派、子 Agent 执行、回传、再起草、再审阅,步数很容易超过默认的 25。跑多 Agent 系统时,递归上限是第一件要检查的配置。
8.10 环境变量清单
bash
# .env
OPENAI_API_KEY=sk-xxx
OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
MODEL_NAME=qwen-plus
# 调研助手的联网搜索
BOCHA_API_KEY=sk-xxx
# 可选:LangSmith 追踪
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=lsv2_pt_xxx
LANGCHAIN_PROJECT=deepagents-demo
createIntelligenceDeskAgent() 会检查 OPENAI_API_KEY,缺了直接抛错;web_search 在缺 BOCHA_API_KEY 时返回一段提示文本,而不是静默失败。
九、总结
把这篇串成一条线:
- DeepAgents 是 LangChain / LangGraph 之上的生产级封装。 它不替代底层,而是把「每个 Agent 都要做一遍」的基建(文件、记忆、摘要、规划、子 Agent、技能)封装成中间件和内置能力。
- 中间件是 Agent 的插件系统。
stateSchema加状态,before/after挂生命周期,wrapModelCall/wrapToolCall包住调用,canJumpTo+jumpTo实现短路。 - 文件系统中间件把虚拟路径映射到真实目录 ,
tools: []也能拥有ls/read_file/write_file/edit_file;权限规则给 Agent 划出精确的可写面。 - 记忆是文件,不是黑盒。
AGENTS.md存项目事实,preferences.md存用户偏好,分类写入,可读、可 diff、可人工接管。 - 摘要中间件解决上下文窗口。 到阈值就把旧对话压成摘要文件,保留最近几条继续聊,旧内容可追溯。
createDeepAgent用几个参数组装团队 :subagents决定谁能被委派,skills决定怎么做事,memory决定记住什么,backend决定文件落在哪。- 多 Agent 的核心是分工与边界。 调研员限次数、分析师只算数、编辑只审不改,主 Agent 只做编排------每个角色都别越界。
- 文件是最好的消息总线。 子 Agent 通过
findings_*.md协作,上下文隔离、过程可追溯、失败可恢复。
最后记一句:
Agent 的上限由模型决定,下限由 harness 决定。
模型会越来越强,但文件读写、上下文压缩、权限边界、子 Agent 调度这些工程问题不会自己消失。DeepAgents 的价值,就是让你把时间花在业务逻辑上,而不是一遍遍重造基础设施。
本文所有 demo 都在
ai/agent/deepagents下:
demo/------文件系统、记忆、摘要、中间件六个基础脚本,装好依赖后node src/...直接跑;deep-research-assistant/------完整多 Agent 调研项目,node src/cli.mjs "你的调研主题"启动。如果你也在做 Agent 落地,希望这篇帮你把「中间件 → 记忆 → 摘要 → 多 Agent 协作」这条链路理清楚。有问题欢迎评论区交流 👋