自定义 Deep Agents

为什么需要自定义

默认的 Deep Agent 能写代码、管文件，但你的业务远不止于此

比喻只是为了帮你理解——实际上，createDeepAgent 只是一个工厂函数，它根据你传入的配置对象组装出一个 LangGraph graph。所谓"开关"就是对象上的各个字段，不存在真的面板。

全景配置一览

createDeepAgent 提供的配置项多达十余个，但核心只有五个

先看一眼完整的配置参数，心里有个地图。后续每一节深入一个配置项。

const agent = createDeepAgent({
  // 核心五件套
  model?: string | BaseLanguageModel,     // 1. 模型 —— 字符串 "provider:model" 或模型实例
  tools?: TTools | StructuredTool[],      // 2. 自定义工具 —— Agent 通过 LLM 自主选择调用
  systemPrompt?: string | SystemMessage,  // 3. 系统提示 —— 叠加在 SDK 默认提示之上
  middleware?: TMiddleware,                // 4. 中间件 —— 拦截模型/工具调用的钩子
  subagents?: TSubagents,                 // 5. 子代理 —— 隔离上下文的任务委派

  // 文件与存储
  backend?: AnyBackendProtocol,           // 虚拟文件系统后端（默认 StateBackend）
  store?: BaseStore,                      // 跨线程持久存储（StoreBackend 需要此项）
  checkpointer?: BaseCheckpointSaver,     // 检查点存储器（人在回路中功能必需）

  // 交互与记忆
  interruptOn?: Record<string, boolean>,  // 人在回路中断规则 —— 指定哪些工具需审批
  memory?: string[],                      // 记忆文件路径 —— 每次调用都加载
  skills?: string[],                      // 技能文件路径 —— 按需加载，节省 token

  // 高级选项
  name?: string,                          // 代理名称
  permissions?: FilesystemPermission[],   // 文件系统权限 —— 控制读写范围
  responseFormat?: TResponse,             // 结构化输出 schema —— 返回 JSON 而非自由文本
});

选择模型

三种方式传入模型：字符串、initChatModel、模型类实例

最简单的方式是传入 "provider:model" 格式的字符串。一行代码切换模型提供商。

// 方式一：字符串（最简） —— SDK 自动初始化模型，适合快速验证
const agent = createDeepAgent({ model: "openai:gpt-5.4" });
const agent = createDeepAgent({ model: "anthropic:claude-sonnet-4-6" });
const agent = createDeepAgent({ model: "google-genai:gemini-3.1-pro-preview" });

// 方式二：initChatModel（需要调参） —— 通过 provider 字段指定提供商
import { initChatModel } from "langchain";
const model = await initChatModel("openai:gpt-5.5", { temperature: 0 });
const agent = createDeepAgent({ model });

// 方式三：模型类实例（完全控制） —— 可设置 apiKey、temperature 等所有参数
import { ChatOpenAI } from "@langchain/openai";
const agent = createDeepAgent({
  model: new ChatOpenAI({
    model: "gpt-5.4",
    apiKey: "your-api-key",     // 也可从环境变量自动读取
    temperature: 0,              // 0 = 确定性输出，1 = 更有创意
  }),
});

支持的提供商

Deep Agents 支持主流 LLM 提供商，用统一的接口接入

# 安装示例（以 OpenAI 为例）
$ npm install @langchain/openai deepagents

# Anthropic
$ npm install @langchain/anthropic deepagents

自定义工具

用 langchain 的 tool 函数定义工具，让代理拥有新能力

Deep Agent 已经内置了文件管理和规划工具。当你需要搜索网页、查询天气、调用内部 API 时，就需要自定义工具。

import { tool } from "langchain";
import { createDeepAgent } from "deepagents";
import { z } from "zod";

// 定义一个网络搜索工具 —— tool() 的第一个参数是执行函数，第二个是元数据
const internetSearch = tool(
  async ({ query, maxResults = 5 }) => {
    // 动态导入 TavilySearch，避免在不需要搜索时加载该模块
    const { TavilySearch } = await import("@langchain/tavily");
    const search = new TavilySearch({
      maxResults,                                 // 返回结果数量
      tavilyApiKey: process.env.TAVILY_API_KEY,   // 密钥从环境变量读取
    });
    return await search._call({ query });          // 执行搜索，返回结果给 Agent
  },
  {
    name: "internet_search",                           // Agent 调用时的名称
    description: "运行网络搜索，获取最新信息",            // LLM 据此判断何时调用
    schema: z.object({
      query: z.string().describe("搜索查询关键词"),     // .describe() 帮助 LLM 理解参数用途
      maxResults: z.number().optional().default(5),
    }),
  }
);

