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