子代理 - Docs by LangChain中文

深度代理可以创建子代理来委派工作。您可以在 subagents 参数中指定自定义子代理。子代理对于上下文隔离（保持主代理的上下文清洁）以及提供专门的指令非常有用。本页涵盖同步子代理，即主管代理会阻塞直到子代理完成。对于长时间运行的任务、并行工作流，或需要在执行过程中进行引导和取消的情况，请参阅异步子代理。

为什么要使用子代理？

子代理解决了上下文膨胀问题。当代理使用具有大量输出的工具（网页搜索、文件读取、数据库查询）时，上下文窗口会迅速被中间结果填满。子代理隔离了这些详细工作——主代理只接收最终结果，而不是产生该结果的几十次工具调用。 何时使用子代理：

✅ 可能会混淆主代理上下文的多步骤任务
✅ 需要自定义指令或工具的专业领域
✅ 需要不同模型能力的任务
✅ 当您希望主代理专注于高级协调时

何时不使用子代理：

❌ 简单的单步骤任务
❌ 当您需要保留中间上下文时
❌ 当开销大于收益时

配置

subagents 应该是一个字典列表或 CompiledSubAgent 对象。有两种类型：

默认子代理

深度代理会自动添加一个同步的 general-purpose 子代理，除非您已经提供了一个同名的同步子代理。 general-purpose 子代理默认拥有文件系统工具，并且可以通过额外的工具/中间件进行自定义。

要替换它，请传递您自己的名为 general-purpose 的子代理。
要重命名或重新提示自动添加的版本，请在活动驱动配置上设置 general_purpose_subagent=GeneralPurposeSubagentProfile(...)。
要禁用它，请参阅下面的在没有子代理的情况下运行。

在没有子代理的情况下运行

要运行一个没有 task 工具的代理，需要做两件事：

在活动驱动配置上设置 general_purpose_subagent=GeneralPurposeSubagentProfile(enabled=False)。
通过 create_deep_agent 的 subagents= 参数不传递任何同步子代理。

深度代理仅在存在至少一个同步子代理时才附加 SubAgentMiddleware（以及 task 工具）。既没有默认子代理也没有调用者提供的子代理时，代理将无委派运行。异步子代理不受影响——它们通过自己的中间件和工具流动，如异步子代理中所述。

这里不要使用 excluded_middleware——SubAgentMiddleware 是必需的脚手架，将其列入会引发 ValueError。general_purpose_subagent.enabled = False 是受支持的途径。

自定义子代理

您可以使用 subagents 参数定义具有特定工具的专业化子代理。例如，用作代码审查员、网络研究员或测试运行器。对于大多数用例，请使用 SubAgent 字典将子代理定义为字典。对于复杂的工作流，请使用 CompiledSubAgent：

SubAgent（基于字典）

将子代理定义为匹配 SubAgent 规范的字典，包含以下字段：

字段	类型	描述
`name`	`string`	必需。子代理的唯一标识符。主代理在调用 `task()` 工具时使用此名称。子代理名称成为 `AIMessage` 和流式传输的元数据，有助于区分代理。
`description`	`string`	必需。此子代理功能的描述。要具体且面向操作。主代理用此来决定何时委派。
`systemPrompt`	`string`	必需。子代理的指令。自定义子代理必须定义自己的指令。包括工具使用指南和输出格式要求。不从主代理继承。
`tools`	`StructuredTool[]`	可选。子代理可以使用的工具。保持最小化，仅包含所需内容。默认从主代理继承。指定时，将完全覆盖继承的工具。
`model`	`LanguageModelLike \| string`	可选。覆盖主代理的模型。省略则使用主代理的模型。默认从主代理继承。您可以传递模型标识符字符串，如 `'openai:gpt-5.5'`（使用 `'provider:model'` 格式）或 LangChain 聊天模型对象（`await initChatModel("gpt-5.5")` 或 `new ChatOpenAI({ model: "gpt-5.5" })`）。
`middleware`	`AgentMiddleware[]`	可选。用于自定义行为、日志记录或速率限制的额外中间件。不从主代理继承。附加到默认子代理栈中。
`interruptOn`	`Record<string, boolean \| InterruptOnConfig>`	可选。为特定工具配置人在回路。选项：`True`、`False` 或带有 `allowed_decisions` 的 `InterruptOnConfig`。需要检查点。默认从主代理继承。子代理的值覆盖默认值。
`skills`	`string[]`	可选。技能源路径。指定后，子代理将从这些目录加载技能（例如 `["/skills/research/", "/skills/web-search/"]`）。这允许子代理拥有与主代理不同的技能集。不从主代理继承。只有通用子代理继承主代理的技能。当子代理拥有技能时，它会运行自己独立的 `SkillsMiddleware` 实例。技能状态是完全隔离的——子代理加载的技能对父代理不可见，反之亦然。
`responseFormat`	`ResponseFormat`	可选。子代理的结构化输出模式。设置后，父代理以 JSON 形式接收子代理的结果，而不是自由格式文本。接受 Zod 模式、JSON 模式对象、`toolStrategy(...)` 或 `providerStrategy(...)`。参见结构化输出。
`permissions`	`FilesystemPermission[]`	可选。子代理的文件系统权限规则。设置后，完全替换父代理的权限。默认从主代理继承。

CompiledSubAgent

对于复杂的工作流，可以使用预构建的 LangGraph 图作为 CompiledSubAgent：

字段	类型	描述
`name`	`str`	必需。子代理的唯一标识符。子代理名称成为 `AIMessage` 和流式传输的元数据，有助于区分代理。
`description`	`str`	必需。此子代理的功能。
`runnable`	`Runnable`	必需。编译后的 LangGraph 图（必须先调用 `.compile()`）。

使用 SubAgent

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: "google-genai:gemini-3.6-flash", // 可选覆盖，默认使用主代理模型
};
const subagents = [researchSubagent];
    
const agent = createDeepAgent({
  model: "google_genai:gemini-3.6-flash",
  subagents,
});

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.5", // 可选覆盖，默认使用主代理模型
};
const subagents = [researchSubagent];
    
const agent = createDeepAgent({
  model: "google_genai:gemini-3.6-flash",
  subagents,
});

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: "anthropic:claude-sonnet-4-6", // 可选覆盖，默认使用主代理模型
};
const subagents = [researchSubagent];
    
const agent = createDeepAgent({
  model: "google_genai:gemini-3.6-flash",
  subagents,
});

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: "openrouter:openrouter:z-ai/glm-5.2", // 可选覆盖，默认使用主代理模型
};
const subagents = [researchSubagent];
    
const agent = createDeepAgent({
  model: "google_genai:gemini-3.6-flash",
  subagents,
});

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: "fireworks:accounts/fireworks/models/glm-5p2", // 可选覆盖，默认使用主代理模型
};
const subagents = [researchSubagent];
    
const agent = createDeepAgent({
  model: "google_genai:gemini-3.6-flash",
  subagents,
});

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: "baseten:zai-org/GLM-5.2", // 可选覆盖，默认使用主代理模型
};
const subagents = [researchSubagent];
    
const agent = createDeepAgent({
  model: "google_genai:gemini-3.6-flash",
  subagents,
});

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: "ollama:north-mini-code-1.0", // 可选覆盖，默认使用主代理模型
};
const subagents = [researchSubagent];
    
const agent = createDeepAgent({
  model: "google_genai:gemini-3.6-flash",
  subagents,
});

使用 CompiledSubAgent

对于更复杂的用例，您可以使用 CompiledSubAgent 提供您的自定义子代理。您可以使用 LangChain 的 create_agent 或通过图 API 制作自定义 LangGraph 图来创建自定义子代理。如果您正在创建自定义 LangGraph 图，请确保该图具有一个名为 "messages" 的状态键：

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

const internetSearch = tool(
  async ({ query }: { query: string }) => `关于 ${query} 的搜索结果`,
  {
    name: "internet_search",
    description: "执行网络搜索",
    schema: z.object({ query: z.string() }),
  },
);

const researchInstructions = "你是一位研究协调员。";
const yourModel = "google_genai:gemini-3.6-flash";
const specializedTools: never[] = [];

// 创建一个自定义的智能体图
const customGraph = createAgent({
  model: yourModel,
  tools: specializedTools,
  prompt: "你是一个用于数据分析的专用智能体...",
});

// 将其用作一个自定义子智能体
const customSubagent: CompiledSubAgent = {
  name: "data-analyzer",
  description: "用于复杂数据分析任务的专用智能体",
  runnable: customGraph,
};

const subagents = [customSubagent];

const agent = createDeepAgent({
  model: "google-genai:gemini-3.6-flash",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
  subagents: subagents,
});

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

const internetSearch = tool(
  async ({ query }: { query: string }) => `关于 ${query} 的搜索结果`,
  {
    name: "internet_search",
    description: "执行网络搜索",
    schema: z.object({ query: z.string() }),
  },
);

const researchInstructions = "你是一位研究协调员。";
const yourModel = "google_genai:gemini-3.6-flash";
const specializedTools: never[] = [];

// 创建一个自定义的智能体图
const customGraph = createAgent({
  model: yourModel,
  tools: specializedTools,
  prompt: "你是一个用于数据分析的专用智能体...",
});

