핸드오프

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

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

핸드오프 생성

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

기본 사용

Basic handoffs

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

Customized handoffs

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()에서 사용하세요.

Handoff inputs

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에 있습니다.

Input filters

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를 통해 권장 접두사를 제공합니다.

Recommended prompts

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