[OpenAI Agent SDK] Handoff 란?

🧠 Handoff란?

Handoff는 작업을 다른 Agent에게 넘기는 것을 말한다.

예: 고객 지원 시스템에서

• 주문 확인은 A 에이전트
• 환불은 B 에이전트
• 자주 묻는 질문은 C 에이전트

이렇게 역할을 나누고, 필요할 때 서로 작업을 넘길 수 있게 해주는 것이다.

🛠️ 기본 Handoff 설정 방법

Agent를 만들 때 handoffs 파라미터를 설정:

from agents import Agent, handoff

billing_agent = Agent(name="Billing agent")
refund_agent = Agent(name="Refund agent")

triage_agent = Agent(
    name="Triage agent",
    handoffs=[
        billing_agent,              # 직접 에이전트 넣는 방법
        handoff(refund_agent)       # 커스터마이징 가능하게 handoff()로 감싸기
    ]
)

✨ handoff() 함수로 더 세밀한 설정

from agents import handoff

handoff(
    agent=refund_agent,
    tool_name_override="custom_handoff_tool",           # 도구 이름 커스텀
    tool_description_override="Custom description",     # 도구 설명 변경
    on_handoff=on_handoff_function,                     # Handoff 순간 실행되는 콜백 함수
    input_type=InputSchema,                             # LLM이 넘겨줘야 할 데이터 형식
    input_filter=필터함수                                # 대화 내역 일부만 넘기고 싶을 때
)

🧩 on_handoff: Handoff 순간에 실행되는 함수

def on_handoff(ctx: RunContextWrapper[None]):
    print("Handoff 실행됨!")

만약 데이터를 같이 넘기고 싶다면?

from pydantic import BaseModel

class EscalationData(BaseModel):
    reason: str  # 에이전트에게 넘길 정보 정의

async def on_handoff(ctx, input_data: EscalationData):
    print(f"이유: {input_data.reason}")

🧼 input_filter: 넘기는 대화 내용 정제하기

에이전트에게 넘길 때, 모든 대화 기록을 넘기지 않고 필요한 부분만 넘기고 싶을 때 사용:

from agents.extensions import handoff_filters

handoff_obj = handoff(
    agent=faq_agent,
    input_filter=handoff_filters.remove_all_tools  # 예: 도구 호출 기록 제거
)

🧾 추천 프롬프트 넣기 (LLM이 handoff를 잘 이해하도록)

from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX

agent = Agent(
    name="Billing agent",
    instructions=f"""{RECOMMENDED_PROMPT_PREFIX}
    <여기에 나머지 지침 추가>"""
)

또는 자동으로 추가해주는 함수:

from agents.extensions.handoff_prompt import prompt_with_handoff_instructions

✅ 요약

기능	설명
handoff()	다른 에이전트로 작업 넘기기 설정
tool_name_override	도구 이름을 기본값 대신 원하는 이름으로 지정 가능
on_handoff	Handoff 시점에 실행할 콜백 함수 정의 가능
input_type	넘길 데이터의 스키마(pydantic 기반) 지정 가능
input_filter	대화 내역 중 필요한 부분만 선택해 넘기기 가능
RECOMMENDED_PROMPT_PREFIX	LLM이 handoff 기능을 잘 이해하도록 프롬프트에 지침 자동 추가