交接架构中,行为根据状态动态变化。核心机制:工具更新跨轮次持久化的状态变量(例如 current_stepactive_agent),系统读取此变量来调整行为——应用不同的配置(系统提示、工具)或路由到不同的代理。此模式支持在不同的代理之间交接以及在单个代理内进行动态配置更改。
交接一词由 OpenAI 首创,用于使用工具调用(例如 transfer_to_sales_agent)在代理或状态之间转移控制权。

关键特征

  • 状态驱动行为:行为根据状态变量变化(例如 current_stepactive_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:
    """Transfer to the specialist agent."""
    return Command(
        update={
            "messages": [
                ToolMessage(
                    content="Transferred to specialist",
                    tool_call_id=runtime.tool_call_id    
                )
            ],
            "current_step": "specialist"  # Triggers behavior change
        }
    )
为什么包含 ToolMessage 当 LLM 调用工具时,它期望得到响应。具有匹配 tool_call_idToolMessage 完成此请求-响应循环——没有它,对话历史会变得格式不正确。每当交接工具更新消息时,这是必需的。
有关完整实现,请参阅下面的教程。

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

了解如何使用交接模式构建客户支持代理,其中单个代理在不同配置之间转换。

实现方法

有两种实现交接的方法:带有中间件的单个代理(具有动态配置的单个代理)或**多代理子图**(作为图形节点的独立代理)。

带有中间件的单个代理

单个代理根据状态改变其行为。中间件拦截每个模型调用并动态调整系统提示和可用工具。工具更新状态变量以触发转换:
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:
    """Record warranty status and transition to next step."""
    return Command(
        update={
            "messages": [
                ToolMessage(
                    content=f"Warranty status recorded: {status}",
                    tool_call_id=runtime.tool_call_id
                )
            ],
            "warranty_status": status,
            "current_step": "specialist"  # Update state to trigger transition
        }
    )
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):
    """Track which step is currently active."""
    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:
    """Record warranty status and transition to next step."""
    return Command(update={
        "messages": [
            ToolMessage(
                content=f"Warranty status recorded: {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:
    """Configure agent behavior based on current_step."""
    step = request.state.get("current_step", "triage")

    # 将步骤映射到其配置
    configs = {
        "triage": {
            "prompt": "Collect warranty information...",
            "tools": [record_warranty_status]
        },
        "specialist": {
            "prompt": "Provide solutions based on warranty: {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:
    """Transfer to the sales agent."""
    last_ai_message = next(
        msg for msg in reversed(runtime.state["messages"]) if isinstance(msg, AIMessage)
    )
    transfer_message = ToolMessage(
        content="Transferred to sales agent",
        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:
    """Transfer to the sales agent."""
    last_ai_message = next(
        msg for msg in reversed(runtime.state["messages"]) if isinstance(msg, AIMessage)
    )
    transfer_message = ToolMessage(
        content="Transferred to sales agent from support agent",
        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:
    """Transfer to the support agent."""
    last_ai_message = next(
        msg for msg in reversed(runtime.state["messages"]) if isinstance(msg, AIMessage)
    )
    transfer_message = ToolMessage(
        content="Transferred to support agent from sales agent",
        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="anthropic:claude-sonnet-4-20250514",
    tools=[transfer_to_support],
    system_prompt="You are a sales agent. Help with sales inquiries. If asked about technical issues or support, transfer to the support agent.",
)

support_agent = create_agent(
    model="anthropic:claude-sonnet-4-20250514",
    tools=[transfer_to_sales],
    system_prompt="You are a support agent. Help with technical issues. If asked about pricing or purchasing, transfer to the sales agent.",
)


# 4. 创建调用代理的代理节点
def call_sales_agent(state: MultiAgentState) -> Command:
    """Node that calls the sales agent."""
    response = sales_agent.invoke(state)
    return response


def call_support_agent(state: MultiAgentState) -> Command:
    """Node that calls the support agent."""
    response = support_agent.invoke(state)
    return response


# 5. 创建路由器,检查是否应该结束或继续
def route_after_agent(
    state: MultiAgentState,
) -> Literal["sales_agent", "support_agent", "__end__"]:
    """Route based on active_agent, or END if the agent finished without handoff."""
    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"]:
    """Route to the active agent based on state, default to sales 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": "Hi, I'm having trouble with my account login. Can you help?",
            }
        ]
    }
)

for msg in result["messages"]:
    msg.pretty_print()
对于大多数交接用例,使用带有中间件的单个代理——它更简单。只有在需要定制代理实现时(例如,一个本身是带有反思或检索步骤的复杂图形的节点)才使用多代理子图

上下文工程

使用子图交接时,您可以精确控制哪些消息在代理之间流动。这种精确性对于维护有效的对话历史和避免可能使下游代理混淆的上下文膨胀至关重要。有关此主题的更多信息,请参阅上下文工程 在交接期间处理上下文 在代理之间交接时,您需要确保对话历史保持有效。LLM 期望工具调用与其响应配对,因此在交接时使用 Command.PARENT 时,您必须同时包含:
  1. 包含工具调用的 AIMessage(触发交接的消息)
  2. 确认交接的 ToolMessage(该工具调用的响应)
如果没有这种配对,接收代理将看到不完整的对话,可能会产生错误或意外行为。 下面的示例假设只调用了交接工具(没有并行工具调用):
@tool
def transfer_to_sales(runtime: ToolRuntime) -> Command:
    # 获取触发此交接的 AI 消息
    last_ai_message = runtime.state["messages"][-1]

    # 创建一个工具响应来完成配对
    transfer_message = ToolMessage(
        content="Transferred to sales agent",
        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,
    )
为什么不传递所有子代理消息? 虽然您可以在交接中包含完整的子代理对话,但这通常会产生问题。接收代理可能因无关的内部推理而变得困惑,令牌成本也会不必要地增加。通过只传递交接对,您可以保持父图形的上下文专注于高级协调。如果接收代理需要额外上下文,考虑在 ToolMessage 内容中总结子代理的工作,而不是传递原始消息历史。
将控制权返回给用户 当将控制权返回给用户(结束代理的轮次)时,确保最终消息是 AIMessage。这维护了有效的对话历史,并向用户界面发出信号表明代理已完成其工作。

实现注意事项

在设计多代理系统时,请考虑:
  • 上下文过滤策略:每个代理会接收完整的对话历史、过滤的部分还是摘要?不同的代理可能根据其角色需要不同的上下文。
  • 工具语义:明确交接工具是否只更新路由状态或还执行副作用。例如,transfer_to_sales() 是否也应该创建支持工单,或者那应该是单独的操作?
  • 令牌效率:在上下文完整性和令牌成本之间取得平衡。随着对话变长,摘要和选择性上下文传递变得更加重要。