핸드오프

핸드오프는 한 에이전트가 대화의 일부를 다른 에이전트에 위임하도록 합니다. 이는 서로 다른 에이전트가 특정 영역을 전문으로 할 때 유용합니다. 예를 들어 고객 지원 앱에서는 예약, 환불 또는 FAQ를 처리하는 에이전트를 둘 수 있습니다.

핸드오프는 LLM에 도구로 표현됩니다. Refund Agent라는 에이전트로 핸드오프하면 도구 이름은 transfer_to_refund_agent가 됩니다.

핸드오프 생성

모든 에이전트는 handoffs 옵션을 받습니다. 여기에는 다른 Agent 인스턴스나 handoff() 헬퍼가 반환하는 Handoff 객체를 포함할 수 있습니다.

기본 사용

기본 핸드오프

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 – 다음 에이전트에 전달할 히스토리 필터

커스터마이즈된 핸드오프

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

핸드오프 입력

때로는 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.`,
});