ハンドオフ
ハンドオフは、エージェントが他のエージェントにタスクを委任できる仕組みです。これは、異なるエージェントがそれぞれ異なる分野に特化しているシナリオで特に有用です。たとえば、カスタマーサポートアプリでは、注文状況、返金、FAQ などのタスクをそれぞれ専門に扱うエージェントが存在する場合があります。
ハンドオフは 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: 次のエージェントが受け取る入力をフィルタリングできます。詳細は下記をご覧ください。
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 を返す関数です。
よくあるパターン（たとえば履歴からすべてのツール呼び出しを削除するなど）は、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が呼び出されたときに履歴からすべてのツールが自動的に削除されます。
推奨プロンプト
LLM がハンドオフを正しく理解できるようにするため、エージェントにハンドオフに関する情報を含めることを推奨します。agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX で推奨されるプレフィックスを利用するか、agents.extensions.handoff_prompt.prompt_with_handoff_instructions を呼び出して、推奨データをプロンプトに自動追加できます。