ハンドオフ
ハンドオフを使うと、あるエージェントが会話の一部を別のエージェントへ委任できます。これは、異なるエージェントが特定の領域に特化している場合に便利です。たとえばカスタマーサポートアプリでは、予約、返金、FAQ を担当するエージェントを用意できます。
ハンドオフは LLM に対してツールとして表現されます。Refund Agent というエージェントへハンドオフする場合、ツール名は transfer_to_refund_agent になります。
ハンドオフの作成
Section titled “ハンドオフの作成”すべてのエージェントは handoffs オプションを受け付けます。ここには他の Agent インスタンスや、handoff() ヘルパーが返す Handoff オブジェクトを含められます。
基本的な使い方
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– ハンドオフに期待する入力スキーマinputFilter– 次のエージェントへ渡す履歴のフィルター
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 “ハンドオフの入力”ハンドオフの呼び出し時に LLM にデータを提供させたい場合があります。入力スキーマを定義して handoff() で使用します。
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,});入力フィルター
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,});推奨プロンプト
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.`,});