从 LangChain 到 DeepAgents:手把手拆解 createAgent、Middleware 与复杂 Agent

基于 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 背后帮你完成的事情:

  1. 接收初始的 messages;
  2. 把 systemPrompt 和工具定义交给模型;
  3. 调用模型;
  4. 检查模型返回的 AIMessage 是否包含 tool_calls;
  5. 如果有工具调用,执行对应工具并生成 ToolMessage;
  6. 把工具结果重新放回消息历史,再次调用模型;
  7. 当模型不再请求工具时结束。

可以用伪代码表示这个循环:

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 不仅可以修改模型请求,还可以包住每一次工具调用。

下面这个例子做四件事:

  1. 把时间工具直接注册到 Middleware;
  2. 记录工具名称和参数;
  3. 在工具结果后追加统一标记;
  4. 通过 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 权限规则的真实语义

当前版本的文件系统权限有几个关键规则:

  1. 只支持 read 和 write 两类操作;
  2. 规则按声明顺序检查;
  3. 第一个同时匹配"操作类型 + 路径 glob"的规则生效;
  4. 如果没有任何规则匹配,默认放行;
  5. 路径会先规范化,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"],
    },
  },
});

高风险工具不应该仅靠"提示词提醒模型谨慎"。更可靠的方式是:

  1. 把危险动作封装成明确工具;
  2. 在 interruptOn 中要求人工审批;
  3. 用 Checkpointer 保存中断前的图状态;
  4. 审批或修改参数后从原线程恢复。

人工中断不是日志功能,而是工作流的一部分。业务需要定义谁能审批、审批超时怎么办、拒绝后的替代路径是什么。

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 的生命周期由应用运行时统一创建;
  • 不要在源码中硬编码密钥、租户策略或生产路径。

十六、最后的完整心智模型

如果把整篇文章压缩成几句话:

  1. createAgent 封装的是一个"模型调用、工具执行、消息回流"的循环;
  2. Middleware 是插入这个循环的扩展点,可以读取和更新状态、改写模型请求、包装工具结果、做短路和路由;
  3. DeepAgents 是在 createAgent 与 LangGraph 之上的 Harness,预先组合了文件系统、子 Agent、摘要压缩等复杂能力;
  4. 复杂 Agent 的本质不是写一个更长的提示词,而是设计清楚状态、工具、权限、上下文和恢复边界;
  5. 生产环境最终需要的是可观测、可限制、可恢复、可审计的系统,而不是一个偶尔能跑通的任务 Demo。

可以记住这个分工:

text 复制代码
LangChain  给积木
LangGraph  给运行时
DeepAgents 给复杂 Agent 的装配台
Middleware 给横切扩展
Tool       给领域能力
Policy     给安全边界
测试       给迭代信心

从 createAgent 写起,能够帮助你看清 Agent 的基本运行原理;当文件、计划、上下文压缩和子 Agent 开始重复出现时,再引入 DeepAgents,才能既保持可控性,又避免重复造基础设施。

复杂 Agent 的门槛,往往不在于"让模型调一次工具",而在于让它在一个有边界、有预算、有记忆、有恢复能力的环境中持续完成任务。理解这些边界之后,再回头看 createAgent 和 Middleware,它们就不再是 API 清单,而会变成你设计生产级 Agent 的清晰切面。


参考资料

版本提示:本文示例以 langchain@1.6.6、@langchain/langgraph@1.7.4、deepagents@1.16.5 为基线。Agent 框架仍在快速演进,升级后请优先核对 Middleware Hook、权限配置和 Backend API 的类型定义。

相关推荐
大模型真好玩1 小时前
用 Seedance 2.5 Flash 实现1分钟AI短剧,满足孩子的超级英雄对战梦
人工智能·aigc·deepseek
冬夜Zis1 小时前
顺着作用域链和 outer 指针,一次性看懂闭包底层逻辑
javascript
Ceelog2 小时前
Mac 上怎么找出并安全清理旧的 node_modules?(实测 304 个占 66.3 GB)
javascript
小码哥0682 小时前
智慧物业系统源码定制:公告发布范围与住户阅读记录设计
前端·javascript·vue.js·物业管理·物业系统·物业软件
Highcharts.js4 小时前
Highcharts直方图使用指南:如何根据派生数据创建直方图?
javascript·信息可视化·直方图·highcharts·图表开发·创建图表·派生数据
ZhengEnCi5 小时前
Express 企业级项目结构怎么组织:五层骨架、单向依赖和一份能跑的边界检查脚本
javascript·node.js·express
泯泷5 小时前
Cloudflare 出手抢 Astro:前端框架之战,底层逻辑变了
前端·javascript·前端框架
cc.ChenLy7 小时前
无法修改 el-dialog 样式原因及解决办法
javascript·vue.js·elementui
1-1=08 小时前
Vue 脚手架
前端·javascript·vue.js