交接 - Docs by LangChain

在交接架构中，行为基于状态动态变化。核心机制是：工具更新一个状态变量（例如 current_step 或 active_agent），该变量在各轮之间持久化，系统读取此变量来调整行为——要么应用不同的配置（系统提示词、工具），要么路由到不同的智能体。此模式支持不同智能体之间的交接以及单个智能体内的动态配置变更。

交接一词由 OpenAI 创造，指使用工具调用（例如 transfer_to_sales_agent）在智能体或状态之间转移控制。

关键特征

状态驱动行为：行为基于状态变量变化（例如 current_step 或 active_agent）
基于工具的转换：工具更新状态变量以在状态之间移动
直接用户交互：每个状态的配置直接处理用户消息
持久化状态：状态在对话轮次间保持

何时使用

当你需要强制执行顺序约束（只有在满足前置条件后才解锁能力）、智能体需要在不同状态下直接与用户对话，或者你正在构建多阶段对话流时，请使用交接模式。此模式对于需要按特定顺序收集信息的客户支持场景特别有价值——例如，在处理退款之前收集保修 ID。

基本实现

核心机制是一个工具返回 Command 来更新状态，触发到新步骤或智能体的转换：

from langchain.tools import tool
from langchain.messages import ToolMessage
from langgraph.types import Command

@tool
def transfer_to_specialist(runtime) -> Command:
    """转交给专家智能体。"""
    return Command(
        update={
            "messages": [
                ToolMessage(
                    content="已转交给专家",
                    tool_call_id=runtime.tool_call_id  
                )
            ],
            "current_step": "specialist"  # 触发行为变更
        }
    )

为什么要包含 ToolMessage？ 当 LLM 调用工具时，它期望一个响应。带有匹配 tool_call_id 的 ToolMessage 完成了这个请求-响应周期——没有它，对话历史将变得格式错误。当你的交接工具更新消息时，这是必需的。

完整实现请参阅下面的教程。

教程：使用交接构建客户支持

学习如何使用交接模式构建客户支持智能体，其中单个智能体在不同配置之间转换。

实现方式

有两种实现交接的方式：使用中间件的单智能体（一个具有动态配置的智能体）或**多智能体子图**（作为图节点的不同智能体）。

使用中间件的单智能体

单个智能体基于状态改变其行为。中间件拦截每次模型调用并动态调整系统提示词和可用工具。工具更新状态变量以触发转换：

from langchain.tools import ToolRuntime, tool
from langchain.messages import ToolMessage
from langgraph.types import Command

@tool
def record_warranty_status(
    status: str,
    runtime: ToolRuntime[None, SupportState]
) -> Command:
    """记录保修状态并转换到下一步。"""
    return Command(
        update={
            "messages": [
                ToolMessage(
                    content=f"保修状态已记录：{status}",
                    tool_call_id=runtime.tool_call_id
                )
            ],
            "warranty_status": status,
            "current_step": "specialist"  # 更新状态以触发转换
        }
    )

完整示例：使用中间件的客户支持

from langchain.agents import AgentState, create_agent
from langchain.agents.middleware import wrap_model_call, ModelRequest, ModelResponse
from langchain.tools import tool, ToolRuntime
from langchain.messages import ToolMessage
from langgraph.types import Command
from typing import Callable

# 1. 定义带有 current_step 跟踪器的状态
class SupportState(AgentState):
    """跟踪当前活跃的步骤。"""
    current_step: str = "triage"
    warranty_status: str | None = None

# 2. 工具通过 Command 更新 current_step
@tool
def record_warranty_status(
    status: str,
    runtime: ToolRuntime[None, SupportState]
) -> Command:
    """记录保修状态并转换到下一步。"""
    return Command(update={
        "messages": [
            ToolMessage(
                content=f"保修状态已记录：{status}",
                tool_call_id=runtime.tool_call_id
            )
        ],
        "warranty_status": status,
        # 转换到下一步
        "current_step": "specialist"
    })

# 3. 中间件根据 current_step 应用动态配置
@wrap_model_call
def apply_step_config(
    request: ModelRequest,
    handler: Callable[[ModelRequest], ModelResponse]
) -> ModelResponse:
    """根据 current_step 配置智能体行为。"""
    step = request.state.get("current_step", "triage")

    # 将步骤映射到其配置
    configs = {
        "triage": {
            "prompt": "收集保修信息...",
            "tools": [record_warranty_status]
        },
        "specialist": {
            "prompt": "根据保修状态提供解决方案：{warranty_status}",
            "tools": [provide_solution, escalate]
        }
    }

    config = configs[step]
    request = request.override(
        system_prompt=config["prompt"].format(**request.state),
        tools=config["tools"]
    )
    return handler(request)

