Skip to main content
createDeepAgent 具有以下配置选项:
const agent = createDeepAgent({
  backend?: AnyBackendProtocol | (config: __type) => AnyBackendProtocol,
  checkpointer?: boolean | BaseCheckpointSaver<number>,
  contextSchema?: ContextSchema,
  interruptOn?: Record<string, boolean | __type>,
  memory?: string[],
  middleware?: TMiddleware,
  model?: string | BaseLanguageModel<any, BaseLanguageModelCallOptions>,
  name?: string,
  responseFormat?: TResponse,
  skills?: string[],
  store?: BaseStore,
  subagents?: TSubagents,
  systemPrompt?: string | SystemMessage<MessageStructure<MessageToolSet>>,
  tools?: TTools | StructuredTool<ToolInputSchemaBase, any, any, any, unknown>[]
});
有关完整参数列表,请参阅 createDeepAgent API 参考。

模型

传递一个 provider:model 格式的 model 字符串,或一个已初始化的模型实例。有关所有提供商,请参阅支持的模型;有关经过测试的推荐模型,请参阅推荐模型
使用 provider:model 格式(例如 openai:gpt-5.4)可以快速切换模型。
👉 阅读 OpenAI 聊天模型集成文档
npm install @langchain/openai deepagents
import { createDeepAgent } from "deepagents";

process.env.OPENAI_API_KEY = "your-api-key";

const agent = createDeepAgent({ model: "gpt-5.4" });
// 这会使用默认参数为指定模型调用 initChatModel
// 要使用特定的模型参数,请直接使用 initChatModel

连接弹性

LangChain 聊天模型会自动使用指数退避策略重试失败的 API 请求。默认情况下,模型会针对网络错误、速率限制 (429) 和服务器错误 (5xx) 重试最多 6 次。客户端错误(如 401 未授权或 404 未找到)不会重试。 您可以在创建模型时调整 maxRetries 参数,以根据您的环境调整此行为:
import { ChatAnthropic } from "@langchain/anthropic";
import { createDeepAgent } from "deepagents";

const agent = createDeepAgent({
  model: new ChatAnthropic({
    model: "claude-sonnet-4-6",
    maxRetries: 10, // 对于不可靠的网络增加此值(默认:6)
    timeout: 120_000, // 对于慢速连接增加超时时间
  }),
});
对于在不可靠网络上运行的长时间代理任务,考虑将 max_retries 增加到 10-15,并将其与检查点配对使用,以便在失败时保留进度。

工具

除了用于规划、文件管理和子代理生成的内置工具之外,您还可以提供自定义工具:
import { tool } from "langchain";
import { TavilySearch } from "@langchain/tavily";
import { createDeepAgent } from "deepagents";
import { z } from "zod";

const internetSearch = tool(
  async ({
    query,
    maxResults = 5,
    topic = "general",
    includeRawContent = false,
  }: {
    query: string;
    maxResults?: number;
    topic?: "general" | "news" | "finance";
    includeRawContent?: boolean;
  }) => {
    const tavilySearch = new TavilySearch({
      maxResults,
      tavilyApiKey: process.env.TAVILY_API_KEY,
      includeRawContent,
      topic,
    });
    return await tavilySearch._call({ query });
  },
  {
    name: "internet_search",
    description: "运行网络搜索",
    schema: z.object({
      query: z.string().describe("搜索查询"),
      maxResults: z.number().optional().default(5),
      topic: z
        .enum(["general", "news", "finance"])
        .optional()
        .default("general"),
      includeRawContent: z.boolean().optional().default(false),
    }),
  },
);

const agent = createDeepAgent({
  tools: [internetSearch],
});

系统提示

深度代理自带一个内置系统提示。深度代理的价值来自于 SDK 在模型之上提供的编排层——规划、虚拟文件系统工具和子代理——模型需要知道这些工具的存在以及何时使用它们。内置提示教会代理如何使用该脚手架,这样您就不必为每个项目重新推导它;通过配置文件或您自己的 system_prompt= 来调整它,而不是逐字复制。 当中间件添加特殊工具(如文件系统工具)时,它会将它们附加到系统提示中。 每个深度代理还应包含一个针对其特定用例的自定义系统提示:
import { createDeepAgent } from "deepagents";