// 将其用作一个自定义子智能体
const customSubagent: CompiledSubAgent = {
  name: "data-analyzer",
  description: "用于复杂数据分析任务的专用智能体",
  runnable: customGraph,
};

const subagents = [customSubagent];

const agent = createDeepAgent({
  model: "openai:gpt-5.5",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
  subagents: subagents,
});

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

const internetSearch = tool(
  async ({ query }: { query: string }) => `关于 ${query} 的搜索结果`,
  {
    name: "internet_search",
    description: "执行网络搜索",
    schema: z.object({ query: z.string() }),
  },
);

const researchInstructions = "你是一位研究协调员。";
const yourModel = "google_genai:gemini-3.6-flash";
const specializedTools: never[] = [];

// 创建一个自定义的智能体图
const customGraph = createAgent({
  model: yourModel,
  tools: specializedTools,
  prompt: "你是一个用于数据分析的专用智能体...",
});

// 将其用作一个自定义子智能体
const customSubagent: CompiledSubAgent = {
  name: "data-analyzer",
  description: "用于复杂数据分析任务的专用智能体",
  runnable: customGraph,
};

const subagents = [customSubagent];

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

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

const internetSearch = tool(
  async ({ query }: { query: string }) => `关于 ${query} 的搜索结果`,
  {
    name: "internet_search",
    description: "执行网络搜索",
    schema: z.object({ query: z.string() }),
  },
);

const researchInstructions = "你是一位研究协调员。";
const yourModel = "google_genai:gemini-3.6-flash";
const specializedTools: never[] = [];

// 创建一个自定义的智能体图
const customGraph = createAgent({
  model: yourModel,
  tools: specializedTools,
  prompt: "你是一个用于数据分析的专用智能体...",
});

// 将其用作一个自定义子智能体
const customSubagent: CompiledSubAgent = {
  name: "data-analyzer",
  description: "用于复杂数据分析任务的专用智能体",
  runnable: customGraph,
};

const subagents = [customSubagent];

const agent = createDeepAgent({
  model: "openrouter:openrouter:z-ai/glm-5.2",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
  subagents: subagents,
});

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

const internetSearch = tool(
  async ({ query }: { query: string }) => `关于 ${query} 的搜索结果`,
  {
    name: "internet_search",
    description: "执行网络搜索",
    schema: z.object({ query: z.string() }),
  },
);

const researchInstructions = "你是一位研究协调员。";
const yourModel = "google_genai:gemini-3.6-flash";
const specializedTools: never[] = [];

// 创建一个自定义的智能体图
const customGraph = createAgent({
  model: yourModel,
  tools: specializedTools,
  prompt: "你是一个用于数据分析的专用智能体...",
});

// 将其用作一个自定义子智能体
const customSubagent: CompiledSubAgent = {
  name: "data-analyzer",
  description: "用于复杂数据分析任务的专用智能体",
  runnable: customGraph,
};

const subagents = [customSubagent];

const agent = createDeepAgent({
  model: "fireworks:accounts/fireworks/models/glm-5p2",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
  subagents: subagents,
});

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

const internetSearch = tool(
  async ({ query }: { query: string }) => `关于 ${query} 的搜索结果`,
  {
    name: "internet_search",
    description: "执行网络搜索",
    schema: z.object({ query: z.string() }),
  },
);

const researchInstructions = "你是一位研究协调员。";
const yourModel = "google_genai:gemini-3.6-flash";
const specializedTools: never[] = [];

// 创建一个自定义的智能体图
const customGraph = createAgent({
  model: yourModel,
  tools: specializedTools,
  prompt: "你是一个用于数据分析的专用智能体...",
});

// 将其用作一个自定义子智能体
const customSubagent: CompiledSubAgent = {
  name: "data-analyzer",
  description: "用于复杂数据分析任务的专用智能体",
  runnable: customGraph,
};

const subagents = [customSubagent];

const agent = createDeepAgent({
  model: "baseten:zai-org/GLM-5.2",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
  subagents: subagents,
});

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

const internetSearch = tool(
  async ({ query }: { query: string }) => `关于 ${query} 的搜索结果`,
  {
    name: "internet_search",
    description: "执行网络搜索",
    schema: z.object({ query: z.string() }),
  },
);

const researchInstructions = "你是一位研究协调员。";
const yourModel = "google_genai:gemini-3.6-flash";
const specializedTools: never[] = [];

// 创建一个自定义的智能体图
const customGraph = createAgent({
  model: yourModel,
  tools: specializedTools,
  prompt: "你是一个用于数据分析的专用智能体...",
});

// 将其用作一个自定义子智能体
const customSubagent: CompiledSubAgent = {
  name: "data-analyzer",
  description: "用于复杂数据分析任务的专用智能体",
  runnable: customGraph,
};

const subagents = [customSubagent];

const agent = createDeepAgent({
  model: "ollama:north-mini-code-1.0",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
  subagents: subagents,
});

动态子代理

默认情况下，主代理通过 task 工具调用委派给子代理（它可以在单个轮次中发出多个调用以并行运行它们）。附加了解释器后，代理可以改为从代码中派发子代理——使用循环、分支和并行批处理将工作分散到多个项目并以编程方式综合结果。这称为动态子代理。当工作跨越许多独立单元（审查目录中的每个文件、分流一批工单）、需要多个视角，或受益于递归分析时，请考虑使用动态子代理。

动态子代理使用解释器运行时，目前处于 测试版。API 和生命周期行为可能在版本之间发生变化。

启用动态子代理

只要代理拥有子代理和解释器中间件，动态子代理就可用。安装 QuickJS 解释器包，然后将 CodeInterpreterMiddleware 添加到您的代理。

npm install deepagents @langchain/quickjs

pnpm add deepagents @langchain/quickjs

yarn add deepagents @langchain/quickjs

import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

const agent = createDeepAgent({
  model: "google-genai:gemini-3.6-flash",
  subagents: [{
    name: "reviewer",
    description: "审查代码安全问题，引用行号和严重程度",
    systemPrompt: "你是一个专注于安全的代码审查员。报告问题时需包含行号和严重程度。",
  }],
  middleware: [createCodeInterpreterMiddleware()],
});

import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

const agent = createDeepAgent({
  model: "openai:gpt-5.5",
  subagents: [{
    name: "reviewer",
    description: "审查代码安全问题，引用行号和严重程度",
    systemPrompt: "你是一个专注于安全的代码审查员。报告问题时需包含行号和严重程度。",
  }],
  middleware: [createCodeInterpreterMiddleware()],
});

import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

const agent = createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  subagents: [{
    name: "reviewer",
    description: "审查代码安全问题，引用行号和严重程度",
    systemPrompt: "你是一个专注于安全的代码审查员。报告问题时需包含行号和严重程度。",
  }],
  middleware: [createCodeInterpreterMiddleware()],
});

import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

const agent = createDeepAgent({
  model: "openrouter:openrouter:z-ai/glm-5.2",
  subagents: [{
    name: "reviewer",
    description: "审查代码安全问题，引用行号和严重程度",
    systemPrompt: "你是一个专注于安全的代码审查员。报告问题时需包含行号和严重程度。",
  }],
  middleware: [createCodeInterpreterMiddleware()],
});

import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

const agent = createDeepAgent({
  model: "fireworks:accounts/fireworks/models/glm-5p2",
  subagents: [{
    name: "reviewer",
    description: "审查代码安全问题，引用行号和严重程度",
    systemPrompt: "你是一个专注于安全的代码审查员。报告问题时需包含行号和严重程度。",
  }],
  middleware: [createCodeInterpreterMiddleware()],
});

import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

const agent = createDeepAgent({
  model: "baseten:zai-org/GLM-5.2",
  subagents: [{
    name: "reviewer",
    description: "审查代码安全问题，引用行号和严重程度",
    systemPrompt: "你是一个专注于安全的代码审查员。报告问题时需包含行号和严重程度。",
  }],
  middleware: [createCodeInterpreterMiddleware()],
});

import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

const agent = createDeepAgent({
  model: "ollama:north-mini-code-1.0",
  subagents: [{
    name: "reviewer",
    description: "审查代码安全问题，引用行号和严重程度",
    systemPrompt: "你是一个专注于安全的代码审查员。报告问题时需包含行号和严重程度。",
  }],
  middleware: [createCodeInterpreterMiddleware()],
});

只要代理拥有子代理和解释器中间件，动态子代理派发默认开启。传递 createCodeInterpreterMiddleware({ subagents: false }) 以要求通过常规 task 工具路径派发。

触发动态编排

动态派发是隐式的：代理根据任务的形状决定是否从代码中分散工作，而不是通过每次调用的标志。

“workflow”一词是一个有用的触发词。 内置的解释器系统提示将“workflow”视为一个信号，表示通过解释器组织工作——从代码中使用 task() 派发子代理。将请求表述为“workflow”是一个您可以在选择启用动态编排时拉动的有意杠杆：当您希望代理从代码中分散工作时，请包含它。对于单个直接委派，请直接明了地表述请求。

例如，将请求表述为“workflow”会启用从代码中的扇出：

