コンテンツにスキップ

ハンドオフ

ハンドオフは、ある エージェント が別の エージェント にタスクを委譲できるようにするものです。これは、異なる エージェント がそれぞれ別の分野を専門とするシナリオで特に有用です。たとえば、カスタマーサポートアプリでは、注文状況、返金、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)])
  1. 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 を返す関数です。

既定では、ランナーは前の書き起こしを 1 つのアシスタント要約メッセージに折りたたみます（RunConfig.nest_handoff_history を参照）。この要約は、同一の実行中に複数回のハンドオフが発生した場合に新しいターンが追記される <CONVERSATION HISTORY> ブロック内に表示されます。完全な input_filter を書かずに生成されたメッセージを置き換えるには、RunConfig.handoff_history_mapper を指定して独自のマッピング関数を提供できます。既定は、ハンドオフ側と実行側のいずれも明示的な input_filter を提供しない場合にのみ適用されるため、既にペイロードをカスタマイズしている既存のコード（このリポジトリの code examples を含む）は変更なしで現在の動作を維持します。単一のハンドオフについてネスト動作を上書きしたい場合は、handoff(...) に nest_handoff_history=True または False を渡して、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)!
)
  1. これは、FAQ agent が呼び出されたときに、履歴からすべてのツールを自動的に削除します。

推奨プロンプト

LLMs がハンドオフを正しく理解できるようにするため、エージェント にハンドオフに関する情報を含めることを推奨します。agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX に推奨のプレフィックスがあり、または agents.extensions.handoff_prompt.prompt_with_handoff_instructions を呼び出して、推奨データをプロンプトに自動的に追加できます。

from agents import Agent
from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX

billing_agent = Agent(
    name="Billing agent",
    instructions=f"""{RECOMMENDED_PROMPT_PREFIX}
    <Fill in the rest of your prompt here>.""",
)