const researchInstructions =
  `You are an expert researcher. ` +
  `Your job is to conduct thorough research, and then ` +
  `write a polished report.`;

const agent = createDeepAgent({
  systemPrompt: researchInstructions,
});

提示组装

深度代理从最多四个命名部分构建系统提示,以便调用者提供的指令、SDK 的内置代理指导以及任何特定于模型的配置文件覆盖可以共存,并具有可预测的优先级。如果没有这种分层,为 Claude(例如)调整的配置文件后缀可能会根据调用顺序覆盖或被您的 system_prompt= 参数覆盖;命名槽使顺序明确且稳定。 在实践中,大多数调用者只遇到两个槽:USER(您的 system_prompt=)和 BASE(SDK 默认值)。选择具有内置配置文件的模型——目前是 Anthropic 或 OpenAI——会添加一个 SUFFIX。完整的四部分组装主要在您编写自定义 HarnessProfile 或调试配置文件文本出现位置时相关。 四个命名部分(每个都可能缺失):
名称来源备注
USERcreate_deep_agentsystem_prompt= 参数strSystemMessage;未设置时省略。
BASESDK 默认值 (BASE_AGENT_PROMPT)始终存在,除非被配置文件的 CUSTOM 替换。
CUSTOMHarnessProfile.base_system_prompt当匹配的配置文件设置它时,完全替换 BASE
SUFFIXHarnessProfile.system_prompt_suffix当匹配的配置文件设置它时,最后附加。
顺序始终是 USER -> (BASECUSTOM) -> SUFFIX,由空行 (\n\n) 连接。由此得出两个不变式:
  1. USER 始终在最前面。 调用者的文本优先于任何 SDK 或配置文件内容,因此无论选择哪个模型,角色/指令都具有优先权。
  2. SUFFIX 始终在最后。 配置文件后缀最接近对话历史,模型调整指导在此处最可靠地生效。
组装形式(✓ = 字段已设置,- = 字段未设置):
system_prompt=配置文件 base_system_prompt (CUSTOM)配置文件 system_prompt_suffix (SUFFIX)最终组装的系统提示
None--BASE
None-BASE + SUFFIX
None-CUSTOM
NoneCUSTOM + SUFFIX
str--USER + BASE
str-USER + BASE + SUFFIX
str-USER + CUSTOM
strUSER + CUSTOM + SUFFIX
实际示例——内置配置文件(Anthropic、OpenAI)仅提供 system_prompt_suffix,因此典型调用落在 str + - + 行:
agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    system_prompt="You are a customer-support agent for ACME Corp.",
)
# 最终 = USER + BASE + SUFFIX
#       = "You are a customer-support agent for ACME Corp."
#         + "\n\n"
#         + BASE_AGENT_PROMPT
#         + "\n\n"
#         + <Claude 特定指导>
传递 SystemMessage(而不是字符串)会触发不同的连接路径:右侧组装(BASECUSTOM 加上任何 SUFFIX)作为额外的文本内容块附加到消息现有的 content_blocks 上。相同的逻辑顺序适用(调用者块在前),并且调用者块上的任何 cache_control 标记都会保留——这对于放置显式的 Anthropic 提示缓存断点很有用。
相同的覆盖规则适用于声明式子代理——每个子代理根据其自身模型重新运行配置文件解析,然后将解析后的配置文件的 base_system_prompt / system_prompt_suffix 应用于其编写的 system_prompt。子代理的 system_prompt 扮演 BASE 角色;CUSTOMSUFFIX 来自与子代理模型匹配的配置文件(可能与主代理的配置文件不同)。
spec["system_prompt"]配置文件 base_system_prompt (CUSTOM)配置文件 system_prompt_suffix (SUFFIX)最终子代理系统提示
已编写--已编写
已编写-已编写 + SUFFIX
已编写-CUSTOM
已编写CUSTOM + SUFFIX
子代理没有 USER 部分——规范中编写的 system_prompt 是最接近的类比,并保留在 BASE 槽中。仅提供 system_prompt_suffix 的配置文件(内置 Anthropic / OpenAI 配置文件的常见情况)只是附加到子代理作者编写的任何内容;设置 base_system_prompt 的配置文件将完全替换编写的提示,因此请谨慎使用该字段。
自动添加的通用子代理遵循相同的覆盖规则,但多了一层:GP 基础提示解析为 general_purpose_subagent.system_prompt(如果已设置)-> HarnessProfile.base_system_prompt(如果已设置)-> SDK GP 默认值。配置文件后缀无论如何都会叠加在上面。两个覆盖字段都可以携带基础提示替换,但它们不可互换。general_purpose_subagent.system_prompt 是 GP 特定的配置;base_system_prompt 是一个全局覆盖,主要针对主代理。当两者都设置时,GP 特定的意图对 GP 子代理生效,因此同时调整这两个字段的用户永远不会看到他们的 GP 覆盖被静默丢弃:
register_harness_profile(
    "anthropic",
    HarnessProfile(
        base_system_prompt="You are ACME's support orchestrator.",  # 主代理
        general_purpose_subagent=GeneralPurposeSubagentProfile(
            system_prompt="You are a research subagent. Cite sources.",  # GP 子代理
        ),
        system_prompt_suffix="Always think step by step.",
    ),
)
堆栈最终系统提示
主代理"You are ACME's support orchestrator." + SUFFIX
GP 子代理"You are a research subagent. Cite sources." + SUFFIX
如果 general_purpose_subagent.system_prompt 未设置,GP 子代理将回退到 base_system_prompt(如果已设置),最后回退到 SDK GP 默认值。

