交接/切换

交接/切换允许一个智能体将任务委托给另一个智能体。在不同智能体擅长不同领域的场景中，这特别有用。例如，一个客户支持应用程序可能有专门处理订单状态、退款、常见问题解答等任务的智能体。

交接/切换对大语言模型（LLM）来说是以工具的形式呈现。所以，如果要交接给一个名为“退款智能体”的智能体，该工具将被称为transfer_to_refund_agent。

创建交接/切换

所有智能体都有一个handoffs参数，它既可以直接接受一个Agent，也可以接受一个自定义交接/切换的Handoff对象。

你可以使用Agents SDK提供的handoff()函数来创建交接/切换。这个函数允许你指定要交接给的智能体，以及可选的覆盖和输入过滤器。

基本用法

以下是创建简单交接/切换的方法：

from agents import Agent, handoff

billing_agent = Agent(name="账单智能体")
refund_agent = Agent(name="退款智能体")


# (1)!
triage_agent = Agent(name="分诊智能体", handoffs=[billing_agent, handoff(refund_agent)])

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

通过 `handoff()` 函数自定义交接/切换

handoff() 函数可用于自定义相关内容。 - agent：这是交接/切换的目标 agent。 - tool_name_override：默认情况下，使用 Handoff.default_tool_name() 函数，其解析结果为 transfer_to_<agent_name>。你可以覆盖此默认值。 - tool_description_override：覆盖 Handoff.default_tool_description() 的默认工具描述。 - on_handoff：调用交接/切换时执行的回调函数。这对于诸如一旦知道调用交接/切换就立即启动某些数据获取等操作很有用。此函数接收 agent 上下文，也可以选择接收 LLM 生成的输入。输入数据由 input_type 参数控制。 - input_type：交接/切换所需的输入类型（可选）。 - input_filter：这使你可以过滤下一个 agent 接收的输入。更多内容见下文。

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 在调用交接/切换时提供一些数据。例如，假设交接/切换到 “升级 agent”。你可能希望提供一个原因，以便进行记录。

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,
)

输入过滤器

发生交接/切换时，就好像新的 agent 接管了对话，并能看到整个之前的对话历史记录。如果你想改变这种情况，可以设置一个 input_filter。输入过滤器是一个函数，它通过 HandoffInputData 接收现有输入，并且必须返回一个新的 HandoffInputData。

有一些常见模式（例如从历史记录中删除所有工具调用），已在 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”时，这将自动从历史记录中删除所有工具。