DeepAgents 从零上手:别再手搓 Harness,用中间件拼出一个调研团队

用 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",
        };
      }
    },
  },
});

两个要点:

  1. canJumpTo: ["end"] 是在声明这个中间件有跳转权限;
  2. 返回 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 协作图:

graph TD U[用户调研主题] --> O[主 Agent 编排] O -->|write_todos 规划| P[research_plan.md] O -->|task 委派| R1[researcher 调研员 1] O -->|task 委派| R2[researcher 调研员 2] O -->|task 委派| R3[researcher 调研员 3] R1 --> F1[findings_*.md] R2 --> F2[findings_*.md] R3 --> F3[findings_*.md] O -->|需要计算时| A[analyst 分析师] A --> AN[analysis_*.md] O -->|读 findings 起草| D[draft_*.md] D -->|task 委派| E[editor 编辑] E -->|审阅意见| O O -->|修订定稿| REPORT[report_*.md]

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 之间不靠对话历史传递信息,靠文件。

一轮完整调研的产物链:

graph LR Q[question.txt] --> P[research_plan.md] P --> F[findings_*.md] F --> A[analysis_*.md] A --> D[draft_*.md] D --> R[report_*.md]

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 时返回一段提示文本,而不是静默失败。


九、总结

把这篇串成一条线:

  1. DeepAgents 是 LangChain / LangGraph 之上的生产级封装。 它不替代底层,而是把「每个 Agent 都要做一遍」的基建(文件、记忆、摘要、规划、子 Agent、技能)封装成中间件和内置能力。
  2. 中间件是 Agent 的插件系统。 stateSchema 加状态,before/after 挂生命周期,wrapModelCall / wrapToolCall 包住调用,canJumpTo + jumpTo 实现短路。
  3. 文件系统中间件把虚拟路径映射到真实目录 ,tools: [] 也能拥有 ls/read_file/write_file/edit_file;权限规则给 Agent 划出精确的可写面。
  4. 记忆是文件,不是黑盒。 AGENTS.md 存项目事实,preferences.md 存用户偏好,分类写入,可读、可 diff、可人工接管。
  5. 摘要中间件解决上下文窗口。 到阈值就把旧对话压成摘要文件,保留最近几条继续聊,旧内容可追溯。
  6. createDeepAgent 用几个参数组装团队 :subagents 决定谁能被委派,skills 决定怎么做事,memory 决定记住什么,backend 决定文件落在哪。
  7. 多 Agent 的核心是分工与边界。 调研员限次数、分析师只算数、编辑只审不改,主 Agent 只做编排------每个角色都别越界。
  8. 文件是最好的消息总线。 子 Agent 通过 findings_*.md 协作,上下文隔离、过程可追溯、失败可恢复。

最后记一句:

Agent 的上限由模型决定,下限由 harness 决定。

模型会越来越强,但文件读写、上下文压缩、权限边界、子 Agent 调度这些工程问题不会自己消失。DeepAgents 的价值,就是让你把时间花在业务逻辑上,而不是一遍遍重造基础设施。


本文所有 demo 都在 ai/agent/deepagents 下:

  • demo/------文件系统、记忆、摘要、中间件六个基础脚本,装好依赖后 node src/... 直接跑;
  • deep-research-assistant/------完整多 Agent 调研项目,node src/cli.mjs "你的调研主题" 启动。

如果你也在做 Agent 落地,希望这篇帮你把「中间件 → 记忆 → 摘要 → 多 Agent 协作」这条链路理清楚。有问题欢迎评论区交流 👋

相关推荐
吴长建先生重名了37 分钟前
一次线上MySQL慢查询Bug的复现与调优全过程
javascript
LVZ2 小时前
AI Agent 缺的不是更强的模型,而是一个运行时
前端·javascript·后端
1-1=03 小时前
Vue 中 Class 与 Style 绑定
前端·javascript·vue.js
用户83134859306983 小时前
Vue3的v-if /v-show/v-else /v-else-if:区别、渲染原理、坑点与性能选型
前端·javascript·vue.js
mONESY3 小时前
LangSmith 全链路观测:从 Agent 调试到 RAG 量化评估
javascript
NoteDeep 深度笔记5 小时前
DOM 被改乱了怎么办?Notedeep 编辑器的 normalize 设计
前端·javascript·编辑器
翼帆7 小时前
我用 AI 复刻了 CodeTank,重温代码坦克
前端·javascript·开源·ai编程·游戏开发·codetank
黑土豆8 小时前
用 drawink 给业务页面加一层画板:从网页批注到无限板书
前端·javascript·github
Hilaku1 天前
Claude Code 过夜跑长任务实战:tmux、权限、验收,以及我为什么换到 ApexOne
前端·javascript·程序员