ハンドオフ
ハンドオフを使うと、エージェントは会話の一部を別のエージェントに委譲できます。これは、エージェントごとに専門分野が異なる場合に便利です。たとえば、カスタマーサポートアプリでは、予約、返金、よくある質問をそれぞれ担当するエージェントを用意できます。
ハンドオフは LLM に対してツールとして提示されます。Refund Agent という名前のエージェントにハンドオフする場合、ツール名は transfer_to_refund_agent になります。
専門エージェントが会話を引き継ぐべきだと判断したら、エージェントに続けてこのページをお読みください。専門エージェントが元のエージェントの背後で処理を担当すべき場合は、代わりにツールに記載されている agents as tools を使用してください。
ハンドオフの作成
Section titled “ハンドオフの作成”すべてのエージェントは handoffs オプションを受け付けます。このオプションには、ほかの Agent インスタンスや、handoff() ヘルパーが返す Handoff オブジェクトを含められます。
Agent インスタンスをそのまま渡すと、その handoffDescription(指定されている場合)がデフォルトのツールの説明に追加されます。これを使って、モデルがそのハンドオフを選択すべき状況を明確にしてください。
基本的な使い方
Section titled “基本的な使い方”import { Agent, handoff } from '@openai/agents';
const billingAgent = new Agent({ name: 'Billing agent' });const refundAgent = new Agent({ name: 'Refund agent' });
// Use Agent.create method to ensure the finalOutput type considers handoffsconst triageAgent = Agent.create({ name: 'Triage agent', handoffs: [billingAgent, handoff(refundAgent)],});handoff() によるハンドオフのカスタマイズ
Section titled “handoff() によるハンドオフのカスタマイズ”handoff() 関数を使うと、生成されるツールを調整できます。
agent– ハンドオフ先のエージェントtoolNameOverride– デフォルトのツール名transfer_to_<agent_name>の上書きtoolDescriptionOverride– デフォルトのツールの説明の上書きonHandoff– ハンドオフ発生時のコールバック。RunContextと、inputTypeが設定されている場合は解析済みのハンドオフペイロードを受け取ります。inputType– ハンドオフのツール呼び出し引数のスキーマinputFilter– 次のエージェントに渡す履歴のフィルターisEnabled– 条件に一致する実行でのみハンドオフを公開するための真偽値または述語関数
handoff() ヘルパーは、渡された特定の agent に常に制御を移します。移譲先の候補が複数ある場合は、移譲先ごとにハンドオフを登録し、モデルに選択させてください。呼び出し時に独自のハンドオフコードで返すエージェントを決定する必要がある場合は、カスタムの Handoff を使用してください。
import { z } from 'zod';import { Agent, handoff, RunContext } from '@openai/agents';
const FooSchema = z.object({ foo: z.string() });
function onHandoff(ctx: RunContext, input?: { foo: string }) { console.log('Handoff called with:', input?.foo);}
const agent = new Agent({ name: 'My agent' });
const handoffObj = handoff(agent, { onHandoff, inputType: FooSchema, toolNameOverride: 'custom_handoff_tool', toolDescriptionOverride: 'Custom description',});ハンドオフの入力
Section titled “ハンドオフの入力”モデルがハンドオフを選択するときに、小さな構造化ペイロードを付加させたい場合があります。その場合は、inputType と onHandoff を併せて定義してください。
import { z } from 'zod';import { Agent, handoff, RunContext } from '@openai/agents';
const EscalationData = z.object({ reason: z.string() });type EscalationData = z.infer<typeof EscalationData>;
async function onHandoff( ctx: RunContext<EscalationData>, input: EscalationData | undefined,) { console.log(`Escalation agent called with reason: ${input?.reason}`);}
const agent = new Agent<EscalationData>({ name: 'Escalation agent' });
const handoffObj = handoff(agent, { onHandoff, inputType: EscalationData,});inputType は、ハンドオフのツール呼び出し自体の引数を記述します。SDK はそのスキーマをハンドオフツールの parameters としてモデルに公開し、返された引数をローカルで解析して、解析済みの値を onHandoff に渡します。
isEnabled は、モデルがハンドオフの引数を返す前に、SDK がモデルで利用可能なハンドオフを準備する段階で評価されます。そのため、引数付きのハンドオフでは、引数内の値に基づく認可を行えません。認可が解析済みのフィールドに依存する場合は、アプリケーションに副作用が生じる前に、onHandoff の冒頭でチェックしてください。認可に失敗した場合は、リターンするのではなく例外をスローしてください。SDK は onHandoff が正常にリターンした後に制御の移譲を続行します。ツール入力ガードレールは関数ツールに適用され、ハンドオフには適用されません。
このペイロードは、次のエージェントのメイン入力を置き換えるものではなく、別の移譲先を選択するものでもありません。handoff() ヘルパーは、引き続きラップした特定のエージェントに制御を移し、受け取るエージェントは、inputFilter で変更しない限り会話履歴を参照します。
inputType は RunContext とも別のものです。ローカルですでに保持しているアプリケーションの状態や依存関係ではなく、モデルがハンドオフ時に決定するメタデータに使用してください。
inputType の使用場面
Section titled “inputType の使用場面”ハンドオフに reason、language、priority、summary など、モデルが生成する少量のルーティング用メタデータが必要な場合は、inputType を使用してください。たとえば、トリアージエージェントは { reason: 'duplicate_charge', priority: 'high' } を添えて返金エージェントにハンドオフでき、onHandoff は返金エージェントが引き継ぐ前にそのメタデータをログに記録したり、永続化したりできます。
目的が異なる場合は、別の仕組みを選択してください。
- 既存のアプリケーションの状態は
RunContextに格納してください。 - 受け取るエージェントに見せる履歴を変更したい場合は、
inputFilterを使用してください。 - 専門エージェントの候補が複数ある場合は、移譲先ごとにハンドオフを登録してください。
inputTypeは選択されたハンドオフにメタデータを追加できますが、移譲先の振り分けは行いません。 onHandoffの実行前に SDK で解析済みペイロードを検証したい場合は、Zod スキーマまたはサポートされている Standard Schema の値を優先して使用してください。元の JSON Schema は、モデルに送信するツールの仕様を定義するだけです。Standard Schema の例については、スキーマ検証を参照してください。
入力フィルター
Section titled “入力フィルター”デフォルトでは、ハンドオフは会話履歴全体を受け取ります。次のエージェントに渡す内容を変更するには、inputFilter を指定してください。よく使われるヘルパーは @openai/agents-core/extensions にあります。
import { Agent, handoff } from '@openai/agents';import { removeAllTools } from '@openai/agents-core/extensions';
const agent = new Agent({ name: 'FAQ agent' });
const handoffObj = handoff(agent, { inputFilter: removeAllTools,});inputFilter は HandoffInputData オブジェクトを受け取り、返します。
inputHistory– 実行開始前の入力履歴preHandoffItems– ハンドオフが発生したターンより前に生成された項目newItems– ハンドオフの呼び出し・出力の項目を含む、現在のターンで生成された項目runContext– 現在の実行コンテキスト
Runner に handoffInputFilter も設定している場合、そのハンドオフでは、ハンドオフごとの inputFilter が優先されます。
推奨プロンプト
Section titled “推奨プロンプト”プロンプトでハンドオフについて言及すると、LLM はより確実に応答します。SDK は RECOMMENDED_PROMPT_PREFIX を通じて推奨のプレフィックスを提供します。
import { Agent } from '@openai/agents';import { RECOMMENDED_PROMPT_PREFIX } from '@openai/agents-core/extensions';
const billingAgent = new Agent({ name: 'Billing agent', instructions: `${RECOMMENDED_PROMPT_PREFIX}Fill in the rest of your prompt here.`,});- エージェント:マネージャーとハンドオフの選択
- エージェントオーケストレーション:ワークフロー全体のトレードオフ
- ツール:
agent.asTool()を使うマネージャー型の代替手段 - エージェントの実行:実行時のハンドオフの動作
- エージェントの実行結果:ハンドオフグラフ全体にわたる型付きの
finalOutput