交接

交接允许一个代理将任务委派给另一个代理。这在不同代理专门处理不同领域的情况下特别有用。例如，一个客户支持应用程序可能拥有专门处理订单状态、退款、常见问题解答等任务的代理。

交接在 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 在调用交接时提供一些数据。例如，想象一下与“升级代理”的交接。您可能需要提供一个原因，以便进行记录。

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。

默认情况下，runner 现在会将先前的对话记录折叠成单个助手摘要消息（参见 RunConfig.nest_handoff_history）。摘要将出现在一个 <CONVERSATION HISTORY> 块中，该块在同一运行期间发生多次交接时会不断追加新的对话轮次。您可以通过 RunConfig.handoff_history_mapper 提供您自己的映射函数，以替换生成的消息，而无需编写完整的 input_filter。默认行为仅在交接和运行都没有显式提供 input_filter 时适用，因此已经自定义有效负载的代码（包括此存储库中的示例）将保持其当前行为而无需更改。您可以通过将 nest_handoff_history=True 或 False 传递给 handoff(...) 来覆盖单个交接的嵌套行为，这将设置 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 时，这将自动从历史记录中删除所有工具。

交接

创建交接

基本用法

通过 handoff() 函数自定义交接

交接输入

输入过滤器

推荐提示词

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