const result = await agent.invoke({
  messages: [{ role: "user", content: "运行一个工作流，该工作流会检查src/routes/目录下的每个文件并总结主要风险。" }],
});

::> 有关配置、高级编排模式和安全说明，请参阅动态子代理。

与编码代理一起使用

尝试动态子代理最快的方法是使用 dcode，即构建在深度代理之上的 LangChain 终端编码代理。它自带代码解释器，开箱即用，无需额外配置。安装 dcode：

curl -LsSf https://langch.in/dcode | bash

运行它：

dcode

要触发动态子代理，请要求一个“workflow”。代理不会自己处理工作，也不会通过其原生 task 工具管理扇出，而是编写一个编排脚本调用内置的 task() 全局函数并在代码解释器中运行它。例如：“运行一个工作流以审查 src/ 中的每个文件是否存在 SQL 注入。” 随着子代理的生成，dcode 会在动态子代理面板中实时显示它们，按派发分组成阶段。

dcode 是尝试此功能的最快方式，但您也可以在您选择的编码代理中通过 ACP（例如 Zed）使用动态子代理。

流式传输

深度代理支持从协调器和每个委派的子代理进行流式更新。 python 使用 stream_events 获取类型化投影——用于子代理、消息、工具调用和值的独立迭代器——以便您可以独立消费每个。 ::: 使用 streamEvents 获取类型化投影——用于子代理、消息、工具调用和值的独立迭代器——以便您可以独立消费每个。

流式传输子代理进度

最简单的模式是迭代 stream.subagents 以跟踪每个委派的任务开始、运行和完成。每个子代理句柄都公开 .name、.messages、.tool_calls 和 .output。

import { createDeepAgent } from "deepagents";
    
    const agent = createDeepAgent({
      model: "google-genai:gemini-3.6-flash",
      systemPrompt:
        "你是一个没有研究知识的项目协调员。" +
        "对于每个用户请求，你必须调用 task() 工具，" +
        "并将 subagent_type 设置为 research-agent。" +
        "永远不要自己回答研究问题。",
      subagents: [
        {
          name: "research-agent",
          description:
            "将研究任务委托给此子代理。一次只提供一个主题。",
          systemPrompt: "你是一个出色的研究员。请返回简短摘要。",
        },
      ],
    });
    
    async function streamSubagentProgress() {
      const stream = await agent.streamEvents(
        {
          messages: [
            {
              role: "user",
              content: "研究量子计算的最新进展。",
            },
          ],
        },
        { version: "v3" },
      );
    
      const coordinatorMessages: string[] = [];
      const subagentHandles: { name: string }[] = [];
    
      await Promise.all([
        (async () => {
          for await (const message of stream.messages) {
            console.log("[coordinator]", await message.text);
            coordinatorMessages.push(await message.text);
          }
        })(),
        (async () => {
          for await (const subagent of stream.subagents) {
            console.log(`[${subagent.name}] started`);
            subagentHandles.push({ name: subagent.name });
            for await (const message of subagent.messages) {
              console.log(`[${subagent.name}]`, await message.text);
            }
          }
        })(),
      ]);
    
      return { coordinatorMessages, subagentHandles };
    }

import { createDeepAgent } from "deepagents";

const agent = createDeepAgent({
  model: "openai:gpt-5.5",
  systemPrompt:
    "你是一个没有研究知识的项目协调员。" +
    "对于每个用户请求，你必须调用 task() 工具，" +
    "并将 subagent_type 设置为 research-agent。" +
    "永远不要自己回答研究问题。",
  subagents: [
    {
      name: "research-agent",
      description:
        "将研究任务委托给此子代理。一次只提供一个主题。",
      systemPrompt: "你是一个出色的研究员。请返回简短摘要。",
    },
  ],
});

async function streamSubagentProgress() {
  const stream = await agent.streamEvents(
    {
      messages: [
        {
          role: "user",
          content: "研究量子计算的最新进展。",
        },
      ],
    },
    { version: "v3" },
  );

  const coordinatorMessages: string[] = [];
  const subagentHandles: { name: string }[] = [];

  await Promise.all([
    (async () => {
      for await (const message of stream.messages) {
        console.log("[coordinator]", await message.text);
        coordinatorMessages.push(await message.text);
      }
    })(),
    (async () => {
      for await (const subagent of stream.subagents) {
        console.log(`[${subagent.name}] started`);
        subagentHandles.push({ name: subagent.name });
        for await (const message of subagent.messages) {
          console.log(`[${subagent.name}]`, await message.text);
        }
      }
    })(),
  ]);

  return { coordinatorMessages, subagentHandles };
}

import { createDeepAgent } from "deepagents";

const agent = createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  systemPrompt:
    "你是一个没有研究知识的项目协调员。" +
    "对于每个用户请求，你必须调用 task() 工具，" +
    "并将 subagent_type 设置为 research-agent。" +
    "永远不要自己回答研究问题。",
  subagents: [
    {
      name: "research-agent",
      description:
        "将研究任务委托给此子代理。一次只提供一个主题。",
      systemPrompt: "你是一个出色的研究员。请返回简短摘要。",
    },
  ],
});

async function streamSubagentProgress() {
  const stream = await agent.streamEvents(
    {
      messages: [
        {
          role: "user",
          content: "研究量子计算的最新进展。",
        },
      ],
    },
    { version: "v3" },
  );

  const coordinatorMessages: string[] = [];
  const subagentHandles: { name: string }[] = [];

  await Promise.all([
    (async () => {
      for await (const message of stream.messages) {
        console.log("[coordinator]", await message.text);
        coordinatorMessages.push(await message.text);
      }
    })(),
    (async () => {
      for await (const subagent of stream.subagents) {
        console.log(`[${subagent.name}] started`);
        subagentHandles.push({ name: subagent.name });
        for await (const message of subagent.messages) {
          console.log(`[${subagent.name}]`, await message.text);
        }
      }
    })(),
  ]);

  return { coordinatorMessages, subagentHandles };
}

import { createDeepAgent } from "deepagents";

const agent = createDeepAgent({
  model: "openrouter:openrouter:z-ai/glm-5.2",
  systemPrompt:
    "你是一个没有研究知识的项目协调员。" +
    "对于每个用户请求，你必须调用 task() 工具，" +
    "并将 subagent_type 设置为 research-agent。" +
    "永远不要自己回答研究问题。",
  subagents: [
    {
      name: "research-agent",
      description:
        "将研究任务委托给此子代理。一次只提供一个主题。",
      systemPrompt: "你是一个出色的研究员。请返回简短摘要。",
    },
  ],
});

async function streamSubagentProgress() {
  const stream = await agent.streamEvents(
    {
      messages: [
        {
          role: "user",
          content: "研究量子计算的最新进展。",
        },
      ],
    },
    { version: "v3" },
  );

  const coordinatorMessages: string[] = [];
  const subagentHandles: { name: string }[] = [];

  await Promise.all([
    (async () => {
      for await (const message of stream.messages) {
        console.log("[coordinator]", await message.text);
        coordinatorMessages.push(await message.text);
      }
    })(),
    (async () => {
      for await (const subagent of stream.subagents) {
        console.log(`[${subagent.name}] started`);
        subagentHandles.push({ name: subagent.name });
        for await (const message of subagent.messages) {
          console.log(`[${subagent.name}]`, await message.text);
        }
      }
    })(),
  ]);

  return { coordinatorMessages, subagentHandles };
}

import { createDeepAgent } from "deepagents";

const agent = createDeepAgent({
  model: "fireworks:accounts/fireworks/models/glm-5p2",
  systemPrompt:
    "你是一个没有研究知识的项目协调员。" +
    "对于每个用户请求，你必须调用 task() 工具，" +
    "并将 subagent_type 设置为 research-agent。" +
    "永远不要自己回答研究问题。",
  subagents: [
    {
      name: "research-agent",
      description:
        "将研究任务委托给此子代理。一次只提供一个主题。",
      systemPrompt: "你是一个出色的研究员。请返回简短摘要。",
    },
  ],
});

async function streamSubagentProgress() {
  const stream = await agent.streamEvents(
    {
      messages: [
        {
          role: "user",
          content: "研究量子计算的最新进展。",
        },
      ],
    },
    { version: "v3" },
  );

  const coordinatorMessages: string[] = [];
  const subagentHandles: { name: string }[] = [];

  await Promise.all([
    (async () => {
      for await (const message of stream.messages) {
        console.log("[coordinator]", await message.text);
        coordinatorMessages.push(await message.text);
      }
    })(),
    (async () => {
      for await (const subagent of stream.subagents) {
        console.log(`[${subagent.name}] started`);
        subagentHandles.push({ name: subagent.name });
        for await (const message of subagent.messages) {
          console.log(`[${subagent.name}]`, await message.text);
        }
      }
    })(),
  ]);

  return { coordinatorMessages, subagentHandles };
}

import { createDeepAgent } from "deepagents";

const agent = createDeepAgent({
  model: "baseten:zai-org/GLM-5.2",
  systemPrompt:
    "你是一个没有研究知识的项目协调员。" +
    "对于每个用户请求，你必须调用 task() 工具，" +
    "并将 subagent_type 设置为 research-agent。" +
    "永远不要自己回答研究问题。",
  subagents: [
    {
      name: "research-agent",
      description:
        "将研究任务委托给此子代理。一次只提供一个主题。",
      systemPrompt: "你是一个出色的研究员。请返回简短摘要。",
    },
  ],
});