# 4. 创建带中间件的智能体
agent = create_agent(
    model,
    tools=[record_warranty_status, provide_solution, escalate],
    state_schema=SupportState,
    middleware=[apply_step_config],
    checkpointer=InMemorySaver()  # 跨轮次持久化状态  #
)

多智能体子图

多个不同的智能体作为图中的独立节点存在。交接工具使用 Command.PARENT 导航到不同的智能体节点，指定接下来执行哪个节点。

子图交接需要仔细的**上下文工程**。与单智能体中间件（消息历史自然流动）不同，你必须明确决定哪些消息在智能体之间传递。如果处理不当，智能体会收到格式错误的对话历史或膨胀的上下文。请参阅下面的上下文工程。

from langchain.messages import AIMessage, ToolMessage
from langchain.tools import tool, ToolRuntime
from langgraph.types import Command

@tool
def transfer_to_sales(
    runtime: ToolRuntime,
) -> Command:
    """转交给销售智能体。"""
    last_ai_message = next(
        msg for msg in reversed(runtime.state["messages"]) if isinstance(msg, AIMessage)
    )
    transfer_message = ToolMessage(
        content="已转交给销售智能体",
        tool_call_id=runtime.tool_call_id,
    )
    return Command(
        goto="sales_agent",
        update={
            "active_agent": "sales_agent",
            "messages": [last_ai_message, transfer_message],
        },
        graph=Command.PARENT
    )

完整示例：使用交接的销售和支持

此示例展示了一个具有独立销售和支持智能体的多智能体系统。每个智能体是一个独立的图节点，交接工具允许智能体将对话转移给彼此。

from typing import Literal

from langchain.agents import AgentState, create_agent
from langchain.messages import AIMessage, ToolMessage
from langchain.tools import tool, ToolRuntime
from langgraph.graph import StateGraph, START, END
from langgraph.types import Command
from typing_extensions import NotRequired


# 1. 定义带有 active_agent 跟踪器的状态
class MultiAgentState(AgentState):
    active_agent: NotRequired[str]


# 2. 创建交接工具
@tool
def transfer_to_sales(
    runtime: ToolRuntime,
) -> Command:
    """转交给销售智能体。"""
    last_ai_message = next(
        msg for msg in reversed(runtime.state["messages"]) if isinstance(msg, AIMessage)
    )
    transfer_message = ToolMessage(
        content="已从支持智能体转交给销售智能体",
        tool_call_id=runtime.tool_call_id,
    )
    return Command(
        goto="sales_agent",
        update={
            "active_agent": "sales_agent",
            "messages": [last_ai_message, transfer_message],
        },
        graph=Command.PARENT,
    )


@tool
def transfer_to_support(
    runtime: ToolRuntime,
) -> Command:
    """转交给支持智能体。"""
    last_ai_message = next(
        msg for msg in reversed(runtime.state["messages"]) if isinstance(msg, AIMessage)
    )
    transfer_message = ToolMessage(
        content="已从销售智能体转交给支持智能体",
        tool_call_id=runtime.tool_call_id,
    )
    return Command(
        goto="support_agent",
        update={
            "active_agent": "support_agent",
            "messages": [last_ai_message, transfer_message],
        },
        graph=Command.PARENT,
    )


# 3. 创建带交接工具的智能体
sales_agent = create_agent(
    model="google_genai:gemini-3.1-pro-preview",
    tools=[transfer_to_support],
    system_prompt="你是一个销售智能体。帮助处理销售咨询。如果被问到技术问题或支持，转交给支持智能体。",
)

support_agent = create_agent(
    model="google_genai:gemini-3.1-pro-preview",
    tools=[transfer_to_sales],
    system_prompt="你是一个支持智能体。帮助处理技术问题。如果被问到定价或购买，转交给销售智能体。",
)


# 4. 创建调用智能体的节点
def call_sales_agent(state: MultiAgentState) -> Command:
    """调用销售智能体的节点。"""
    response = sales_agent.invoke(state)
    return response


def call_support_agent(state: MultiAgentState) -> Command:
    """调用支持智能体的节点。"""
    response = support_agent.invoke(state)
    return response


