OpenAI Agents SDK のエージェントが利用可能なハンドオフについての説明です。これはエージェントがタスクを別のエージェントに委任することを可能にします。

OpenAI Agents SDK : ハンドオフ

作成 : クラスキャット・セールスインフォメーション
作成日時 : 03/21/2025

* 本記事は openai.github.io/openai-agents-python の以下のページを独自に翻訳した上でまとめ直し、補足説明を加えています :

• Handoffs

* サンプルコードの動作確認はしておりますが、必要な場合には適宜、追加改変しています。
* ご自由にリンクを張って頂いてかまいませんが、sales-info@classcat.com までご一報いただけると嬉しいです。

 

 

 

OpenAI Agents SDK : ハンドオフ

ハンドオフはエージェントがタスクを別のエージェントに委任することを可能にします。これは、様々なエージェントが異なる領域を専門としているようなシナリオで特に役立ちます。例えば、顧客サポート app は、注文ステータス、払い戻し、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")


triage_agent = Agent(name="Triage agent", handoffs=[billing_agent, handoff(refund_agent)])

 

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: これは、次のエージェントにより受け取られる入力のフィルターを可能にします。See below for more.

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 がハンドオフを呼び出すとき何某かのデータを提供することを望むでしょう。例えば、”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,
)

 

入力フィルター

ハンドオフが発生すると、新しいエージェントが会話を引き継ぎ、以前の会話履歴全体を見れるようになります。これを変更したい場合、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, 
)

 

推奨プロンプト

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}
    .""",
)

以上