async function streamSubagentProgress() {
  const stream = await agent.streamEvents(
    {
      messages: [
        {
          role: "user",
          content: "研究量子计算的最新进展。",
        },
      ],
    },
    { version: "v3" },
  );

  const coordinatorMessages: string[] = [];
  const subagentHandles: { name: string }[] = [];

  await Promise.all([
    (async () => {
      for await (const message of stream.messages) {
        console.log("[coordinator]", await message.text);
        coordinatorMessages.push(await message.text);
      }
    })(),
    (async () => {
      for await (const subagent of stream.subagents) {
        console.log(`[${subagent.name}] started`);
        subagentHandles.push({ name: subagent.name });
        for await (const message of subagent.messages) {
          console.log(`[${subagent.name}]`, await message.text);
        }
      }
    })(),
  ]);

  return { coordinatorMessages, subagentHandles };
}

import { createDeepAgent } from "deepagents";

const agent = createDeepAgent({
  model: "ollama:north-mini-code-1.0",
  systemPrompt:
    "你是一个没有研究知识的项目协调员。" +
    "对于每个用户请求，你必须调用 task() 工具，" +
    "并将 subagent_type 设置为 research-agent。" +
    "永远不要自己回答研究问题。",
  subagents: [
    {
      name: "research-agent",
      description:
        "将研究任务委托给此子代理。一次只提供一个主题。",
      systemPrompt: "你是一个出色的研究员。请返回简短摘要。",
    },
  ],
});

async function streamSubagentProgress() {
  const stream = await agent.streamEvents(
    {
      messages: [
        {
          role: "user",
          content: "研究量子计算的最新进展。",
        },
      ],
    },
    { version: "v3" },
  );

  const coordinatorMessages: string[] = [];
  const subagentHandles: { name: string }[] = [];

  await Promise.all([
    (async () => {
      for await (const message of stream.messages) {
        console.log("[coordinator]", await message.text);
        coordinatorMessages.push(await message.text);
      }
    })(),
    (async () => {
      for await (const subagent of stream.subagents) {
        console.log(`[${subagent.name}] started`);
        subagentHandles.push({ name: subagent.name });
        for await (const message of subagent.messages) {
          console.log(`[${subagent.name}]`, await message.text);
        }
      }
    })(),
  ]);

  return { coordinatorMessages, subagentHandles };
}

LangSmith 追踪

当您的深度代理运行时，由子代理或协调器执行的所有运行都将在其元数据中的 lc_agent_name 键下拥有代理名称——例如 {'lc_agent_name': 'research-agent'}。这使您能够在 LangSmith 中按子代理识别和过滤运行。显示元数据的 LangSmith 示例追踪

在 LangSmith 中打开运行以比较协调器追踪与每个子代理运行。请遵循可观测性快速入门进行设置。我们建议您还设置 LangSmith Engine，它会监控您的追踪、检测问题并提出修复建议。

在 LangSmith 中按子代理过滤

因为每个子代理的 name 都写入其产生的每个运行的 lc_agent_name 元数据键中，您可以使用 LangSmith 的元数据过滤来隔离来自特定子代理的所有运行——这对于调试、监控或比较子代理随时间的行为非常有用。

在 LangSmith UI 中过滤

在 LangSmith 中打开您的追踪项目。
在追踪项目页面将视图切换到 Runs 以查看单个跨度。
单击 Add filter 并选择 Metadata。
将 Key 设置为 lc_agent_name，将 Value 设置为子代理名称，例如 coordinator。

LangSmith Runs 视图，lc_agent_name 元数据过滤器设置为 coordinator

这将仅显示该子代理产生的运行。您可以将过滤器保存为命名视图以便重复使用。有关过滤选项的完整参考，请参阅过滤追踪。

使用 SDK 以编程方式过滤

在 LangSmith 过滤查询语言中使用 has 比较器通过元数据键值对匹配运行：

from langsmith import Client

client = Client()

runs = client.list_runs(
    project_name="<your-project>",
    filter='has(metadata, \'{"lc_agent_name": "research-agent"}\')',
)

for run in runs:
    print(run.name, run.start_time, run.status)

要获取来自任何命名子代理（不包括主代理）的运行，请过滤具有 lc_agent_name 键的运行：

runs = client.list_runs(
    project_name="<your-project>",
    filter="has(metadata, 'lc_agent_name')",
)

有关完整的过滤查询语言参考，请参阅追踪查询语法。

结构化输出

子代理支持结构化输出，因此父代理接收到的是可预测、可解析的 JSON，而不是自由格式文本。

子代理的结构化输出需要 deepagents>=1.8.4。

在子代理配置上传递 responseFormat。当子代理完成时，其结构化响应将被 JSON 序列化并作为 ToolMessage 内容返回给父代理。该模式接受 createAgent 支持的任何内容：Zod 模式、JSON 模式对象、toolStrategy(...) 或 providerStrategy(...)。

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

const webSearch = tool(
  async ({ query }: { query: string }) => `web results for ${query}`,
  {
    name: "web_search",
    description: "搜索网络",
    schema: z.object({ query: z.string() }),
  },
);

const ResearchFindings = z.object({
  summary: z.string().describe("研究结果摘要"),
  confidence: z.number().describe("置信度评分，范围从 0 到 1"),
  sources: z.array(z.string()).describe("来源 URL 列表"),
});

const researchSubagent = {
  name: "researcher",
  description: "研究主题并返回结构化结果",
  systemPrompt: "深入研究给定主题。返回你的研究结果。",
  tools: [webSearch],
  responseFormat: ResearchFindings,
};

const agent = createDeepAgent({
  model: "google-genai:gemini-3.6-flash",
  subagents: [researchSubagent],
});

const result = await agent.invoke({
  messages: [
    { role: "user", content: "研究量子计算的最新进展" },
  ],
});

// 父级的 ToolMessage 包含 JSON 序列化的结构化数据：
// '{"summary": "...", "confidence": 0.87, "sources": ["https://..."]}'

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

const webSearch = tool(
  async ({ query }: { query: string }) => `web results for ${query}`,
  {
    name: "web_search",
    description: "搜索网络",
    schema: z.object({ query: z.string() }),
  },
);

const ResearchFindings = z.object({
  summary: z.string().describe("研究结果摘要"),
  confidence: z.number().describe("置信度评分，范围从 0 到 1"),
  sources: z.array(z.string()).describe("来源 URL 列表"),
});

const researchSubagent = {
  name: "researcher",
  description: "研究主题并返回结构化结果",
  systemPrompt: "深入研究给定主题。返回你的研究结果。",
  tools: [webSearch],
  responseFormat: ResearchFindings,
};

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

const result = await agent.invoke({
  messages: [
    { role: "user", content: "研究量子计算的最新进展" },
  ],
});

// 父级的 ToolMessage 包含 JSON 序列化的结构化数据：
// '{"summary": "...", "confidence": 0.87, "sources": ["https://..."]}'

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

const webSearch = tool(
  async ({ query }: { query: string }) => `web results for ${query}`,
  {
    name: "web_search",
    description: "搜索网络",
    schema: z.object({ query: z.string() }),
  },
);

const ResearchFindings = z.object({
  summary: z.string().describe("研究结果摘要"),
  confidence: z.number().describe("置信度评分，范围从 0 到 1"),
  sources: z.array(z.string()).describe("来源 URL 列表"),
});

const researchSubagent = {
  name: "researcher",
  description: "研究主题并返回结构化结果",
  systemPrompt: "深入研究给定主题。返回你的研究结果。",
  tools: [webSearch],
  responseFormat: ResearchFindings,
};

const agent = createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  subagents: [researchSubagent],
});

const result = await agent.invoke({
  messages: [
    { role: "user", content: "研究量子计算的最新进展" },
  ],
});

// 父级的 ToolMessage 包含 JSON 序列化的结构化数据：
// '{"summary": "...", "confidence": 0.87, "sources": ["https://..."]}'

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

const webSearch = tool(
  async ({ query }: { query: string }) => `web results for ${query}`,
  {
    name: "web_search",
    description: "搜索网络",
    schema: z.object({ query: z.string() }),
  },
);

const ResearchFindings = z.object({
  summary: z.string().describe("研究结果摘要"),
  confidence: z.number().describe("置信度评分，范围从 0 到 1"),
  sources: z.array(z.string()).describe("来源 URL 列表"),
});

const researchSubagent = {
  name: "researcher",
  description: "研究主题并返回结构化结果",
  systemPrompt: "深入研究给定主题。返回你的研究结果。",
  tools: [webSearch],
  responseFormat: ResearchFindings,
};

const agent = createDeepAgent({
  model: "openrouter:openrouter:z-ai/glm-5.2",
  subagents: [researchSubagent],
});

const result = await agent.invoke({
  messages: [
    { role: "user", content: "研究量子计算的最新进展" },
  ],
});

