跳到主要内容

文档索引

在以下地址获取完整的文档索引:https://docs.langchain.org.cn/llms.txt

在进一步探索之前,请使用此文件发现所有可用页面。

深度智能体可以创建子智能体来委托工作。您可以在 subagents 参数中指定自定义子智能体。子智能体对于上下文隔离(保持主智能体的上下文整洁)和提供专业指令非常有用。 本页介绍同步子智能体,其中监督者会阻塞直到子智能体完成。对于长时间运行的任务、并行工作流,或者需要中途控制和取消的情况,请参阅异步子智能体

为何使用子智能体?

子智能体解决了上下文膨胀问题。当智能体使用具有大量输出的工具(网络搜索、文件读取、数据库查询)时,上下文窗口会迅速被中间结果填满。子智能体隔离了这些详细工作——主智能体只接收最终结果,而不是产生结果的数十个工具调用。 何时使用子智能体:
  • ✅ 会使主智能体上下文混乱的多步骤任务
  • ✅ 需要自定义指令或工具的专业领域
  • ✅ 需要不同模型能力的任务
  • ✅ 当您希望主智能体专注于高层协调时
何时不使用子智能体
  • ❌ 简单的单步任务
  • ❌ 当您需要维护中间上下文时
  • ❌ 当开销大于收益时

配置

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

默认子智能体

除非您已经提供了一个同名的同步子智能体,否则深度智能体会自动添加一个同步的通用子智能体。
  • 要替换它,请传入您自己的名为通用的子智能体。
  • 要重命名或重新提示自动添加的版本,请在活跃的Harness配置文件上设置 general_purpose_subagent=GeneralPurposeSubagentProfile(...)
  • 要禁用它,请参阅下面的不使用子智能体运行

不使用子智能体运行

要运行不带task工具的智能体,请执行以下两项操作
  1. 在活跃的Harness配置文件上设置 general_purpose_subagent=GeneralPurposeSubagentProfile(enabled=False)
  2. create_deep_agent上通过subagents=不传入任何同步子智能体。
只有当至少存在一个同步子智能体时,深度智能体才会附加SubAgentMiddleware(和task工具)。如果既没有默认的子智能体也没有调用者提供的子智能体,智能体将不进行委托运行。 异步子智能体不受影响——它们通过自己的中间件和工具运行,如异步子智能体中所述。
此处不要使用excluded_middleware——SubAgentMiddleware是必需的支架,将其列出会导致ValueErrorgeneral_purpose_subagent.enabled = False是受支持的路径。

子智能体 (基于字典)

对于大多数用例,将子智能体定义为与SubAgent规范匹配的字典,包含以下字段
字段类型描述
名称str必需。子智能体的唯一标识符。主智能体在调用task()工具时使用此名称。子智能体名称成为AIMessage和流式传输的元数据,有助于区分不同的智能体。
descriptionstr必需。此子智能体的功能描述。请具体且面向行动。主智能体以此决定何时委托。
system_promptstr必需。子智能体的指令。自定义子智能体必须定义自己的指令。包括工具使用指南和输出格式要求。
不从主智能体继承。
toolslist[Callable]可选。子智能体可使用的工具。保持最小化,仅包含所需工具。
默认从主智能体继承。指定时,完全覆盖继承的工具。
modelstr | BaseChatModel可选。覆盖主智能体的模型。省略则使用主智能体的模型。
默认从主智能体继承。您可以传入模型标识符字符串,例如'openai:gpt-5.4'(使用'provider:model'格式),或LangChain聊天模型对象(init_chat_model("gpt-5.4")ChatOpenAI(model="gpt-5.4"))。
middlewarelist[Middleware]可选。用于自定义行为、日志记录或速率限制的额外中间件。
不从主智能体继承。
interrupt_ondict[str, bool]可选。配置特定工具的人机协作。子智能体的值覆盖主智能体。需要检查点。
默认从主智能体继承。子智能体的值覆盖默认值。
skillslist[str]可选。技能源路径。指定时,子智能体将从这些目录加载技能(例如,["/skills/research/", "/skills/web-search/"])。这允许子智能体拥有与主智能体不同的技能集。
不从主智能体继承。只有通用子智能体继承主智能体的技能。当子智能体拥有技能时,它会运行自己独立的SkillsMiddleware实例。技能状态完全隔离——子智能体加载的技能对父级不可见,反之亦然。
response_formatResponseFormat可选。子智能体的结构化输出Schema。设置后,父级将收到子智能体的结果作为JSON,而不是自由格式文本。接受Pydantic模型、ToolStrategy(...)ProviderStrategy(...)或原始Schema类型。请参阅结构化输出
permissionslist[FilesystemPermission]可选。子智能体的文件系统权限规则。设置后,将完全替换父智能体的权限。
默认从主智能体继承。
CLI 用户: 您也可以将子智能体定义为磁盘上的 AGENTS.md 文件,而不是在代码中。namedescriptionmodel 字段映射到 YAML frontmatter,而 Markdown 正文成为 system_prompt。有关文件格式,请参阅自定义子智能体部署用户: 将子智能体定义为 subagents/ 下的目录,每个目录都有自己的 deepagents.tomlAGENTS.md。打包器会自动发现它们。有关完整的配置参考,请参阅部署子智能体

