任务转移

任务转移允许一个智能体将任务委派给另一个智能体。这在不同智能体专注于不同领域的场景中尤其有用。例如，一个客服应用可以有各自专门处理订单状态、退款、常见问题等任务的智能体。

在 LLM 看来，任务转移被表示为工具。因此，如果要转移到名为 Refund Agent 的智能体，工具名将是 transfer_to_refund_agent。

创建任务转移

所有智能体都有一个 handoffs 参数，它可以直接接收一个 Agent，或者接收一个用于自定义任务转移的 Handoff 对象。

你可以使用 Agents SDK 提供的 handoff() 函数创建任务转移。该函数允许你指定要转移到的智能体，并可选地提供覆盖项和输入过滤器。

基本用法

以下展示如何创建一个简单的任务转移：

from agents import Agent, handoff

billing_agent = Agent(name="Billing agent")
refund_agent = Agent(name="Refund agent")

# (1)!
triage_agent = Agent(name="Triage agent", handoffs=[billing_agent, handoff(refund_agent)])

你可以直接使用智能体（如 billing_agent），也可以使用 handoff() 函数。

通过 `handoff()` 函数自定义任务转移

handoff() 函数允许你进行自定义。

agent：要将任务转移至的智能体。
tool_name_override：默认使用 Handoff.default_tool_name()，解析为 transfer_to_<agent_name>。你可以覆盖它。
tool_description_override：覆盖 Handoff.default_tool_description() 提供的默认工具描述。
on_handoff：任务转移被调用时执行的回调函数。可用于在确认将要进行任务转移时立即启动数据获取等操作。该函数接收智能体上下文，并可选地接收 LLM 生成的输入。输入数据由 input_type 参数控制。
input_type：任务转移期望的输入类型（可选）。
input_filter：允许你过滤下一个智能体所接收的输入。详见下文。
is_enabled：任务转移是否启用。可以是布尔值或返回布尔值的函数，从而允许在运行时动态启用或禁用任务转移。

from agents import Agent, handoff, RunContextWrapper

def on_handoff(ctx: RunContextWrapper[None]):
    print("Handoff called")

agent = Agent(name="My agent")

handoff_obj = handoff(
    agent=agent,
    on_handoff=on_handoff,
    tool_name_override="custom_handoff_tool",
    tool_description_override="Custom description",
)

任务转移输入

在某些情况下，你希望 LLM 在调用任务转移时提供一些数据。例如，设想转移到一个“升级处理（Escalation）智能体”。你可能希望提供一个原因，以便记录。

from pydantic import BaseModel

from agents import Agent, handoff, RunContextWrapper

class EscalationData(BaseModel):
    reason: str

async def on_handoff(ctx: RunContextWrapper[None], input_data: EscalationData):
    print(f"Escalation agent called with reason: {input_data.reason}")

agent = Agent(name="Escalation agent")

handoff_obj = handoff(
    agent=agent,
    on_handoff=on_handoff,
    input_type=EscalationData,
)

输入过滤器

当发生任务转移时，就好像新智能体接管了对话，并可以看到整个先前的对话历史。如果你想改变这一点，可以设置一个 input_filter。输入过滤器是一个函数，它通过 HandoffInputData 接收现有输入，并且必须返回一个新的 HandoffInputData。

默认情况下，运行器会将先前的对话记录折叠为一条助理摘要消息（参见 RunConfig.nest_handoff_history）。该摘要位于一个 <CONVERSATION HISTORY> 块中，在同一次运行期间发生多次任务转移时会持续追加新的轮次。你可以通过 RunConfig.handoff_history_mapper 提供自己的映射函数来替换生成的消息，而无需编写完整的 input_filter。该默认行为仅在任务转移和运行都未提供显式的 input_filter 时生效，因此已自定义负载的现有代码（包括本仓库中的 code examples）无需更改即可保持当前行为。你可以通过向 handoff(...) 传入 nest_handoff_history=True 或 False 来覆盖单次任务转移的嵌套行为，这将设置 Handoff.nest_handoff_history。如果你只需要更改生成摘要的包装文本，请在运行智能体之前调用 set_conversation_history_wrappers（并可选调用 reset_conversation_history_wrappers）。

有一些常见模式（例如从历史记录中移除所有工具调用），已在 agents.extensions.handoff_filters 中为你实现。

from agents import Agent, handoff
from agents.extensions import handoff_filters

agent = Agent(name="FAQ agent")

handoff_obj = handoff(
    agent=agent,
    input_filter=handoff_filters.remove_all_tools, # (1)!
)

当调用 FAQ agent 时，这将自动从历史记录中移除所有工具。