// 父级的 ToolMessage 包含 JSON 序列化的结构化数据：
// '{"summary": "...", "confidence": 0.87, "sources": ["https://..."]}'

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

const webSearch = tool(
  async ({ query }: { query: string }) => `web results for ${query}`,
  {
    name: "web_search",
    description: "搜索网络",
    schema: z.object({ query: z.string() }),
  },
);

const ResearchFindings = z.object({
  summary: z.string().describe("研究结果摘要"),
  confidence: z.number().describe("置信度评分，范围从 0 到 1"),
  sources: z.array(z.string()).describe("来源 URL 列表"),
});

const researchSubagent = {
  name: "researcher",
  description: "研究主题并返回结构化结果",
  systemPrompt: "深入研究给定主题。返回你的研究结果。",
  tools: [webSearch],
  responseFormat: ResearchFindings,
};

const agent = createDeepAgent({
  model: "fireworks:accounts/fireworks/models/glm-5p2",
  subagents: [researchSubagent],
});

const result = await agent.invoke({
  messages: [
    { role: "user", content: "研究量子计算的最新进展" },
  ],
});

// 父级的 ToolMessage 包含 JSON 序列化的结构化数据：
// '{"summary": "...", "confidence": 0.87, "sources": ["https://..."]}'

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

const webSearch = tool(
  async ({ query }: { query: string }) => `web results for ${query}`,
  {
    name: "web_search",
    description: "搜索网络",
    schema: z.object({ query: z.string() }),
  },
);

const ResearchFindings = z.object({
  summary: z.string().describe("研究结果摘要"),
  confidence: z.number().describe("置信度评分，范围从 0 到 1"),
  sources: z.array(z.string()).describe("来源 URL 列表"),
});

const researchSubagent = {
  name: "researcher",
  description: "研究主题并返回结构化结果",
  systemPrompt: "深入研究给定主题。返回你的研究结果。",
  tools: [webSearch],
  responseFormat: ResearchFindings,
};

const agent = createDeepAgent({
  model: "baseten:zai-org/GLM-5.2",
  subagents: [researchSubagent],
});

const result = await agent.invoke({
  messages: [
    { role: "user", content: "研究量子计算的最新进展" },
  ],
});

// 父级的 ToolMessage 包含 JSON 序列化的结构化数据：
// '{"summary": "...", "confidence": 0.87, "sources": ["https://..."]}'

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

const webSearch = tool(
  async ({ query }: { query: string }) => `web results for ${query}`,
  {
    name: "web_search",
    description: "搜索网络",
    schema: z.object({ query: z.string() }),
  },
);

const ResearchFindings = z.object({
  summary: z.string().describe("研究结果摘要"),
  confidence: z.number().describe("置信度评分，范围从 0 到 1"),
  sources: z.array(z.string()).describe("来源 URL 列表"),
});

const researchSubagent = {
  name: "researcher",
  description: "研究主题并返回结构化结果",
  systemPrompt: "深入研究给定主题。返回你的研究结果。",
  tools: [webSearch],
  responseFormat: ResearchFindings,
};

const agent = createDeepAgent({
  model: "ollama:north-mini-code-1.0",
  subagents: [researchSubagent],
});

const result = await agent.invoke({
  messages: [
    { role: "user", content: "研究量子计算的最新进展" },
  ],
});

// 父级的 ToolMessage 包含 JSON 序列化的结构化数据：
// '{"summary": "...", "confidence": 0.87, "sources": ["https://..."]}'

如果没有 response_format，父代理会原样接收子代理最后的消息文本。使用它时，父代理总是获得符合模式的有效 JSON，这在父代理需要以编程方式处理结果或将其传递给下游工具时非常有用。有关模式类型和策略（工具调用与原生提供程序）的完整详细信息，请参阅结构化输出。

通用子代理

除了任何用户定义的子代理之外，每个深度代理在任何时候都可以访问一个 general-purpose 子代理。此子代理：

使用其自己的应用了配置文件覆盖的默认系统提示
可以访问所有相同的工具
使用相同的模型（除非被覆盖）
从主代理继承技能（当技能已配置时）

覆盖通用子代理

在您的 subagents 列表中包含一个 name: "general-purpose" 的子代理以替换默认的。使用此方法可以为通用子代理配置不同的模型、工具或系统提示：

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

const internetSearch = tool(
  async ({ query }: { query: string }) => `搜索结果：${query}`,
  {
    name: "internet_search",
    description: "执行网络搜索",
    schema: z.object({ query: z.string() }),
  },
);

// 主代理使用 Gemini；通用子代理使用 GPT
const agent = await createDeepAgent({
  model: "google-genai:gemini-3.6-flash",
  tools: [internetSearch],
  subagents: [
    {
      name: "general-purpose",
      description: "用于研究和多步任务的通用代理",
      systemPrompt: "你是一个通用助手。",
      tools: [internetSearch],
      model: "openai:gpt-5.5", // 为委派任务使用不同的模型
    },
  ],
});

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

const internetSearch = tool(
  async ({ query }: { query: string }) => `搜索结果：${query}`,
  {
    name: "internet_search",
    description: "执行网络搜索",
    schema: z.object({ query: z.string() }),
  },
);

// 主代理使用 Gemini；通用子代理使用 GPT
const agent = await createDeepAgent({
  model: "openai:gpt-5.5",
  tools: [internetSearch],
  subagents: [
    {
      name: "general-purpose",
      description: "用于研究和多步任务的通用代理",
      systemPrompt: "你是一个通用助手。",
      tools: [internetSearch],
      model: "openai:gpt-5.5", // 为委派任务使用不同的模型
    },
  ],
});

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

const internetSearch = tool(
  async ({ query }: { query: string }) => `搜索结果：${query}`,
  {
    name: "internet_search",
    description: "执行网络搜索",
    schema: z.object({ query: z.string() }),
  },
);

// 主代理使用 Gemini；通用子代理使用 GPT
const agent = await createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  tools: [internetSearch],
  subagents: [
    {
      name: "general-purpose",
      description: "用于研究和多步任务的通用代理",
      systemPrompt: "你是一个通用助手。",
      tools: [internetSearch],
      model: "openai:gpt-5.5", // 为委派任务使用不同的模型
    },
  ],
});

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

const internetSearch = tool(
  async ({ query }: { query: string }) => `搜索结果：${query}`,
  {
    name: "internet_search",
    description: "执行网络搜索",
    schema: z.object({ query: z.string() }),
  },
);

// 主代理使用 Gemini；通用子代理使用 GPT
const agent = await createDeepAgent({
  model: "openrouter:openrouter:z-ai/glm-5.2",
  tools: [internetSearch],
  subagents: [
    {
      name: "general-purpose",
      description: "用于研究和多步任务的通用代理",
      systemPrompt: "你是一个通用助手。",
      tools: [internetSearch],
      model: "openai:gpt-5.5", // 为委派任务使用不同的模型
    },
  ],
});

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

const internetSearch = tool(
  async ({ query }: { query: string }) => `搜索结果：${query}`,
  {
    name: "internet_search",
    description: "执行网络搜索",
    schema: z.object({ query: z.string() }),
  },
);

// 主代理使用 Gemini；通用子代理使用 GPT
const agent = await createDeepAgent({
  model: "fireworks:accounts/fireworks/models/glm-5p2",
  tools: [internetSearch],
  subagents: [
    {
      name: "general-purpose",
      description: "用于研究和多步任务的通用代理",
      systemPrompt: "你是一个通用助手。",
      tools: [internetSearch],
      model: "openai:gpt-5.5", // 为委派任务使用不同的模型
    },
  ],
});

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

const internetSearch = tool(
  async ({ query }: { query: string }) => `搜索结果：${query}`,
  {
    name: "internet_search",
    description: "执行网络搜索",
    schema: z.object({ query: z.string() }),
  },
);

// 主代理使用 Gemini；通用子代理使用 GPT
const agent = await createDeepAgent({
  model: "baseten:zai-org/GLM-5.2",
  tools: [internetSearch],
  subagents: [
    {
      name: "general-purpose",
      description: "用于研究和多步任务的通用代理",
      systemPrompt: "你是一个通用助手。",
      tools: [internetSearch],
      model: "openai:gpt-5.5", // 为委派任务使用不同的模型
    },
  ],
});

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

const internetSearch = tool(
  async ({ query }: { query: string }) => `搜索结果：${query}`,
  {
    name: "internet_search",
    description: "执行网络搜索",
    schema: z.object({ query: z.string() }),
  },
);

// 主代理使用 Gemini；通用子代理使用 GPT
const agent = await createDeepAgent({
  model: "ollama:north-mini-code-1.0",
  tools: [internetSearch],
  subagents: [
    {
      name: "general-purpose",
      description: "用于研究和多步任务的通用代理",
      systemPrompt: "你是一个通用助手。",
      tools: [internetSearch],
      model: "openai:gpt-5.5", // 为委派任务使用不同的模型
    },
  ],
});

当您提供一个具有通用名称的子代理时，默认的通用子代理不会被添加。您的规范完全替换了它。要完全移除内置的通用子代理而不是替换它，请将活动驱动配置文件的通用子代理 enabled 标志设置为 False。

何时使用它