中间件

默认情况下,深度代理可以访问以下中间件 如果您使用记忆、技能或Human in the Loop,则还包括以下中间件:
  • MemoryMiddleware:当提供 memory 参数时,跨会话持久化和检索对话上下文
  • SkillsMiddleware:当提供 skills 参数时启用自定义技能
  • HumanInTheLoopMiddleware:当提供 interruptOn 参数时,在指定点暂停以等待人类批准或输入

预构建中间件

LangChain 提供了额外的预构建中间件,允许您添加各种功能,例如重试、回退或 PII 检测。有关更多信息,请参阅预构建中间件 deepagents 包还为相同的工作流提供了 createSummarizationMiddleware。有关更多详细信息,请参阅摘要

特定于提供商的中间件

有关针对特定 LLM 提供商优化的特定于提供商的中间件,请参阅官方集成社区集成

自定义中间件

您可以提供额外的中间件来扩展功能、添加工具或实现自定义钩子:
import { tool, createMiddleware } from "langchain";
import { createDeepAgent } from "deepagents";
import * as z from "zod";

const getWeather = tool(
  ({ city }: { city: string }) => {
    return `The weather in ${city} is sunny.`;
  },
  {
    name: "get_weather",
    description: "获取城市的天气。",
    schema: z.object({
      city: z.string(),
    }),
  },
);

let callCount = 0;

const logToolCallsMiddleware = createMiddleware({
  name: "LogToolCallsMiddleware",
  wrapToolCall: async (request, handler) => {
    // 拦截并记录每个工具调用 - 演示横切关注点
    callCount += 1;
    const toolName = request.toolCall.name;

    console.log(`[Middleware] Tool call #${callCount}: ${toolName}`);
    console.log(
      `[Middleware] Arguments: ${JSON.stringify(request.toolCall.args)}`,
    );

    // 执行工具调用
    const result = await handler(request);

    // 记录结果
    console.log(`[Middleware] Tool call #${callCount} completed`);

    return result;
  },
});

const agent = await createDeepAgent({
  model: "google_genai:gemini-3.1-pro-preview",
  tools: [getWeather] as any,
  middleware: [logToolCallsMiddleware] as any,
});
初始化后不要修改属性如果您需要在钩子调用之间跟踪值(例如计数器或累积数据),请使用图状态。 图状态按设计限定在线程范围内,因此更新在并发下是安全的。请这样做:
const customMiddleware = createMiddleware({
  name: "CustomMiddleware",
  beforeAgent: async (state) => {
    return { x: (state.x ?? 0) + 1 }; // 改为更新图状态
  },
});
不要这样做:
let x = 1;

