ハンドオフ

ハンドオフにより、エージェントは会話の一部を別のエージェントに委譲できます。これは、異なるエージェントが特定の領域を専門に扱う場合に便利です。たとえばカスタマーサポートアプリでは、予約、返金、FAQ を処理するエージェントを用意できます。

ハンドオフは LLM に対してツールとして表現されます。Refund Agent というエージェントにハンドオフする場合、ツール名は transfer_to_refund_agent になります。

専門エージェントが会話を引き継ぐべきだと分かった段階で、エージェントを読んだ後にこのページを読んでください。専門エージェントが元のエージェントの背後で動作するべき場合は、代わりに agents as tools を使用してください。

ハンドオフの作成

すべてのエージェントは handoffs オプションを受け取れます。handoffs には、他の Agent インスタンス、または handoff() ヘルパーが返す Handoff オブジェクトを含められます。

プレーンな Agent インスタンスを渡すと、その handoffDescription が指定されている場合、デフォルトのツール説明に追加されます。モデルがそのハンドオフを選ぶべきタイミングを明確にするために使います。

基本的な使用方法

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 handoffs
const triageAgent = Agent.create({
  name: 'Triage agent',
  handoffs: [billingAgent, handoff(refundAgent)],
});

`handoff()` によるハンドオフのカスタマイズ

handoff() 関数を使うと、生成されるツールを調整できます。

agent – ハンドオフ先のエージェント
toolNameOverride – デフォルトの transfer_to_<agent_name> ツール名を上書き
toolDescriptionOverride – デフォルトのツール説明を上書き
onHandoff – ハンドオフ発生時のコールバック。RunContext を受け取り、inputType が設定されている場合は、パース済みのハンドオフペイロードも受け取ります。
inputType – ハンドオフツール呼び出し引数のスキーマ
inputFilter – 次のエージェントに渡される履歴をフィルタリング
isEnabled – 条件に一致する実行でのみハンドオフを公開する boolean または述語

handoff() ヘルパーは常に、渡された特定の agent に制御を移します。複数の宛先候補がある場合は、宛先ごとに 1 つのハンドオフを登録し、その中からモデルに選択させます。呼び出し時にどのエージェントを返すかを独自のハンドオフコードで決定する必要がある場合は、カスタム 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',
});

ハンドオフ入力

モデルがハンドオフを選択するときに、小さな構造化ペイロードを添付させたい場合があります。その場合は 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 に渡します。

これは、次のエージェントのメイン入力を置き換えるものではなく、別の宛先を選ぶものでもありません。handoff() ヘルパーは引き続き、ラップした特定のエージェントに転送します。また、受け取るエージェントは、inputFilter で変更しない限り、引き続き会話履歴を参照します。

また inputType は RunContext とも別物です。ローカルに既にあるアプリケーション状態や依存関係ではなく、ハンドオフ時にモデルが決定するメタデータに使用してください。

`inputType` の使用タイミング

ハンドオフで、reason、language、priority、summary のような、モデルが生成する小さなルーティングメタデータが必要な場合に inputType を使用します。たとえば、トリアージエージェントは { reason: 'duplicate_charge', priority: 'high' } とともに返金エージェントへハンドオフでき、onHandoff は返金エージェントが引き継ぐ前にそのメタデータをログに記録したり永続化したりできます。

目的が異なる場合は、別の仕組みを選んでください：

既存のアプリケーション状態は RunContext に入れます。
受け取るエージェントに見せる履歴を変更したい場合は、inputFilter を使用します。
候補となる専門エージェントが複数いる場合は、宛先ごとに 1 つのハンドオフを登録します。inputType は選択されたハンドオフにメタデータを追加できますが、宛先間の振り分けは行いません。
onHandoff が実行される前に、パース済みペイロードを SDK に検証させたい場合は、Zod スキーマを推奨します。元の JSON Schema は、モデルに送られるツール契約を定義するだけです。

入力フィルター

デフォルトでは、ハンドオフは会話履歴全体を受け取ります。次のエージェントに渡される内容を変更するには、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 が優先されます。

推奨プロンプト

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