通用子代理非常适合在没有专门行为的情况下进行上下文隔离。主代理可以将一个复杂的多步骤任务委派给此子代理，并获得简洁的结果，而不会因为中间工具调用而膨胀。

示例

主代理不是自己进行 10 次网络搜索并用结果填满其上下文，而是委派给通用子代理：task(name="general-purpose", task="研究量子计算趋势")。子代理在内部执行所有搜索，并仅返回摘要。

技能继承

使用 create_deep_agent 配置技能时：

通用子代理：自动从主代理继承技能
自定义子代理：默认不继承技能——使用 skills 参数赋予它们自己的技能

只有配置了技能的子代理才会获得 SkillsMiddleware 实例——没有 skills 参数的自定义子代理则不会。存在时，技能状态在两个方向上都是完全隔离的：父代理的技能对子代理不可见，子代理的技能也不会传播回父代理。

import { createDeepAgent } from "deepagents";

const researchSubagent = {
  name: "researcher",
  description: "具有专业技能的研究助手",
  systemPrompt: "你是一名研究员。",
  tools: [webSearch],
  skills: ["/skills/research/", "/skills/web-search/"], // 子智能体专属技能
};

const agent = await createDeepAgent({
  model: "google_genai:gemini-3.6-flash",
  skills: ["/skills/main/"], // 主智能体和GP子智能体获得这些技能
  subagents: [researchSubagent], // 研究员仅获得其自身技能
});

最佳实践

编写清晰的描述

主代理使用描述来决定调用哪个子代理。要具体： ✅ 好： "分析金融数据并生成带有置信度分数的投资洞察" ❌ 差： "处理金融事务"

保持系统提示详细

包含关于如何使用工具和格式化输出的具体指导：

const researchSubagent = {
  name: "research-agent",
  description:
    "使用网络搜索进行深入研究并综合发现",
  systemPrompt: `你是一个细致的研究员。你的工作是：

  1. 将研究问题分解为可搜索的查询
  2. 使用 internet_search 来查找相关信息
  3. 将发现综合成一个全面但简洁的总结
  4. 在陈述主张时引用来源

  输出格式：
  - 摘要（2-3 段）
  - 关键发现（项目符号）
  - 来源（附带 URL）

  将你的回复保持在 500 字以内，以保持上下文清晰。`,
  tools: [internetSearch],
};

最小化工具集

只给子代理他们需要的工具。这可以提高专注度和安全性：

// ✅ 好的：专注的工具集
const emailAgent = {
  name: "email-sender",
  tools: [sendEmail, validateEmail], // 仅限电子邮件相关
};

// ❌ 错误示范：工具过多
const emailAgentBad = {
  name: "email-sender",
  tools: [sendEmail, webSearch, databaseQuery, fileUpload], // 不够聚焦
};

按任务选择模型

不同的模型擅长不同的任务：

const subagents = [
  {
    name: "contract-reviewer",
    description: "审查法律文件和合同",
    systemPrompt: "You are an expert legal reviewer...",
    tools: [readDocument, analyzeContract],
    model: "google-genai:gemini-3.6-flash", // 用于长文档的大上下文
  },
  {
    name: "financial-analyst",
    description: "分析财务数据和市场趋势",
    systemPrompt: "You are an expert financial analyst...",
    tools: [getStockPrice, analyzeFundamentals],
    model: "openai:gpt-5.5", // 更适合数值分析
  },
];

const subagents = [
  {
    name: "contract-reviewer",
    description: "审查法律文件和合同",
    systemPrompt: "You are an expert legal reviewer...",
    tools: [readDocument, analyzeContract],
    model: "openai:gpt-5.5", // 用于长文档的大上下文
  },
  {
    name: "financial-analyst",
    description: "分析财务数据和市场趋势",
    systemPrompt: "You are an expert financial analyst...",
    tools: [getStockPrice, analyzeFundamentals],
    model: "openai:gpt-5.5", // 更适合数值分析
  },
];

const subagents = [
  {
    name: "contract-reviewer",
    description: "审查法律文件和合同",
    systemPrompt: "You are an expert legal reviewer...",
    tools: [readDocument, analyzeContract],
    model: "anthropic:claude-sonnet-4-6", // 用于长文档的大上下文
  },
  {
    name: "financial-analyst",
    description: "分析财务数据和市场趋势",
    systemPrompt: "You are an expert financial analyst...",
    tools: [getStockPrice, analyzeFundamentals],
    model: "openai:gpt-5.5", // 更适合数值分析
  },
];

const subagents = [
  {
    name: "contract-reviewer",
    description: "审查法律文件和合同",
    systemPrompt: "You are an expert legal reviewer...",
    tools: [readDocument, analyzeContract],
    model: "openrouter:openrouter:z-ai/glm-5.2", // 用于长文档的大上下文
  },
  {
    name: "financial-analyst",
    description: "分析财务数据和市场趋势",
    systemPrompt: "You are an expert financial analyst...",
    tools: [getStockPrice, analyzeFundamentals],
    model: "openai:gpt-5.5", // 更适合数值分析
  },
];

const subagents = [
  {
    name: "contract-reviewer",
    description: "审查法律文件和合同",
    systemPrompt: "You are an expert legal reviewer...",
    tools: [readDocument, analyzeContract],
    model: "fireworks:accounts/fireworks/models/glm-5p2", // 用于长文档的大上下文
  },
  {
    name: "financial-analyst",
    description: "分析财务数据和市场趋势",
    systemPrompt: "You are an expert financial analyst...",
    tools: [getStockPrice, analyzeFundamentals],
    model: "openai:gpt-5.5", // 更适合数值分析
  },
];

const subagents = [
  {
    name: "contract-reviewer",
    description: "审查法律文件和合同",
    systemPrompt: "You are an expert legal reviewer...",
    tools: [readDocument, analyzeContract],
    model: "baseten:zai-org/GLM-5.2", // 用于长文档的大上下文
  },
  {
    name: "financial-analyst",
    description: "分析财务数据和市场趋势",
    systemPrompt: "You are an expert financial analyst...",
    tools: [getStockPrice, analyzeFundamentals],
    model: "openai:gpt-5.5", // 更适合数值分析
  },
];

const subagents = [
  {
    name: "contract-reviewer",
    description: "审查法律文件和合同",
    systemPrompt: "You are an expert legal reviewer...",
    tools: [readDocument, analyzeContract],
    model: "ollama:north-mini-code-1.0", // 用于长文档的大上下文
  },
  {
    name: "financial-analyst",
    description: "分析财务数据和市场趋势",
    systemPrompt: "You are an expert financial analyst...",
    tools: [getStockPrice, analyzeFundamentals],
    model: "openai:gpt-5.5", // 更适合数值分析
  },
];

返回简洁的结果

指示子代理返回摘要，而不是原始数据：

const dataAnalyst = {
  systemPrompt: `分析数据并返回：
  1. 关键见解（3-5 个要点）
  2. 总体置信度评分
  3. 建议的后续行动

  请勿包含：
  - 原始数据
  - 中间计算过程
  - 详细的工具输出

  请将回答控制在 300 字以内。`,
};

常见模式

多个专业化子代理

为不同的领域创建专业化的子代理：

import { createDeepAgent } from "deepagents";

const subagents = [
  {
    name: "data-collector",
    description: "从各种来源收集原始数据",
    systemPrompt: "收集关于该主题的综合数据",
    tools: [webSearch, apiCall, databaseQuery],
  },
  {
    name: "data-analyzer",
    description: "分析收集的数据以提取见解",
    systemPrompt: "分析数据并提取关键见解",
    tools: [statisticalAnalysis],
  },
  {
    name: "report-writer",
    description: "根据分析结果撰写详实的报告",
    systemPrompt: "根据见解创建专业报告",
    tools: [formatDocument],
  },
];

const agent = createDeepAgent({
  model: "google-genai:gemini-3.6-flash",
  systemPrompt:
    "你协调数据分析和报告工作。使用子代理执行专门任务。",
  subagents: subagents,
});

import { createDeepAgent } from "deepagents";

const subagents = [
  {
    name: "data-collector",
    description: "从各种来源收集原始数据",
    systemPrompt: "收集关于该主题的综合数据",
    tools: [webSearch, apiCall, databaseQuery],
  },
  {
    name: "data-analyzer",
    description: "分析收集的数据以提取见解",
    systemPrompt: "分析数据并提取关键见解",
    tools: [statisticalAnalysis],
  },
  {
    name: "report-writer",
    description: "根据分析结果撰写详实的报告",
    systemPrompt: "根据见解创建专业报告",
    tools: [formatDocument],
  },
];

const agent = createDeepAgent({
  model: "openai:gpt-5.5",
  systemPrompt:
    "你协调数据分析和报告工作。使用子代理执行专门任务。",
  subagents: subagents,
});

import { createDeepAgent } from "deepagents";

const subagents = [
  {
    name: "data-collector",
    description: "从各种来源收集原始数据",
    systemPrompt: "收集关于该主题的综合数据",
    tools: [webSearch, apiCall, databaseQuery],
  },
  {
    name: "data-analyzer",
    description: "分析收集的数据以提取见解",
    systemPrompt: "分析数据并提取关键见解",
    tools: [statisticalAnalysis],
  },
  {
    name: "report-writer",
    description: "根据分析结果撰写详实的报告",
    systemPrompt: "根据见解创建专业报告",
    tools: [formatDocument],
  },
];