const customMiddleware = createMiddleware({
  name: "CustomMiddleware",
  beforeAgent: async () => {
    x += 1; // 修改会导致竞态条件
  },
});
就地修改,例如在 beforeAgent 中修改 state.x、在 beforeAgent 中修改共享变量或在钩子中更改其他共享值,可能导致细微的错误和竞态条件,因为许多操作并发运行(子代理、并行工具和不同线程上的并行调用)。有关使用自定义属性扩展状态的完整详细信息,请参阅自定义中间件 - 自定义状态模式。 如果您必须在自定义中间件中使用修改,请考虑当子代理、并行工具或并发代理调用同时运行时会发生什么。

子代理

要隔离详细工作并避免上下文膨胀,请使用子代理:
import { tool } from "langchain";
import { TavilySearch } from "@langchain/tavily";
import { createDeepAgent, type SubAgent } from "deepagents";
import { z } from "zod";

const internetSearch = tool(
  async ({
    query,
    maxResults = 5,
    topic = "general",
    includeRawContent = false,
  }: {
    query: string;
    maxResults?: number;
    topic?: "general" | "news" | "finance";
    includeRawContent?: boolean;
  }) => {
    const tavilySearch = new TavilySearch({
      maxResults,
      tavilyApiKey: process.env.TAVILY_API_KEY,
      includeRawContent,
      topic,
    });
    return await tavilySearch._call({ query });
  },
  {
    name: "internet_search",
    description: "运行网络搜索",
    schema: z.object({
      query: z.string().describe("搜索查询"),
      maxResults: z.number().optional().default(5),
      topic: z
        .enum(["general", "news", "finance"])
        .optional()
        .default("general"),
      includeRawContent: z.boolean().optional().default(false),
    }),
  },
);

const researchSubagent: SubAgent = {
  name: "research-agent",
  description: "用于更深入地研究问题",
  systemPrompt: "你是一位出色的研究员",
  tools: [internetSearch],
  model: "openai:gpt-5.4",  // 可选覆盖,默认使用主代理模型
};
const subagents = [researchSubagent];

const agent = createDeepAgent({
  model: "claude-sonnet-4-6",
  subagents,
});
有关更多信息,请参阅子代理

后端

深度代理的工具可以利用虚拟文件系统来存储、访问和编辑文件。默认情况下,深度代理使用 StateBackend 如果您使用技能记忆,则必须在创建代理之前将预期的技能或记忆文件添加到后端。
存储在 langgraph 状态中的临时文件系统后端。此文件系统仅在_单个线程_内持久化。
import { createDeepAgent, StateBackend } from "deepagents";

// 默认情况下,我们提供一个 StateBackend
const agent = createDeepAgent();

// 在底层,它看起来像这样
const agent2 = createDeepAgent({
  backend: new StateBackend(),
});
有关更多信息,请参阅后端

沙箱

沙箱是专门的后端,在隔离环境中运行代理代码,具有自己的文件系统和用于 shell 命令的 execute 工具。 当您希望深度代理写入文件、安装依赖项和运行命令而不更改本地计算机上的任何内容时,请使用沙箱后端。 您可以通过在创建深度代理时将沙箱后端传递给 backend 来配置沙箱:
import { createDeepAgent } from "deepagents";
import { ChatAnthropic } from "@langchain/anthropic";
import { DenoSandbox } from "@langchain/deno";

// 创建并初始化沙箱
const sandbox = await DenoSandbox.create({
  memoryMb: 1024,
  lifetime: "10m",
});

try {
  const agent = createDeepAgent({
    model: new ChatAnthropic({ model: "claude-opus-4-6" }),
    systemPrompt: "You are a JavaScript coding assistant with sandbox access.",
    backend: sandbox,
  });

  const result = await agent.invoke({
    messages: [
      {
        role: "user",
        content:
          "Create a simple HTTP server using Deno.serve and test it with curl",
      },
    ],
  });
} finally {
  await sandbox.close();
}
有关更多信息,请参阅沙箱