// 注册到代理 —— Agent 会根据任务需要自主决定是否调用搜索工具
const agent = createDeepAgent({
  model: "openai:gpt-5.4",
  tools: [internetSearch],
});

系统提示

注入业务专有指令，让代理行为符合你的期望

Deep Agent 自带内置系统提示（规划、文件管理指导等）。你的自定义提示会叠加在内置提示之上，而不是替换它。

import { createDeepAgent } from "deepagents";

const researchInstructions =
  "你是一位专业研究员。" +
  "你的工作是进行深入的研究，然后撰写精炼的报告。" +
  "请始终引用来源，区分事实与观点。";

const agent = createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  systemPrompt: researchInstructions,
});

提示组装机制

系统提示由四个命名部分按固定顺序拼接而成

Deep Agent 从最多四个部分构建最终的系统提示。这确保了你的指令始终优先，而模型特定优化始终在最后。

// 典型场景：使用 Anthropic 模型 + 自定义提示
const agent = createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  systemPrompt: "你是 ACME Corp. 的客户支持代理。",
});
// 最终结果 = USER + BASE + SUFFIX
// = "你是 ACME Corp. 的客户支持代理。"
// + "\n\n"
// + SDK 默认代理提示（BASE）
// + "\n\n"
// + Claude 特定优化指导（SUFFIX）

内置中间件

Deep Agent 开箱即用的中间件，覆盖常见需求

中间件是横切关注点的解决方案——不侵入业务逻辑，却能拦截和增强每一步操作。

自定义中间件

用 createMiddleware 拦截工具调用，实现日志、监控等横切逻辑

自定义中间件的核心是 wrapToolCall 钩子——在工具执行前后插入你的逻辑。

import { tool, createMiddleware } from "langchain";
import { createDeepAgent } from "deepagents";
import { z } from "zod";

// 一个天气工具
const getWeather = tool(
  ({ city }: { city: string }) => `${city} 的天气是晴天。`,
  {
    name: "get_weather",
    description: "获取某个城市的天气。",
    schema: z.object({ city: z.string() }),
  }
);

// 自定义中间件：在每次工具调用前后记录日志
const logToolCallsMiddleware = createMiddleware({
  name: "LogToolCallsMiddleware",
  // wrapToolCall 钩子：拦截每次工具调用，可在执行前后插入自定义逻辑
  wrapToolCall: async (request, handler) => {
    const toolName = request.toolCall.name;
    console.log(`[调用] ${toolName}`, request.toolCall.args);  // 记录调用前的参数
    const result = await handler(request);                      // 调用 handler 执行原始工具
    console.log(`[完成] ${toolName}`);                          // 记录调用完成
    return result;                                               // 将结果返回给 Agent
  },
});

// 中间件按数组顺序依次执行，可叠加多个
const agent = createDeepAgent({
  model: "openai:gpt-5.4",
  tools: [getWeather],
  middleware: [logToolCallsMiddleware],
});

const customMiddleware = createMiddleware({
  name: "CustomMiddleware",
  beforeAgent: async (state) => {
    return { x: (state.x ?? 0) + 1 }; // 更新图状态
  },
});

let x = 1;
const customMiddlewareBad = createMiddleware({
  name: "CustomMiddleware",
  beforeAgent: async () => {
    x += 1; // 修改变量会导致竞态条件！
  },
});

代码解释器

添加 eval 工具，让代理在沙箱中执行 JavaScript

解释器为代理提供了一个 QuickJS 运行时。当代理需要批量处理数据、组合工具调用、在代码中处理错误时，解释器非常有用。

import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";
// 注意：npm 包 @langchain/quickjs 的部分版本实际导出的是 createQuickJSMiddleware
// （此时工具名为 js_eval 而非 eval）。若上述 import 报错，请改用：
//   import { createQuickJSMiddleware } from "@langchain/quickjs";
//   middleware: [createQuickJSMiddleware()]
// 两者是同一能力的不同封装层，详见官方文档。

// 添加 eval 工具：Agent 可以在 QuickJS 沙箱中执行 JavaScript
// 适用于批量处理数据、组合工具调用、复杂错误处理等场景
const agent = createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  middleware: [createCodeInterpreterMiddleware()],  // 自动为 Agent 添加 eval 工具
});

子代理

隔离细节工作，避免主代理上下文爆炸

当任务变得复杂时，主代理的上下文会被大量中间结果塞满。子代理帮你把详细工作外包出去，主代理只看到最终结果。

import { tool } from "langchain";
import { createDeepAgent, type SubAgent } from "deepagents";
import { z } from "zod";