const agent = createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  systemPrompt:
    "你协调数据分析和报告工作。使用子代理执行专门任务。",
  subagents: subagents,
});

import { createDeepAgent } from "deepagents";

const subagents = [
  {
    name: "data-collector",
    description: "从各种来源收集原始数据",
    systemPrompt: "收集关于该主题的综合数据",
    tools: [webSearch, apiCall, databaseQuery],
  },
  {
    name: "data-analyzer",
    description: "分析收集的数据以提取见解",
    systemPrompt: "分析数据并提取关键见解",
    tools: [statisticalAnalysis],
  },
  {
    name: "report-writer",
    description: "根据分析结果撰写详实的报告",
    systemPrompt: "根据见解创建专业报告",
    tools: [formatDocument],
  },
];

const agent = createDeepAgent({
  model: "openrouter:openrouter:z-ai/glm-5.2",
  systemPrompt:
    "你协调数据分析和报告工作。使用子代理执行专门任务。",
  subagents: subagents,
});

import { createDeepAgent } from "deepagents";

const subagents = [
  {
    name: "data-collector",
    description: "从各种来源收集原始数据",
    systemPrompt: "收集关于该主题的综合数据",
    tools: [webSearch, apiCall, databaseQuery],
  },
  {
    name: "data-analyzer",
    description: "分析收集的数据以提取见解",
    systemPrompt: "分析数据并提取关键见解",
    tools: [statisticalAnalysis],
  },
  {
    name: "report-writer",
    description: "根据分析结果撰写详实的报告",
    systemPrompt: "根据见解创建专业报告",
    tools: [formatDocument],
  },
];

const agent = createDeepAgent({
  model: "fireworks:accounts/fireworks/models/glm-5p2",
  systemPrompt:
    "你协调数据分析和报告工作。使用子代理执行专门任务。",
  subagents: subagents,
});

import { createDeepAgent } from "deepagents";

const subagents = [
  {
    name: "data-collector",
    description: "从各种来源收集原始数据",
    systemPrompt: "收集关于该主题的综合数据",
    tools: [webSearch, apiCall, databaseQuery],
  },
  {
    name: "data-analyzer",
    description: "分析收集的数据以提取见解",
    systemPrompt: "分析数据并提取关键见解",
    tools: [statisticalAnalysis],
  },
  {
    name: "report-writer",
    description: "根据分析结果撰写详实的报告",
    systemPrompt: "根据见解创建专业报告",
    tools: [formatDocument],
  },
];

const agent = createDeepAgent({
  model: "baseten:zai-org/GLM-5.2",
  systemPrompt:
    "你协调数据分析和报告工作。使用子代理执行专门任务。",
  subagents: subagents,
});

import { createDeepAgent } from "deepagents";

const subagents = [
  {
    name: "data-collector",
    description: "从各种来源收集原始数据",
    systemPrompt: "收集关于该主题的综合数据",
    tools: [webSearch, apiCall, databaseQuery],
  },
  {
    name: "data-analyzer",
    description: "分析收集的数据以提取见解",
    systemPrompt: "分析数据并提取关键见解",
    tools: [statisticalAnalysis],
  },
  {
    name: "report-writer",
    description: "根据分析结果撰写详实的报告",
    systemPrompt: "根据见解创建专业报告",
    tools: [formatDocument],
  },
];

const agent = createDeepAgent({
  model: "ollama:north-mini-code-1.0",
  systemPrompt:
    "你协调数据分析和报告工作。使用子代理执行专门任务。",
  subagents: subagents,
});

工作流：

主代理创建高级计划
将数据收集委派给 data-collector
将结果传递给 data-analyzer
将洞察发送给 report-writer
编译最终输出

每个子代理都在干净的上下文中工作，只专注于其任务。

上下文管理

当您使用运行时上下文调用父代理时，该上下文会自动传播到所有子代理。每个子代理运行都会接收到您在父代理 invoke / ainvoke 调用中传递的相同运行时上下文。这意味着在任何子代理内部运行的工具都可以访问您提供给父代理的相同上下文值：

import { createDeepAgent } from "deepagents";
import { tool } from "langchain";
import type { ToolRuntime } from "@langchain/core/tools";
import { z } from "zod";

const contextSchema = z.object({
  userId: z.string(),
  sessionId: z.string(),
});

const getUserData = tool(
  async (input, runtime: ToolRuntime<unknown, typeof contextSchema>) => {
    const userId = runtime.context?.userId;
    return `Data for user ${userId}: ${input.query}`;
  },
  {
    name: "get_user_data",
    description: "获取当前用户的数据",
    schema: z.object({ query: z.string() }),
  },
);

const researchSubagent = {
  name: "researcher",
  description: "为当前用户进行研究",
  systemPrompt: "你是一名研究助手。",
  tools: [getUserData],
};

const agent = createDeepAgent({
  model: "google-genai:gemini-3.6-flash",
  subagents: [researchSubagent],
  contextSchema,
});

// 上下文会自动传递给研究员子代理及其工具
const result = await agent.invoke(
  { messages: [new HumanMessage("Look up my recent activity")] },
  { context: { userId: "user-123", sessionId: "abc" } },
);

import { createDeepAgent } from "deepagents";
import { tool } from "langchain";
import type { ToolRuntime } from "@langchain/core/tools";
import { z } from "zod";

const contextSchema = z.object({
  userId: z.string(),
  sessionId: z.string(),
});

const getUserData = tool(
  async (input, runtime: ToolRuntime<unknown, typeof contextSchema>) => {
    const userId = runtime.context?.userId;
    return `Data for user ${userId}: ${input.query}`;
  },
  {
    name: "get_user_data",
    description: "获取当前用户的数据",
    schema: z.object({ query: z.string() }),
  },
);

const researchSubagent = {
  name: "researcher",
  description: "为当前用户进行研究",
  systemPrompt: "你是一名研究助手。",
  tools: [getUserData],
};

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

// 上下文会自动传递给研究员子代理及其工具
const result = await agent.invoke(
  { messages: [new HumanMessage("Look up my recent activity")] },
  { context: { userId: "user-123", sessionId: "abc" } },
);

import { createDeepAgent } from "deepagents";
import { tool } from "langchain";
import type { ToolRuntime } from "@langchain/core/tools";
import { z } from "zod";

const contextSchema = z.object({
  userId: z.string(),
  sessionId: z.string(),
});

const getUserData = tool(
  async (input, runtime: ToolRuntime<unknown, typeof contextSchema>) => {
    const userId = runtime.context?.userId;
    return `Data for user ${userId}: ${input.query}`;
  },
  {
    name: "get_user_data",
    description: "获取当前用户的数据",
    schema: z.object({ query: z.string() }),
  },
);

const researchSubagent = {
  name: "researcher",
  description: "为当前用户进行研究",
  systemPrompt: "你是一名研究助手。",
  tools: [getUserData],
};

const agent = createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  subagents: [researchSubagent],
  contextSchema,
});

// 上下文会自动传递给研究员子代理及其工具
const result = await agent.invoke(
  { messages: [new HumanMessage("Look up my recent activity")] },
  { context: { userId: "user-123", sessionId: "abc" } },
);

import { createDeepAgent } from "deepagents";
import { tool } from "langchain";
import type { ToolRuntime } from "@langchain/core/tools";
import { z } from "zod";

const contextSchema = z.object({
  userId: z.string(),
  sessionId: z.string(),
});

const getUserData = tool(
  async (input, runtime: ToolRuntime<unknown, typeof contextSchema>) => {
    const userId = runtime.context?.userId;
    return `Data for user ${userId}: ${input.query}`;
  },
  {
    name: "get_user_data",
    description: "获取当前用户的数据",
    schema: z.object({ query: z.string() }),
  },
);

const researchSubagent = {
  name: "researcher",
  description: "为当前用户进行研究",
  systemPrompt: "你是一名研究助手。",
  tools: [getUserData],
};

const agent = createDeepAgent({
  model: "openrouter:openrouter:z-ai/glm-5.2",
  subagents: [researchSubagent],
  contextSchema,
});

// 上下文会自动传递给研究员子代理及其工具
const result = await agent.invoke(
  { messages: [new HumanMessage("Look up my recent activity")] },
  { context: { userId: "user-123", sessionId: "abc" } },
);

import { createDeepAgent } from "deepagents";
import { tool } from "langchain";
import type { ToolRuntime } from "@langchain/core/tools";
import { z } from "zod";

const contextSchema = z.object({
  userId: z.string(),
  sessionId: z.string(),
});

const getUserData = tool(
  async (input, runtime: ToolRuntime<unknown, typeof contextSchema>) => {
    const userId = runtime.context?.userId;
    return `Data for user ${userId}: ${input.query}`;
  },
  {
    name: "get_user_data",
    description: "获取当前用户的数据",
    schema: z.object({ query: z.string() }),
  },
);

const researchSubagent = {
  name: "researcher",
  description: "为当前用户进行研究",
  systemPrompt: "你是一名研究助手。",
  tools: [getUserData],
};

