コンテンツにスキップ

ハンドオフ

ハンドオフは、あるエージェントが別のエージェントにタスクを委譲できる仕組みです。これは、異なるエージェントがそれぞれ別の分野に特化している状況で特に有用です。例えば、カスタマーサポートアプリでは、注文状況、払い戻し、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 を返す関数です。

いくつかの一般的なパターン（例えば履歴からすべてのツール呼び出しを除去するなど）は、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 が呼び出されたときに履歴からすべてのツールを自動的に除去します。

推奨プロンプト

LLM にハンドオフを正しく理解させるため、エージェントにハンドオフに関する情報を含めることを推奨します。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>.""",
)