# 5. 创建检查是否应结束或继续的路由器
def route_after_agent(
    state: MultiAgentState,
) -> Literal["sales_agent", "support_agent", "__end__"]:
    """根据 active_agent 路由，如果智能体完成且无交接则结束。"""
    messages = state.get("messages", [])

    # 检查最后一条消息 - 如果是没有工具调用的 AIMessage，则结束
    if messages:
        last_msg = messages[-1]
        if isinstance(last_msg, AIMessage) and not last_msg.tool_calls:
            return "__end__"

    # 否则路由到活跃的智能体
    active = state.get("active_agent", "sales_agent")
    return active if active else "sales_agent"


def route_initial(
    state: MultiAgentState,
) -> Literal["sales_agent", "support_agent"]:
    """根据状态路由到活跃智能体，默认为销售智能体。"""
    return state.get("active_agent") or "sales_agent"


# 6. 构建图
builder = StateGraph(MultiAgentState)
builder.add_node("sales_agent", call_sales_agent)
builder.add_node("support_agent", call_support_agent)

# 根据初始 active_agent 进行条件路由
builder.add_conditional_edges(START, route_initial, ["sales_agent", "support_agent"])

# 每个智能体之后，检查是否应结束或路由到另一个智能体
builder.add_conditional_edges(
    "sales_agent", route_after_agent, ["sales_agent", "support_agent", END]
)
builder.add_conditional_edges(
    "support_agent", route_after_agent, ["sales_agent", "support_agent", END]
)

graph = builder.compile()
result = graph.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "你好，我登录账号时遇到了问题。你能帮忙吗？",
            }
        ]
    }
)

for msg in result["messages"]:
    msg.pretty_print()

大多数交接用例使用使用中间件的单智能体——它更简单。只有当你需要定制的智能体实现（例如，一个本身就是包含反思或检索步骤的复杂图的节点）时，才使用多智能体子图。

上下文工程

使用子图交接时，你可以精确控制哪些消息在智能体之间流动。这种精确性对于维护有效的对话历史和避免可能混淆下游智能体的上下文膨胀至关重要。有关此主题的更多信息，请参阅上下文工程。 交接期间的上下文处理 在智能体之间交接时，你需要确保对话历史保持有效。LLM 期望工具调用与其响应配对，因此当使用 Command.PARENT 交接给另一个智能体时，你必须同时包含：

包含工具调用的 AIMessage（触发交接的消息）
确认交接的 ToolMessage（对该工具调用的人工响应）

没有这种配对，接收智能体将看到不完整的对话并可能产生错误或意外行为。以下示例假设只调用了交接工具（没有并行工具调用）：

@tool
def transfer_to_sales(runtime: ToolRuntime) -> Command:
    # 获取触发此交接的 AI 消息
    last_ai_message = runtime.state["messages"][-1]

    # 创建人工工具响应以完成配对
    transfer_message = ToolMessage(
        content="已转交给销售智能体",
        tool_call_id=runtime.tool_call_id,
    )

    return Command(
        goto="sales_agent",
        update={
            "active_agent": "sales_agent",
            # 只传递这两条消息，而不是完整的子智能体历史
            "messages": [last_ai_message, transfer_message],
        },
        graph=Command.PARENT,
    )

为什么不传递所有子智能体消息？ 虽然你可以在交接中包含完整的子智能体对话，但这通常会造成问题。接收智能体可能会被不相关的内部推理混淆，Token 成本也会不必要地增加。通过只传递交接配对，你可以让父图的上下文专注于高级协调。如果接收智能体需要额外上下文，请考虑在 ToolMessage 内容中总结子智能体的工作，而不是传递原始消息历史。

将控制权返回给用户 当将控制权返回给用户（结束智能体的轮次）时，确保最后一条消息是 AIMessage。这维护了有效的对话历史，并向用户界面发出智能体已完成工作的信号。

实现考虑

在设计多智能体系统时，请考虑：

上下文过滤策略：每个智能体是否接收完整的对话历史、过滤后的部分还是摘要？不同的智能体可能根据其角色需要不同的上下文。
工具语义：明确交接工具是否只更新路由状态还是也执行副作用。例如，transfer_to_sales() 是否还应该创建支持工单，还是应该作为单独的操作？
Token 效率：在上下文完整性和 Token 成本之间取得平衡。随着对话变长，摘要和选择性上下文传递变得越来越重要。

通过 MCP 连接这些文档到 Claude、VSCode 等，获取实时答案。

在 GitHub 上编辑此页面或提交 issue。

Documentation Index

​关键特征

​何时使用

​基本实现

教程：使用交接构建客户支持

​实现方式

​使用中间件的单智能体

​多智能体子图

​上下文工程

​实现考虑

关键特征

何时使用

基本实现

实现方式

使用中间件的单智能体

多智能体子图

上下文工程

实现考虑