ハンドオフ

ハンドオフは、会話の一部を別のエージェントに委譲できる機能です。これは、異なるエージェントが特定の分野に特化している場合に有用です。たとえばカスタマーサポートアプリでは、予約、返金、FAQ を担当するエージェントを用意できます。

ハンドオフは LLM に対してツールとして表現されます。Refund Agent というエージェントにハンドオフする場合、ツール名は transfer_to_refund_agent になります。

ハンドオフの作成

すべてのエージェントは handoffs オプションを受け付けます。ここには他の Agent インスタンス、または handoff() ヘルパーが返す Handoff オブジェクトを含められます。

プレーンな Agent インスタンスを渡すと、（指定されていれば）その handoffDescription が既定のツール説明に追記されます。モデルがそのハンドオフを選ぶべき状況を明確にするために活用してください。

基本的な使用方法

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 handoffs
const triageAgent = Agent.create({
  name: 'Triage agent',
  handoffs: [billingAgent, handoff(refundAgent)],
});

`handoff()` によるハンドオフのカスタマイズ

handoff() 関数を使うと、生成されるツールを調整できます。

agent – ハンドオフ先のエージェント
toolNameOverride – 既定の transfer_to_<agent_name> ツール名を上書き
toolDescriptionOverride – 既定のツール説明を上書き
onHandoff – ハンドオフ発生時のコールバック。RunContext と、必要に応じてパース済み入力を受け取る
inputType – ハンドオフに期待する入力スキーマ
inputFilter – 次のエージェントに渡す履歴をフィルター
isEnabled – 一致する実行に対してのみそのハンドオフを公開する boolean または述語

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',
});

ハンドオフの入力

ハンドオフを呼び出す際に 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,
});

入力フィルター

既定ではハンドオフは会話履歴全体を受け取ります。次のエージェントに渡す内容を変更するには、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,
});

推奨プロンプト

プロンプトでハンドオフに言及すると、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.`,
});