Human in the Loop

某些工具操作可能很敏感,需要在执行前获得人类批准。 您可以为每个工具配置批准:
import { tool } from "langchain";
import { createDeepAgent } from "deepagents";
import { MemorySaver } from "@langchain/langgraph";
import { z } from "zod";

const deleteFile = tool(
  async ({ path }: { path: string }) => {
    return `Deleted ${path}`;
  },
  {
    name: "delete_file",
    description: "从文件系统中删除一个文件。",
    schema: z.object({
      path: z.string(),
    }),
  },
);

const readFile = tool(
  async ({ path }: { path: string }) => {
    return `Contents of ${path}`;
  },
  {
    name: "read_file",
    description: "从文件系统中读取一个文件。",
    schema: z.object({
      path: z.string(),
    }),
  },
);

const sendEmail = tool(
  async ({ to, subject, body }: { to: string; subject: string; body: string }) => {
    return `Sent email to ${to}`;
  },
  {
    name: "send_email",
    description: "发送一封电子邮件。",
    schema: z.object({
      to: z.string(),
      subject: z.string(),
      body: z.string(),
    }),
  },
);

// 人机交互循环必须使用检查点存储器
const checkpointer = new MemorySaver();

const agent = createDeepAgent({
  model: "google_genai:gemini-3.1-pro-preview",
  tools: [deleteFile, readFile, sendEmail],
  interruptOn: {
    delete_file: true,  // 默认:批准、编辑、拒绝、响应
    read_file: false,   // 不需要中断
    send_email: { allowedDecisions: ["approve", "reject"] },  // 不允许编辑
  },
  checkpointer,  // 必需!
});
您可以为代理和子代理配置在工具调用时以及从工具调用内部进行中断。 有关更多信息,请参阅Human in the Loop

技能

您可以使用技能为您的深度代理提供新的能力和专业知识。 虽然工具往往涵盖较低级别的功能,如原生文件系统操作或规划,但技能可以包含有关如何完成任务的详细说明、参考信息和其他资产,例如模板。 这些文件仅在代理确定该技能对当前提示有用时才会被代理加载。 这种渐进式披露减少了代理在启动时必须考虑的令牌和上下文数量。 有关示例技能,请参阅深度代理示例技能 要将技能添加到您的深度代理,请将它们作为参数传递给 create_deep_agent
import { createDeepAgent, type FileData } from "deepagents";
import { MemorySaver } from "@langchain/langgraph";

const checkpointer = new MemorySaver();

function createFileData(content: string): FileData {
  const now = new Date().toISOString();
  return {
    content: content.split("\n"),
    created_at: now,
    modified_at: now,
  };
}

const skillsFiles: Record<string, FileData> = {};

const skillUrl =
  "https://raw.githubusercontent.com/langchain-ai/deepagentsjs/refs/heads/main/examples/skills/langgraph-docs/SKILL.md";
const response = await fetch(skillUrl);
const skillContent = await response.text();

skillsFiles["/skills/langgraph-docs/SKILL.md"] = createFileData(skillContent);

const agent = await createDeepAgent({
  checkpointer,
  // 重要:deepagents 技能源路径是相对于后端根目录的虚拟(POSIX)路径。
  skills: ["/skills/"],
});

const config = {
  configurable: {
    thread_id: `thread-${Date.now()}`,
  },
};

const result = await agent.invoke(
  {
    messages: [
      {
        role: "user",
        content: "什么是 langraph?如果可用,请使用 langgraph-docs 技能。",
      },
    ],
    files: skillsFiles,
  },
  config,
);

记忆

使用 AGENTS.md 文件为您的深度代理提供额外的上下文。 您可以在创建深度代理时将一个或多个文件路径传递给 memory 参数:
import { createDeepAgent, type FileData } from "deepagents";
import { MemorySaver } from "@langchain/langgraph";

const AGENTS_MD_URL =
  "https://raw.githubusercontent.com/langchain-ai/deepagents/refs/heads/main/examples/text-to-sql-agent/AGENTS.md";

