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