在子代理架构中，一个中央主代理（通常称为主管）通过将子代理作为工具来调用，从而协调它们。主代理决定调用哪个子代理、提供什么输入以及如何组合结果。子代理是无状态的——它们不记得过去的交互，所有对话记忆都由主代理维护。这提供了上下文隔离：每个子代理调用都在一个干净的上下文窗口中工作，防止主对话中的上下文膨胀。
关键特性
- 集中式控制：所有路由都通过主代理
- 无直接用户交互：子代理将结果返回给主代理，而不是用户（尽管你可以在子代理中使用中断来允许用户交互）
- 通过工具调用子代理：子代理通过工具被调用
- 并行执行：主代理可以在单个回合中调用多个子代理
主管 vs. 路由器：主管代理（此模式）与路由器不同。主管是一个完整的代理，它维护对话上下文，并在多个回合中动态决定调用哪些子代理。路由器通常是一个单一的分类步骤，它将任务分派给代理，而不维护持续的对话状态。 何时使用
当你有多个不同的领域（例如，日历、电子邮件、CRM、数据库），子代理不需要直接与用户对话，或者你想要集中式的工作流控制时，可以使用子代理模式。对于只有少数几个工具的更简单情况，请使用单个代理。
需要在子代理中进行用户交互？ 虽然子代理通常将结果返回给主代理，而不是直接与用户对话，但你可以在子代理中使用中断来暂停执行并收集用户输入。当子代理在继续之前需要澄清或批准时，这很有用。主代理仍然是协调者，但子代理可以在任务中途从用户那里收集信息。 基本实现
核心机制是将子代理包装成一个主代理可以调用的工具：
from langchain.tools import tool
from langchain.agents import create_agent
# 创建一个子代理
subagent = create_agent(model="google_genai:gemini-3.1-pro-preview", tools=[...])
# 将其包装为一个工具
@tool("research", description="Research a topic and return findings")
def call_research_agent(query: str):
result = subagent.invoke({"messages": [{"role": "user", "content": query}]})
return result["messages"][-1].content
# 主代理，将子代理作为工具
main_agent = create_agent(model="google_genai:gemini-3.1-pro-preview", tools=[call_research_agent])
教程：使用子代理构建个人助手
了解如何使用子代理模式构建个人助手，其中中央主代理（主管）协调专门的工作者代理。
设计决策
在实现子代理模式时，你将做出几个关键的设计选择。此表总结了选项——每个选项都在下面的章节中详细讨论。
| 决策 | 选项 |
|---|
| 同步 vs. 异步 | 同步（阻塞） vs. 异步（后台） |
| 工具模式 | 每个代理一个工具 vs. 单一分派工具 |
| 子代理规格 | 系统提示 vs. 枚举约束 vs. 基于工具的发现（仅限单一分派工具） |
| 子代理输入 | 仅查询 vs. 完整上下文 |
| 子代理输出 | 子代理结果 vs. 完整对话历史 |
同步 vs. 异步
子代理执行可以是同步的（阻塞）或异步的（后台）。你的选择取决于主代理是否需要结果才能继续。
| 模式 | 主代理行为 | 适用于 | 权衡 |
|---|
| 同步 | 等待子代理完成 | 主代理需要结果才能继续 | 简单，但会阻塞对话 |
| 异步 | 在子代理后台运行时继续 | 独立任务，用户不应等待 | 响应迅速，但更复杂 |
不要与 Python 的 async/await 混淆。这里的“异步”意味着主代理启动一个后台作业（通常在单独的进程或服务中）并继续执行而不阻塞。
同步（默认）
默认情况下，子代理调用是同步的：主代理等待每个子代理完成后再继续。当主代理的下一步操作依赖于子代理的结果时，使用同步。
何时使用同步：
- 主代理需要子代理的结果来制定其响应
- 任务具有顺序依赖性（例如，获取数据 → 分析 → 响应）
- 子代理失败应阻塞主代理的响应
权衡：
- 实现简单——只需调用并等待
- 在所有子代理完成之前，用户看不到响应
- 长时间运行的任务会冻结对话
当子代理的工作是独立的——主代理不需要结果就能继续与用户对话时，使用异步执行。主代理启动一个后台作业并保持响应。
何时使用异步：
- 子代理工作独立于主对话流
- 用户应该能够在工作进行时继续聊天
- 你想并行运行多个独立任务
三工具模式：
- 启动作业：启动后台任务，返回一个作业 ID
- 检查状态：返回当前状态（待处理、运行中、已完成、失败）
- 获取结果：检索完成的结果
处理作业完成： 当作业完成时，你的应用程序需要通知用户。一种方法：显示一个通知，点击时发送一条 HumanMessage，如“检查 job_123 并总结结果。”
工有两种主要方式将子代理暴露为工具：
| 模式 | 适用于 | 权衡 |
|---|
| 每个代理一个工具 | 对每个子代理的输入/输出进行细粒度控制 | 设置更多，但可定制性更强 |
| 单一分派工具 | 许多代理、分布式团队、约定优于配置 | 组合更简单，但每个代理的定制性较少 |
每个代理一个工具
关键思想是将子代理包装成主代理可以调用的工具：
from langchain.tools import tool
from langchain.agents import create_agent
# 创建一个子代理
subagent = create_agent(model="...", tools=[...])
# 将其包装为一个工具 #
@tool("subagent_name", description="subagent_description")
def call_subagent(query: str):
result = subagent.invoke({"messages": [{"role": "user", "content": query}]})
return result["messages"][-1].content
# 主代理，将子代理作为工具 #
main_agent = create_agent(model="...", tools=[call_subagent])
单一分派工具
一种替代方法使用单个参数化工具来为独立任务调用临时子代理。与每个代理一个工具方法（其中每个子代理被包装为单独的工具）不同，这种方法使用基于约定的单一 task 工具：任务描述作为人类消息传递给子代理，子代理的最终消息作为工具结果返回。
当你想将代理开发分配给多个团队、需要将复杂任务隔离到单独的上下文窗口中、需要一种可扩展的方式来添加新代理而无需修改协调器，或者更喜欢约定而非自定义时，请使用此方法。这种方法以牺牲上下文工程的灵活性为代价，换取了代理组合的简单性和强大的上下文隔离。
关键特性：
- 单一任务工具：一个参数化工具，可以通过名称调用任何已注册的子代理
- 基于约定的调用：通过名称选择代理，任务作为人类消息传递，最终消息作为工具结果返回
- 团队分配：不同的团队可以独立开发和部署代理
- 代理发现：子代理可以通过系统提示（列出可用代理）或通过渐进式披露（通过工具按需加载代理信息）来发现
这种方法的一个有趣方面是，子代理可能具有与主代理完全相同的能力。在这种情况下，调用子代理主要是为了上下文隔离——允许复杂的多步骤任务在隔离的上下文窗口中运行，而不会使主代理的对话历史膨胀。子代理自主完成其工作，只返回一个简洁的摘要，使主线程保持专注和高效。
from langchain.tools import tool
from langchain.agents import create_agent
# 由不同团队开发的子代理
research_agent = create_agent(
model="gpt-5.4",
prompt="You are a research specialist..."
)
writer_agent = create_agent(
model="gpt-5.4",
prompt="You are a writing specialist..."
)
# 可用子代理的注册表
SUBAGENTS = {
"research": research_agent,
"writer": writer_agent,
}
@tool
def task(
agent_name: str,
description: str
) -> str:
"""为任务启动一个临时子代理。
可用代理：
- research: 研究和事实查找
- writer: 内容创作和编辑
"""
agent = SUBAGENTS[agent_name]
result = agent.invoke({
"messages": [
{"role": "user", "content": description}
]
})
return result["messages"][-1].content
# 主协调代理
main_agent = create_agent(
model="gpt-5.4",
tools=[task],
system_prompt=(
"You coordinate specialized sub-agents. "
"Available: research (fact-finding), "
"writer (content creation). "
"Use the task tool to delegate work."
),
)
上下文工程
控制主代理与其子代理之间的上下文流动：
| 类别 | 目的 | 影响 |
|---|
| 子代理规格 | 确保子代理在应该被调用时被调用 | 主代理路由决策 |
| 子代理输入 | 确保子代理能够使用优化的上下文良好执行 | 子代理性能 |
| 子代理输出 | 确保主管能够根据子代理结果采取行动 | 主代理性能 |
子代理规格
与子代理关联的名称和描述是主代理知道调用哪些子代理的主要方式。这些是提示杠杆——请谨慎选择。
- 名称：主代理如何引用子代理。保持清晰且面向行动（例如，
research_agent、code_reviewer）。
- 描述：主代理对子代理能力的了解。具体说明它处理哪些任务以及何时使用它。
对于单一分派工具设计，你必须额外向主代理提供有关它可以调用的子代理的信息。
你可以根据代理数量以及注册表是静态还是动态，以不同方式提供此信息：
| 方法 | 适用于 | 权衡 |
|---|
| 系统提示枚举 | 小型、静态代理列表（< 10 个代理） | 简单，但代理更改时需要更新提示 |
| 枚举约束 | 小型、静态代理列表（< 10 个代理） | 类型安全且明确，但代理更改时需要更改代码 |
| 基于工具的发现 | 大型或动态代理注册表 | 灵活且可扩展，但增加了复杂性 |
系统提示枚举
直接在主代理的系统提示中列出可用代理。主代理将代理列表及其描述视为其指令的一部分。
何时使用：
- 你有一个小型、固定的代理集（< 10）
- 代理注册表很少更改
- 你想要最简单的实现
示例：
main_agent = create_agent(
model="...",
tools=[task],
system_prompt=(
"You coordinate specialized sub-agents. "
"Available agents:\n"
"- research: Research and fact-finding\n"
"- writer: Content creation and editing\n"
"- reviewer: Code and document review\n"
"Use the task tool to delegate work."
),
)
分派工具上的枚举约束
在分派工具的 agent_name 参数上添加枚举约束。这提供了类型安全，并使可用代理在工具模式中明确。
何时使用：
- 你有一个小型、固定的代理集（< 10）
- 你想要类型安全和明确的代理名称
- 你更喜欢基于模式的验证，而不是基于提示的指导
示例：
from enum import Enum
class AgentName(str, Enum):
RESEARCH = "research"
WRITER = "writer"
REVIEWER = "reviewer"
@tool
def task(
agent_name: AgentName, # 枚举约束
description: str
) -> str:
"""为任务启动一个临时子代理。"""
# ...
基于工具的发现
提供一个单独的工具（例如，list_agents 或 search_agents），主代理可以调用它来按需发现可用代理。这支持渐进式披露并支持动态注册表。
何时使用：
- 你有许多代理（> 10）或一个不断增长的注册表
- 代理注册表频繁更改或是动态的
- 你想减少提示大小和令牌使用量
- 不同的团队独立管理不同的代理
示例：
@tool
def list_agents(query: str = "") -> str:
"""列出可用的子代理，可选择按查询过滤。"""
agents = search_agent_registry(query)
return format_agent_list(agents)
@tool
def task(agent_name: str, description: str) -> str:
"""为任务启动一个临时子代理。"""
# ...
main_agent = create_agent(
model="...",
tools=[task, list_agents],
system_prompt="Use list_agents to discover available subagents, then use task to invoke them."
)
子代理输入
自定义子代理接收的上下文以执行其任务。通过从代理的状态中提取，添加在静态提示中不实用捕获的输入——完整的消息历史、先前结果或任务元数据。
from langchain.agents import AgentState
from langchain.tools import tool, ToolRuntime
class CustomState(AgentState):
example_state_key: str
@tool(
"subagent1_name",
description="subagent1_description"
)
def call_subagent1(query: str, runtime: ToolRuntime[None, CustomState]):
# 应用任何需要的逻辑将消息转换为合适的输入
subagent_input = some_logic(query, runtime.state["messages"])
result = subagent1.invoke({
"messages": subagent_input,
# 你也可以根据需要在此传递其他状态键。
# 确保在主代理和子代理的状态模式中都定义了这些。
"example_state_key": runtime.state["example_state_key"]
})
return result["messages"][-1].content
子代理输出
自定义主代理接收回来的内容，以便它能做出好的决策。两种策略：
- 提示子代理：指定应该返回什么。一个常见的失败模式是子代理执行工具调用或推理，但没有在其最终消息中包含结果——提醒它主管只看到最终输出。
- 在代码中格式化：在返回之前调整或丰富响应。例如，除了最终文本外，使用
Command 传回特定的状态键。
from typing import Annotated
from langchain.agents import AgentState
from langchain.tools import InjectedToolCallId
from langgraph.types import Command
@tool(
"subagent1_name",
description="subagent1_description"
)
def call_subagent1(
query: str,
tool_call_id: Annotated[str, InjectedToolCallId],
) -> Command:
result = subagent1.invoke({
"messages": [{"role": "user", "content": query}]
})
return Command(update={
# 从子代理传回额外的状态
"example_state_key": result["example_state_key"],
"messages": [
ToolMessage(
content=result["messages"][-1].content,
tool_call_id=tool_call_id
)
]
})
检查点和状态检查
默认情况下，子代理使用继承的检查点模式——每次调用都从全新状态开始，支持中断，并安全地并行运行。如果你需要子代理在调用之间维护自己的持久对话历史，请使用 checkpointer=True（续接模式）编译它。有关模式的完整比较，请参阅子图持久化。
因为子代理是在工具函数内部调用的，LangGraph 无法静态发现它们。这意味着带有 subgraphs 的 get_state 不会返回子代理状态。如果你需要读取嵌套图状态（例如，在中断期间），请改为在自定义图中的节点函数中调用子代理。有关每种模式如何影响状态可见性的详细信息，请参阅子图持久化。
将这些文档连接到 Claude、VSCode 等，通过 MCP 获取实时答案。 