const agent = createDeepAgent({
  model: "fireworks:accounts/fireworks/models/glm-5p2",
  subagents: [researchSubagent],
  contextSchema,
});

// 上下文会自动传递给研究员子代理及其工具
const result = await agent.invoke(
  { messages: [new HumanMessage("Look up my recent activity")] },
  { context: { userId: "user-123", sessionId: "abc" } },
);

import { createDeepAgent } from "deepagents";
import { tool } from "langchain";
import type { ToolRuntime } from "@langchain/core/tools";
import { z } from "zod";

const contextSchema = z.object({
  userId: z.string(),
  sessionId: z.string(),
});

const getUserData = tool(
  async (input, runtime: ToolRuntime<unknown, typeof contextSchema>) => {
    const userId = runtime.context?.userId;
    return `Data for user ${userId}: ${input.query}`;
  },
  {
    name: "get_user_data",
    description: "获取当前用户的数据",
    schema: z.object({ query: z.string() }),
  },
);

const researchSubagent = {
  name: "researcher",
  description: "为当前用户进行研究",
  systemPrompt: "你是一名研究助手。",
  tools: [getUserData],
};

const agent = createDeepAgent({
  model: "baseten:zai-org/GLM-5.2",
  subagents: [researchSubagent],
  contextSchema,
});

// 上下文会自动传递给研究员子代理及其工具
const result = await agent.invoke(
  { messages: [new HumanMessage("Look up my recent activity")] },
  { context: { userId: "user-123", sessionId: "abc" } },
);

import { createDeepAgent } from "deepagents";
import { tool } from "langchain";
import type { ToolRuntime } from "@langchain/core/tools";
import { z } from "zod";

const contextSchema = z.object({
  userId: z.string(),
  sessionId: z.string(),
});

const getUserData = tool(
  async (input, runtime: ToolRuntime<unknown, typeof contextSchema>) => {
    const userId = runtime.context?.userId;
    return `Data for user ${userId}: ${input.query}`;
  },
  {
    name: "get_user_data",
    description: "获取当前用户的数据",
    schema: z.object({ query: z.string() }),
  },
);

const researchSubagent = {
  name: "researcher",
  description: "为当前用户进行研究",
  systemPrompt: "你是一名研究助手。",
  tools: [getUserData],
};

const agent = createDeepAgent({
  model: "ollama:north-mini-code-1.0",
  subagents: [researchSubagent],
  contextSchema,
});

// 上下文会自动传递给研究员子代理及其工具
const result = await agent.invoke(
  { messages: [new HumanMessage("Look up my recent activity")] },
  { context: { userId: "user-123", sessionId: "abc" } },
);

每个子代理的上下文

所有子代理都接收相同的父上下文。要传递特定于某个子代理的配置，请在扁平的 context 映射中使用命名空间键（用子代理名称为键添加前缀，例如 researcher:max_depth），或者将这些设置建模为上下文类型上的单独字段：

import { tool } from "langchain";
import type { ToolRuntime } from "@langchain/core/tools";
import { z } from "zod";

const contextSchema = z.object({
  userId: z.string(),
  researcherMaxDepth: z.number().optional(),
  factCheckerStrictMode: z.boolean().optional(),
});

const verifyClaim = tool(
  async (input, runtime: ToolRuntime<unknown, typeof contextSchema>) => {
    const strictMode = runtime.context?.factCheckerStrictMode ?? false;
    if (strictMode) {
      return strictVerification(input.claim);
    }
    return basicVerification(input.claim);
  },
  {
    name: "verify_claim",
    description: "验证事实性声明",
    schema: z.object({ claim: z.string() }),
  },
);

识别哪个子代理调用了工具

当同一个工具在父代理和多个子代理之间共享时，您可以使用 lc_agent_name 元数据（与流式传输中使用的值相同）来确定是哪个代理发起了调用：

import { tool } from "langchain";
import type { ToolRuntime } from "@langchain/core/tools";
import { z } from "zod";

const sharedLookup = tool(
  async (input, runtime: ToolRuntime) => {
    const agentName = runtime.config?.metadata?.lc_agent_name;
    if (agentName === "fact-checker") {
      return strictLookup(input.query);
    }
    return generalLookup(input.query);
  },
  {
    name: "shared_lookup",
    description: "从各种来源查找信息",
    schema: z.object({ query: z.string() }),
  },
);

您可以结合两种模式——从 runtime.context 读取代理特定设置，并在分支工具行为时从 runtime.config 元数据读取 lc_agent_name。

import { tool } from "langchain";
import type { ToolRuntime } from "@langchain/core/tools";
import { z } from "zod";

const contextSchema = z.object({
  userId: z.string(),
  researcherMaxDepth: z.number().optional(),
  factCheckerStrictMode: z.boolean().optional(),
});

const flexibleSearch = tool(
  async (input, runtime: ToolRuntime<unknown, typeof contextSchema>) => {
    const agentName = runtime.config?.metadata?.lc_agent_name ?? "未知";
    const ctx = runtime.context;
    const maxResults =
      agentName === "researcher" ? (ctx?.researcherMaxDepth ?? 5) : 5;
    const includeRaw = false;

    return performSearch(input.query, { maxResults, includeRaw });
  },
  {
    name: "flexible_search",
    description: "使用智能体特定设置进行搜索",
    schema: z.object({ query: z.string() }),
  },
);

故障排除

子代理未被调用

问题：主代理试图自己完成工作而不是委派。 解决方案：

使描述更具体：

// ✅ 正确示例
const goodDescription = {
  name: "research-specialist",
  description:
    "使用网络搜索对特定主题进行深度研究。当你需要通过多次搜索获取详细信息时使用。",
};

// ❌ 错误示例
const badDescription = {
  name: "helper",
  description: "提供帮助",
};

指示主代理委派：

import { createDeepAgent } from "deepagents";

const agent = createDeepAgent({
  systemPrompt: `...你的指令...

  重要提示：对于复杂任务，请使用 task() 工具委托给你的子代理。
  这样可以保持你的上下文清晰，并改善结果。`,
  subagents: [
    {
      name: "research-agent",
      description: "进行研究工作",
      systemPrompt: "你是一个研究员。",
    },
  ],
});

上下文仍然膨胀

问题：尽管使用了子代理，上下文仍然填满。 解决方案：

指示子代理返回简洁结果：

const systemPrompt = `...

重要提示：仅返回必要的摘要。
请勿包含原始数据、中间搜索结果或详细的工具输出。
你的回复应控制在500字以内。`;

对大数据使用文件系统：

const filesystemPrompt = `当你收集到大量数据时：
1. 将原始数据保存到 /data/raw_results.txt
2. 处理并分析数据
3. 仅返回分析摘要

这有助于保持上下文整洁。`;

选择了错误的子代理

问题：主代理为任务调用了不合适的子代理。 解决方案：在描述中清晰地区分子代理：

const subagents = [
  {
    name: "quick-researcher",
    description:
      "用于简单的、快速的研究问题，需要 1-2 次搜索。当您需要基本事实或定义时使用。",
    systemPrompt: "您是快速研究员子代理。",
  },
  {
    name: "deep-researcher",
    description:
      "用于复杂的、深入的研究，需要多次搜索、综合和分析。用于全面报告。",
    systemPrompt: "您是深度研究员子代理。",
  },
];

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

​为什么要使用子代理？

​配置

​默认子代理

​在没有子代理的情况下运行

​自定义子代理

​SubAgent（基于字典）

​CompiledSubAgent

​使用 SubAgent

​使用 CompiledSubAgent

​动态子代理

​启用动态子代理

​触发动态编排

​与编码代理一起使用

​流式传输

​流式传输子代理进度

​LangSmith 追踪

​在 LangSmith 中按子代理过滤

​在 LangSmith UI 中过滤

​使用 SDK 以编程方式过滤

​结构化输出

​通用子代理

​覆盖通用子代理

​何时使用它

示例

​技能继承

​最佳实践

​编写清晰的描述

​保持系统提示详细

​最小化工具集

​按任务选择模型

​返回简洁的结果

​常见模式

​多个专业化子代理

​上下文管理

​每个子代理的上下文

​识别哪个子代理调用了工具

​故障排除

​子代理未被调用

​上下文仍然膨胀

​选择了错误的子代理

为什么要使用子代理？

配置

默认子代理

在没有子代理的情况下运行

自定义子代理

SubAgent（基于字典）

CompiledSubAgent

使用 SubAgent

使用 CompiledSubAgent

动态子代理

启用动态子代理

触发动态编排

与编码代理一起使用

流式传输

流式传输子代理进度

LangSmith 追踪

在 LangSmith 中按子代理过滤

在 LangSmith UI 中过滤

使用 SDK 以编程方式过滤

结构化输出

通用子代理

覆盖通用子代理

何时使用它

技能继承

最佳实践

编写清晰的描述

保持系统提示详细

最小化工具集

按任务选择模型

返回简洁的结果

常见模式

多个专业化子代理

上下文管理

每个子代理的上下文

识别哪个子代理调用了工具

故障排除

子代理未被调用

上下文仍然膨胀

选择了错误的子代理