编译子智能体

对于复杂的工作流程,可以使用预构建的LangGraph图作为CompiledSubAgent
字段类型描述
名称str必需。子智能体的唯一标识符。子智能体名称成为AIMessage和流式传输的元数据,有助于区分不同的智能体。
descriptionstr必需。此子智能体的功能。
runnableRunnable必需。一个编译过的LangGraph图(必须先调用.compile())。

使用子智能体

import os
from typing import Literal
from tavily import TavilyClient
from deepagents import create_deep_agent

tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])

def internet_search(
    query: str,
    max_results: int = 5,
    topic: Literal["general", "news", "finance"] = "general",
    include_raw_content: bool = False,
):
    """Run a web search"""
    return tavily_client.search(
        query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic,
    )

research_subagent = {
    "name": "research-agent",
    "description": "Used to research more in depth questions",
    "system_prompt": "You are a great researcher",
    "tools": [internet_search],
    "model": "openai:gpt-5.4",  # Optional override, defaults to main agent model
}
subagents = [research_subagent]

agent = create_deep_agent(
    model="claude-sonnet-4-6",
    subagents=subagents
)

使用编译子智能体

对于更复杂的用例,您可以使用CompiledSubAgent提供自定义子智能体。您可以使用LangChain的create_agent或使用图API创建自定义LangGraph图来创建自定义子智能体。 如果您正在创建自定义LangGraph图,请确保该图具有一个名为"messages"的状态键
from deepagents import create_deep_agent, CompiledSubAgent
from langchain.agents import create_agent

# Create a custom agent graph
custom_graph = create_agent(
    model=your_model,
    tools=specialized_tools,
    prompt="You are a specialized agent for data analysis..."
)

# Use it as a custom subagent
custom_subagent = CompiledSubAgent(
    name="data-analyzer",
    description="Specialized agent for complex data analysis tasks",
    runnable=custom_graph
)

subagents = [custom_subagent]

agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    tools=[internet_search],
    system_prompt=research_instructions,
    subagents=subagents
)

流式处理

在流式跟踪信息中,智能体名称以lc_agent_name的形式在元数据中可用。在审查跟踪信息时,您可以使用此元数据来区分数据来自哪个智能体。 以下示例创建了一个名为main-agent的深度智能体和一个名为research-agent的子智能体:
import os
from typing import Literal
from tavily import TavilyClient
from deepagents import create_deep_agent

tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])

def internet_search(
    query: str,
    max_results: int = 5,
    topic: Literal["general", "news", "finance"] = "general",
    include_raw_content: bool = False,
):
    """Run a web search"""
    return tavily_client.search(
        query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic,
    )

research_subagent = {
    "name": "research-agent",
    "description": "Used to research more in depth questions",
    "system_prompt": "You are a great researcher",
    "tools": [internet_search],
    "model": "google_genai:gemini-3.1-pro-preview",  # Optional override, defaults to main agent model
}
subagents = [research_subagent]

agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    subagents=subagents,
    name="main-agent"
)
当您提示深度智能体时,由子智能体或深度智能体执行的所有智能体运行都将在其元数据中包含智能体名称。在这种情况下,名为"research-agent"的子智能体将在任何相关的智能体运行元数据中包含{'lc_agent_name': 'research-agent'} LangSmith Example trace showing the metadata