// 研究子代理——拥有独立上下文、工具和提示，不污染主代理
const researchSubagent: SubAgent = {
  name: "research-agent",                               // 主代理通过 task 工具按名称委派
  description: "深入研究特定问题的子代理",                  // 帮助主代理判断何时委派
  systemPrompt: "你是一个优秀的研究员，请引用来源。",       // 子代理的专属提示词
  tools: [internetSearch],                               // 可选：子代理专用工具（不继承主代理工具）
  model: "anthropic:claude-sonnet-4-6",                  // 可选：覆盖主代理的模型
};

const agent = createDeepAgent({
  model: "openai:gpt-5.4",
  subagents: [researchSubagent],
});

后端选择

虚拟文件系统后端决定了代理的文件存储和访问方式

Deep Agent 的工具使用虚拟文件系统。选择不同的后端，文件存储的位置和生命周期完全不同。

// StateBackend（默认，无需显式配置）—— 文件存储在 LangGraph 状态中，线程级持久化
const agent = createDeepAgent();

// StoreBackend（跨线程持久化）—— 数据在不同对话间共享
import { StoreBackend } from "deepagents";
import { InMemoryStore } from "@langchain/langgraph";
const store = new InMemoryStore();    // 生产环境应使用持久化存储
const agent = createDeepAgent({
  backend: new StoreBackend({ namespace: (rt) => [rt.serverInfo.user.identity] }),  // 按用户隔离
  store,                              // StoreBackend 需要传入 store 实例
});

// CompositeBackend（混合）—— 不同路径路由到不同后端
import { CompositeBackend, StateBackend } from "deepagents";
const agent = createDeepAgent({
  backend: new CompositeBackend(new StateBackend(), {  // 默认路径用 StateBackend
    "/memories/": new StoreBackend({ namespace: () => ["memories"] }),  // /memories/ 路径用 StoreBackend
  }),
  store,
});

// LocalShellBackend（本地 shell 执行——高危！）—— 直接在宿主机上执行命令
import { LocalShellBackend } from "deepagents";
const backend = new LocalShellBackend({ workingDirectory: "." });  // 工作目录设为当前目录
const agent = createDeepAgent({
  model: "google-genai:gemini-3.1-pro-preview",
  backend,
});

人在回路中

为敏感操作配置人工审批，防止代理越权执行

有些操作（删除文件、发送邮件）需要人工确认后才能执行。通过 interruptOn 配置审批规则。

import { tool } from "langchain";
import { createDeepAgent } from "deepagents";
import { MemorySaver } from "@langchain/langgraph";
import { z } from "zod";

const removeFile = tool(
  async ({ path }: { path: string }) => `Deleted ${path}`,
  {
    name: "remove_file",
    description: "删除文件",
    schema: z.object({ path: z.string() }),
  }
);

const notifyEmail = tool(
  async ({ to, subject, body }) => `Sent email to ${to}`,
  {
    name: "notify_email",
    description: "发送邮件",
    schema: z.object({
      to: z.string(),
      subject: z.string(),
      body: z.string(),
    }),
  }
);

const checkpointer = new MemorySaver();  // 内存检查点存储器，生产环境用数据库

const agent = createDeepAgent({
  model: "openai:gpt-5.4",
  tools: [removeFile, notifyEmail],
  interruptOn: {
    remove_file: true,  // true = 每次调用前暂停，支持审批/拒绝/编辑
    notify_email: { allowedDecisions: ["approve", "reject"] }, // 只允许批准或拒绝，不允许编辑参数
  },
  checkpointer,  // 必需！暂停/恢复依赖检查点，没有它 interruptOn 会被忽略
});

技能系统

用 SKILL.md 文件为代理提供专业知识和操作指南

技能（Skills）不同于工具。工具是低级功能（搜索、读写文件），技能包含完整的任务说明、参考信息和模板。技能文件只在代理判断有用时才加载——渐进式披露，节省 token。

import { createDeepAgent, StateBackend, type FileData } from "deepagents";
import { MemorySaver } from "@langchain/langgraph";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

const checkpointer = new MemorySaver();
const backend = new StateBackend();

// 从 GitHub 获取技能文件
const skillUrl = "https://raw.githubusercontent.com/langchain-ai/deepagentsjs/main/examples/skills/langgraph-docs/SKILL.md";
const skillContent = await (await fetch(skillUrl)).text();

const agent = createDeepAgent({
  model: "openai:gpt-5.4",
  backend,
  checkpointer,
  skills: ["/skills/"],  // 技能源路径，Agent 会按需加载该目录下的 SKILL.md
  middleware: [createCodeInterpreterMiddleware({ skillsBackend: backend })],
});

