ハンドオフ
ハンドオフを使用すると、あるエージェントが会話の一部を別のエージェントに委任できます。これは、エージェントごとに得意分野が異なる場合に便利です。たとえばカスタマーサポートアプリでは、予約、返金、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 { Agent, handoff, RunContext } from '@openai/agents';
function onHandoff(ctx: RunContext) { console.log('Handoff called');}
const agent = new Agent({ name: 'My agent' });
const handoffObj = handoff(agent, { onHandoff, 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.`,});