交接 (Handoffs)
交接 (Handoffs) 允許代理 (Agent) 將任務委派給其他代理。這在不同代理各自專精於不同領域的情境中特別有用。例如，一個客戶支援應用程式可能會有專門處理訂單狀態、退款、常見問題等任務的代理。
對於大型語言模型 (LLM) 來說，交接會被表示為一個工具 (Tool)。因此，如果有一個交接要給名為 Refund Agent 的代理，這個工具就會被稱為 transfer_to_refund_agent。
建立交接
所有代理 (Agent) 都有一個 [handoffs][agents.agent.Agent.handoffs] 參數，這個參數可以直接接受 Agent，或是一個可自訂 Handoff 的 Handoff 物件。
你可以使用 Agents SDK 提供的 [handoff()][agents.handoffs.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)])
- 你可以直接使用 agent（如
billing_agent），或是使用handoff()函式。
透過 handoff() 函式自訂交接（handoffs）
[handoff()][agents.handoffs.handoff] 函式讓你可以自訂相關行為。
agent：這是交接目標的 agent。tool_name_override：預設會使用Handoff.default_tool_name()函式，該函式會解析為transfer_to_<agent_name>。你可以自行覆寫這個行為。tool_description_override：覆寫來自Handoff.default_tool_description()的預設工具（Tool）描述。on_handoff：當交接被觸發時執行的 callback 函式。這在你得知交接即將發生時，想要立即啟動某些資料擷取等操作時非常有用。此函式會接收 agent context，並可選擇性地接收大型語言模型 (LLM) 產生的輸入。輸入資料由input_type參數控制。input_type：交接所預期的輸入型別（可選）。input_filter：可用來過濾下一個 agent 所接收的輸入。詳情請見下方說明。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",
)
交接 (Handoffs) 輸入
在某些情境下，您可能希望大型語言模型 (LLM) 在呼叫交接 (handoff) 時提供一些資料。例如，假設要交接給「升級處理代理 (Escalation 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,
)
輸入過濾器
當發生交接（handoff）時，就像是新的 Agent 接手對話，並且可以看到整個先前的對話歷史。如果你想要改變這個行為，你可以設定一個 [input_filter][agents.handoffs.Handoff.input_filter]。輸入過濾器（input filter）是一個函式，會透過 [HandoffInputData][agents.handoffs.HandoffInputData] 接收現有的輸入，並且必須回傳一個新的 HandoffInputData。
有一些常見的模式（例如從歷史紀錄中移除所有工具（Tools）呼叫），這些都已經在 [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時，這將自動從歷史紀錄中移除所有工具 (Tools)。
建議提示詞 (prompts)
為了確保大型語言模型 (LLM) 能正確理解交接 (Handoffs)，我們建議在你的代理 (Agents) 中加入有關交接的資訊。我們在 [agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX][] 中提供了建議的前綴詞，或者你也可以呼叫 [agents.extensions.handoff_prompt.prompt_with_handoff_instructions][]，自動將建議的資料加入你的提示詞 (prompts) 中。