async function fetchText(url: string): Promise<string> {
  const res = await fetch(url);
  if (!res.ok) {
    throw new Error(`Failed to fetch ${url}: ${res.status} ${res.statusText}`);
  }
  return await res.text();
}

const agentsMd = await fetchText(AGENTS_MD_URL);
const checkpointer = new MemorySaver();

function createFileData(content: string): FileData {
  const now = new Date().toISOString();
  return {
    content,
    mimeType: "text/plain",
    created_at: now,
    modified_at: now,
  };
}

const agent = await createDeepAgent({
  memory: ["/AGENTS.md"],
  checkpointer: checkpointer,
});

const result = await agent.invoke(
  {
    messages: [
      {
        role: "user",
        content: "Please tell me what's in your memory files.",
      },
    ],
    // 为默认 StateBackend 的状态内文件系统提供种子(虚拟路径必须以 "/" 开头)。
    files: { "/AGENTS.md": createFileData(agentsMd) },
  },
  { configurable: { thread_id: "12345" } }
);

配置文件

工具配置文件打包了每个提供商或每个模型的调整(系统提示后缀、工具描述覆盖、排除的工具或中间件、额外的中间件以及通用子代理编辑),以便 create_deep_agent 在选择匹配的模型时自动应用它们。
from deepagents import HarnessProfile, register_harness_profile

# 每当选择 gpt-5.4 时附加系统提示后缀。
register_harness_profile(
    "openai:gpt-5.4",
    HarnessProfile(system_prompt_suffix="Respond in under 100 words."),
)
有关注册键、合并语义和插件打包,请参阅配置文件。一个更窄的配套 API,提供商配置文件,打包了提供商的模型构造参数。

结构化输出

深度代理支持结构化输出 您可以通过将所需的结构化输出模式作为 responseFormat 参数传递给 createDeepAgent() 调用来设置它。 当模型生成结构化数据时,它会被捕获、验证,并在代理状态的 ‘structuredResponse’ 键中返回。
import { tool } from "langchain";
import { TavilySearch } from "@langchain/tavily";
import { createDeepAgent } from "deepagents";
import { z } from "zod";

const internetSearch = tool(
  async ({
    query,
    maxResults = 5,
    topic = "general",
    includeRawContent = false,
  }: {
    query: string;
    maxResults?: number;
    topic?: "general" | "news" | "finance";
    includeRawContent?: boolean;
  }) => {
    const tavilySearch = new TavilySearch({
      maxResults,
      tavilyApiKey: process.env.TAVILY_API_KEY,
      includeRawContent,
      topic,
    });
    return await tavilySearch._call({ query });
  },
  {
    name: "internet_search",
    description: "运行网络搜索",
    schema: z.object({
      query: z.string().describe("搜索查询"),
      maxResults: z.number().optional().default(5),
      topic: z
        .enum(["general", "news", "finance"])
        .optional()
        .default("general"),
      includeRawContent: z.boolean().optional().default(false),
    }),
  },
);

const weatherReportSchema = z.object({
  location: z.string().describe("此天气报告的位置"),
  temperature: z.number().describe("当前温度(摄氏度)"),
  condition: z.string().describe("当前天气状况(例如,晴朗、多云、下雨)"),
  humidity: z.number().describe("湿度百分比"),
  windSpeed: z.number().describe("风速(公里/小时)"),
  forecast: z.string().describe("未来 24 小时的简要预报"),
});

const agent = await createDeepAgent({
  responseFormat: weatherReportSchema,
  tools: [internetSearch],
});

const result = await agent.invoke({
  messages: [
    {
      role: "user",
      content: "What's the weather like in San Francisco?",
    },
  ],
});

console.log(result.structuredResponse);
// {
//   location: 'San Francisco, California',
//   temperature: 18.3,
//   condition: 'Sunny',
//   humidity: 48,
//   windSpeed: 7.6,
//   forecast: 'Clear skies with temperatures remaining mild. High of 18°C (64°F) during the day, dropping to around 11°C (52°F) at night.'
// }
有关更多信息和示例,请参阅响应格式。 有关更多信息和示例,请参阅响应格式