ハンドオフ
ハンドオフは、ある エージェント が別の エージェント にタスクを委譲できる仕組みです。これは、異なる エージェント がそれぞれ異なる分野を専門としている状況で特に有用です。たとえば、カスタマーサポートアプリでは、注文状況、返金、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
: 次の エージェント が受け取る入力をフィルタリングできます。詳細は以下を参照してください。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
を返す関数です。
よくあるパターン(たとえば履歴からすべてのツール呼び出しを削除するなど)は、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
を呼び出して、推奨データをプロンプトに自動追加できます。