结构化输出

子智能体支持结构化输出,因此父智能体接收的是可预测、可解析的JSON,而不是自由格式文本。
子智能体的结构化输出需要deepagents>=0.5.3
在子智能体配置上传递response_format。当子智能体完成时,其结构化响应将JSON序列化并作为ToolMessage内容返回给父智能体。该Schema接受create_agent支持的任何类型:Pydantic模型、ToolStrategy(...)ProviderStrategy(...)或原始Schema类型。请参阅结构化输出
from pydantic import BaseModel, Field

from deepagents import create_deep_agent


class ResearchFindings(BaseModel):
    """Structured findings from a research task."""
    summary: str = Field(description="Summary of findings")
    confidence: float = Field(description="Confidence score from 0 to 1")
    sources: list[str] = Field(description="List of source URLs")

research_subagent = {
    "name": "researcher",
    "description": "Researches topics and returns structured findings",
    "system_prompt": "Research the given topic thoroughly. Return your findings.",
    "tools": [web_search],
    "response_format": ResearchFindings,
}

agent = create_deep_agent(
    model="claude-sonnet-4-6",
    subagents=[research_subagent],
)

result = await agent.ainvoke(
    {"messages": [{"role": "user", "content": "Research recent advances in quantum computing"}]}
)

# The parent's ToolMessage contains JSON-serialized structured data:
# '{"summary": "...", "confidence": 0.87, "sources": ["https://..."]}'
如果没有response_format,父级将原样接收子智能体的最后一条消息文本。有了它,父级总是会获得与Schema匹配的有效JSON,这在父级需要以编程方式处理结果或将其传递给下游工具时非常有用。 有关Schema类型和策略(工具调用与提供者原生)的完整详细信息,请参阅结构化输出

通用子智能体

除了任何用户定义的子智能体之外,每个深度智能体始终都可以访问一个通用子智能体。此子智能体
  • 具有与主智能体相同的系统提示
  • 可以访问所有相同的工具
  • 使用相同的模型(除非被覆盖)
  • 从主智能体继承技能(当技能被配置时)

覆盖通用子智能体

在您的subagents列表中包含一个名为name="general-purpose"的子智能体来替换默认子智能体。使用此方法为通用子智能体配置不同的模型、工具或系统提示。
from deepagents import create_deep_agent

# Main agent uses Gemini; general-purpose subagent uses GPT
agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    tools=[internet_search],
    subagents=[
        {
            "name": "general-purpose",
            "description": "General-purpose agent for research and multi-step tasks",
            "system_prompt": "You are a general-purpose assistant.",
            "tools": [internet_search],
            "model": "openai:gpt-5.4",  # Different model for delegated tasks
        },
    ],
)
当您提供一个名为“通用”的子智能体时,默认的通用子智能体将不会被添加。您的规范将完全替换它。 要完全删除内置的通用子智能体而不是替换它,请将活跃的Harness配置文件的通用子智能体enabled标志设置为False

何时使用

通用子智能体非常适合上下文隔离而无需专业行为的场景。主智能体可以将复杂的多个步骤任务委托给这个子智能体,并获得简洁的结果,而不会因中间工具调用而导致上下文膨胀。

示例

主智能体不再进行10次网络搜索并用结果填充其上下文,而是委托给通用子智能体:task(name="general-purpose", task="Research quantum computing trends")。子智能体在内部执行所有搜索,并仅返回一个摘要。

技能继承

当使用create_deep_agent配置技能
  • 通用子智能体:自动继承主智能体的技能
  • 自定义子智能体:默认不继承技能——使用skills参数赋予它们自己的技能
只有配置了技能的子智能体才会获得SkillsMiddleware实例——没有skills参数的自定义子智能体则不会。当存在时,技能状态在两个方向上完全隔离:父级的技能对子级不可见,子级的技能也不会传播回父级。
from deepagents import create_deep_agent

# Research subagent with its own skills
research_subagent = {
    "name": "researcher",
    "description": "Research assistant with specialized skills",
    "system_prompt": "You are a researcher.",
    "tools": [web_search],
    "skills": ["/skills/research/", "/skills/web-search/"],  # Subagent-specific skills
}

agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    skills=["/skills/main/"],  # Main agent and GP subagent get these
    subagents=[research_subagent],  # Gets only /skills/research/ and /skills/web-search/
)

