ハンドオフ
ハンドオフを利用すると、あるエージェントが会話の一部を別のエージェントに委任できます。異なるエージェントが特定の分野を専門としている場合に便利です。たとえばカスタマーサポートアプリでは、予約、返金、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.`,});