// 首次调用时通过 files 参数将技能文件写入后端
const result = await agent.invoke({
  messages: [{ role: "user", content: "什么是 LangGraph？" }],
  files: { "/skills/langgraph-docs/SKILL.md": createFileData(skillContent) },  // 技能内容
}, { configurable: { thread_id: `thread-${Date.now()}` } });  // thread_id 用于检查点隔离

记忆系统

用 AGENTS.md 文件为代理提供跨会话的持久上下文

记忆（Memory）使用 AGENTS.md 文件为代理提供额外的上下文信息。不同于技能的渐进式加载，记忆文件在每次调用时都会被读取。

import { createDeepAgent, type FileData } from "deepagents";
import { MemorySaver } from "@langchain/langgraph";

const checkpointer = new MemorySaver();

// 获取记忆文件
const agentsMd = await (await fetch("https://.../AGENTS.md")).text();

const agent = createDeepAgent({
  model: "openai:gpt-5.4",
  memory: ["/AGENTS.md"],   // 记忆文件路径，每次调用都会加载（与技能的按需加载不同）
  checkpointer,
});

// 通过 files 参数传入记忆文件内容，之后每次调用都会自动读取
const result = await agent.invoke({
  messages: [{ role: "user", content: "你的记忆里有什么？" }],
  files: { "/AGENTS.md": createFileData(agentsMd) },  // 首次调用时写入记忆文件
}, { configurable: { thread_id: "12345" } });          // 固定 thread_id 以复用检查点

结构化输出

让代理返回符合 Schema 的结构化数据，而非自由文本

通过 responseFormat 参数，你可以指定代理输出的结构。模型生成的数据会被捕获、验证，放在 structuredResponse 字段中返回。

import { createDeepAgent } from "deepagents";
import { z } from "zod";

// 定义输出结构 —— 用 Zod schema 约束 Agent 返回的字段和类型
const weatherReportSchema = z.object({
  location: z.string().describe("天气报告的地点"),
  temperature: z.number().describe("当前温度（摄氏度）"),
  condition: z.string().describe("当前天气状况"),
  humidity: z.number().describe("湿度百分比"),
  forecast: z.string().describe("未来24小时预报"),
});

// 设置 responseFormat 后，Agent 会返回结构化 JSON 而非自由文本
const agent = createDeepAgent({
  responseFormat: weatherReportSchema,  // schema 中的 .describe() 帮助模型理解字段含义
  tools: [internetSearch],
});

const result = await agent.invoke({
  messages: [{ role: "user", content: "旧金山天气怎么样？" }],
});

// 结构化结果在 structuredResponse 字段中，类型安全可直接使用
console.log(result.structuredResponse);
// { location: "San Francisco", temperature: 18.3,
//   condition: "Sunny", humidity: 48,
//   forecast: "Clear skies with mild temperatures..." }

沙箱环境

在隔离环境中运行代理代码，不触碰本地文件系统

沙箱是一种特殊的后端——代理在隔离环境中运行，拥有自己的文件系统和 shell。你希望代理能写文件、跑命令，但不想让它改你本地机器时，用沙箱。

import { createDeepAgent } from "deepagents";
import { ChatAnthropic } from "@langchain/anthropic";
import { DenoSandbox, createDenoSandboxFactoryFromSandbox } from "@langchain/deno";

// 创建并初始化沙箱 —— 隔离环境，Agent 的代码执行不影响本地机器
const sandbox = await DenoSandbox.create({
  memoryMb: 1024,       // 内存限制：1GB
  lifetime: "10m",      // 存活时间：10 分钟后自动销毁
});

try {
  const agent = createDeepAgent({
    model: new ChatAnthropic({ model: "claude-opus-4-6" }),
    systemPrompt: "You are a JavaScript coding assistant.",
    backend: createDenoSandboxFactoryFromSandbox(sandbox),    // 用沙箱构造后端工厂，Agent 在其中执行代码
  });

  const result = await agent.invoke({
    messages: [{
      role: "user",
      content: "创建一个简单的 HTTP 服务器并用 curl 测试",
    }],
  });
} finally {
  await sandbox.close(); // 务必关闭沙箱释放资源！放在 finally 块中确保异常时也能清理
}

动手练习

构建一个带搜索、审批和子代理的研究助手

现在轮到你了。综合运用本章所学，构建一个研究助手：

需求：
1. 使用 Anthropic 的 claude-sonnet-4-6 模型
2. 拥有网络搜索能力（使用 TavilySearch）
3. 系统提示：专注于技术研究，引用来源
4. 拥有一个"写作子代理"，负责将研究结果整理成报告
5. 发送邮件的操作需要人工审批
6. 使用 StateBackend 作为文件系统

本章回顾

你已经掌握了 Deep Agent 的全部配置维度

延伸阅读