最佳实践

编写清晰的描述

主智能体使用描述来决定调用哪个子智能体。请具体: 好: "分析财务数据并生成具有置信度分数的投资见解" 差: "处理财务事务"

保持系统提示详细

包含关于如何使用工具和格式化输出的具体指导
research_subagent = {
    "name": "research-agent",
    "description": "Conducts in-depth research using web search and synthesizes findings",
    "system_prompt": """You are a thorough researcher. Your job is to:

    1. Break down the research question into searchable queries
    2. Use internet_search to find relevant information
    3. Synthesize findings into a comprehensive but concise summary
    4. Cite sources when making claims

    Output format:
    - Summary (2-3 paragraphs)
    - Key findings (bullet points)
    - Sources (with URLs)

    Keep your response under 500 words to maintain clean context.""",
    "tools": [internet_search],
}

最小化工具集

只赋予子智能体其所需的工具。这能提高专注度和安全性
# ✅ Good: Focused tool set
email_agent = {
    "name": "email-sender",
    "tools": [send_email, validate_email],  # Only email-related
}

# ❌ Bad: Too many tools
email_agent = {
    "name": "email-sender",
    "tools": [send_email, web_search, database_query, file_upload],  # Unfocused
}

按任务选择模型

不同模型擅长不同任务
subagents = [
    {
        "name": "contract-reviewer",
        "description": "Reviews legal documents and contracts",
        "system_prompt": "You are an expert legal reviewer...",
        "tools": [read_document, analyze_contract],
        "model": "google_genai:gemini-3.1-pro-preview",  # Large context for long documents
    },
    {
        "name": "financial-analyst",
        "description": "Analyzes financial data and market trends",
        "system_prompt": "You are an expert financial analyst...",
        "tools": [get_stock_price, analyze_fundamentals],
        "model": "openai:gpt-5.4",  # Better for numerical analysis
    },
]

返回简洁结果

指示子智能体返回摘要,而不是原始数据
data_analyst = {
    "system_prompt": """Analyze the data and return:
    1. Key insights (3-5 bullet points)
    2. Overall confidence score
    3. Recommended next actions

    Do NOT include:
    - Raw data
    - Intermediate calculations
    - Detailed tool outputs

    Keep response under 300 words."""
}

常见模式

多个专业子智能体

为不同领域创建专业子智能体
from deepagents import create_deep_agent

subagents = [
    {
        "name": "data-collector",
        "description": "Gathers raw data from various sources",
        "system_prompt": "Collect comprehensive data on the topic",
        "tools": [web_search, api_call, database_query],
    },
    {
        "name": "data-analyzer",
        "description": "Analyzes collected data for insights",
        "system_prompt": "Analyze data and extract key insights",
        "tools": [statistical_analysis],
    },
    {
        "name": "report-writer",
        "description": "Writes polished reports from analysis",
        "system_prompt": "Create professional reports from insights",
        "tools": [format_document],
    },
]

agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    system_prompt="You coordinate data analysis and reporting. Use subagents for specialized tasks.",
    subagents=subagents
)
工作流程
  1. 主智能体创建高层计划
  2. 将数据收集委托给数据收集器
  3. 将结果传递给数据分析器
  4. 将见解发送给报告撰写器
  5. 编译最终输出
每个子智能体都使用仅专注于其任务的干净上下文。

上下文管理

当您使用运行时上下文调用父智能体时,该上下文会自动传播到所有子智能体。每个子智能体运行都将收到您在父级invoke/ainvoke调用中传递的相同运行时上下文。 这意味着在任何子智能体内部运行的工具都可以访问您提供给父级的相同上下文值:
from dataclasses import dataclass

from deepagents import create_deep_agent
from langchain.messages import HumanMessage
from langchain.tools import tool, ToolRuntime

@dataclass
class Context:
    user_id: str
    session_id: str

@tool
def get_user_data(query: str, runtime: ToolRuntime[Context]) -> str:
    """Fetch data for the current user."""
    user_id = runtime.context.user_id
    return f"Data for user {user_id}: {query}"

research_subagent = {
    "name": "researcher",
    "description": "Conducts research for the current user",
    "system_prompt": "You are a research assistant.",
    "tools": [get_user_data],
}

agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    subagents=[research_subagent],
    context_schema=Context,
)

# Context flows to the researcher subagent and its tools automatically
result = await agent.invoke(
    {"messages": [HumanMessage("Look up my recent activity")]},
    context=Context(user_id="user-123", session_id="abc"),
)

每个子智能体的上下文

所有子智能体接收相同的父级上下文。要传递特定于某个子智能体的配置,请在平坦的context映射中使用命名空间键(以子智能体名称作为键的前缀,例如researcher:max_depth),或者将这些设置建模为上下文类型上的独立字段
from dataclasses import dataclass

from langchain.messages import HumanMessage
from langchain.tools import tool, ToolRuntime

@dataclass
class Context:
    user_id: str
    researcher_max_depth: int | None = None
    fact_checker_strict_mode: bool | None = None

result = await agent.invoke(
    {"messages": [HumanMessage("Research this and verify the claims")]},
    context=Context(
        user_id="user-123",
        researcher_max_depth=3,
        fact_checker_strict_mode=True,
    ),
)

@tool
def verify_claim(claim: str, runtime: ToolRuntime[Context]) -> str:
    """Verify a factual claim."""
    strict_mode = runtime.context.fact_checker_strict_mode or False
    if strict_mode:
        return strict_verification(claim)
    return basic_verification(claim)

识别哪个子智能体调用了工具

当父智能体和多个子智能体共享同一个工具时,您可以使用lc_agent_name元数据(与流式传输中使用的值相同)来确定是哪个智能体发起的调用。
from langchain.tools import tool, ToolRuntime

@tool
def shared_lookup(query: str, runtime: ToolRuntime) -> str:
    """Look up information."""
    agent_name = runtime.config.get("metadata", {}).get("lc_agent_name")
    if agent_name == "fact-checker":
        return strict_lookup(query)
    return general_lookup(query)
您可以结合这两种模式——从runtime.context读取智能体特定设置,并在工具行为分支时从runtime.config元数据读取lc_agent_name
from langchain.tools import tool, ToolRuntime

@tool
def flexible_search(query: str, runtime: ToolRuntime[Context]) -> str:
    """Search with agent-specific settings."""
    agent_name = runtime.config.get("metadata", {}).get("lc_agent_name", "unknown")
    ctx = runtime.context
    if agent_name == "researcher":
        max_results = ctx.researcher_max_depth or 5
    else:
        max_results = 5
    include_raw = False

    return perform_search(query, max_results=max_results, include_raw=include_raw)

故障排除

子智能体未被调用

问题:主智能体尝试自行完成工作而不是委托。 解决方案
  1. 使描述更具体
    # ✅ Good
    {"name": "research-specialist", "description": "Conducts in-depth research on specific topics using web search. Use when you need detailed information that requires multiple searches."}
    
    # ❌ Bad
    {"name": "helper", "description": "helps with stuff"}
    
  2. 指示主智能体进行委托
    agent = create_deep_agent(
        model="google_genai:gemini-3.1-pro-preview",
        system_prompt="""...your instructions...
    
        IMPORTANT: For complex tasks, delegate to your subagents using the task() tool.
        This keeps your context clean and improves results.""",
        subagents=[...]
    )
    

上下文仍然膨胀

问题:尽管使用了子智能体,上下文仍然被填满。 解决方案
  1. 指示子智能体返回简洁结果
    system_prompt="""...
    
    IMPORTANT: Return only the essential summary.
    Do NOT include raw data, intermediate search results, or detailed tool outputs.
    Your response should be under 500 words."""
    
  2. 对大数据使用文件系统
    system_prompt="""When you gather large amounts of data:
    1. Save raw data to /data/raw_results.txt
    2. Process and analyze the data
    3. Return only the analysis summary
    
    This keeps context clean."""
    

选择了错误的子智能体

问题:主智能体为任务调用了不合适的子智能体。 解决方案:在描述中清晰区分子智能体:
subagents = [
    {
        "name": "quick-researcher",
        "description": "For simple, quick research questions that need 1-2 searches. Use when you need basic facts or definitions.",
    },
    {
        "name": "deep-researcher",
        "description": "For complex, in-depth research requiring multiple searches, synthesis, and analysis. Use for comprehensive reports.",
    }
]
:::
© . This site is unofficial and not affiliated with LangChain, Inc.