핸드오프(Handoffs)로 에이전트 넘기기

핸드오프는 한 에이전트가 작업을 다른 에이전트에게 위임할 수 있게 해주는 기능이에요. 각자 분야가 다른 에이전트들이 있을 때 특히 유용해요. 예를 들어 고객 지원 앱에 주문 상태·환불·FAQ를 각각 처리하는 에이전트가 있다고 하면, 사용자의 질문에 따라 적절한 에이전트로 대화를 넘기는 식이에요.

핸드오프는 LLM 입장에서는 도구(tool)처럼 보여요. 즉 Refund Agent라는 에이전트로의 핸드오프는 transfer_to_refund_agent라는 이름의 도구로 표현돼요.

핸드오프 만들기

모든 에이전트에는 handoffs 파라미터가 있어요. 여기에 Agent를 직접 넘길 수도 있고, 핸드오프를 커스터마이즈할 수 있는 Handoff 객체를 넘길 수도 있어요. handoff() 함수로 만들면 agent, tool_name_override, tool_description_override, on_handoff, input_type, input_filter, is_enabled 같은 것들을 지정할 수 있어요.

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)],
)

기본적으로 도구 이름은 transfer_to_<agent_name>이 되는데 tool_name_override로 바꿀 수 있어요. on_handoff는 핸드오프가 호출될 때 실행되는 콜백으로, 데이터를 미리 가져오는 등의 작업을 할 수 있어요.

핸드오프 입력 데이터

핸드오프할 때 모델이 간단한 메타데이터(사유, 언어, 우선순위, 요약 등)를 함께 넘기게 하고 싶다면 input_type을 써요. 예를 들어 "Escalation agent"로 넘길 때 사유를 남기고 싶은 상황을 떠올려 보세요.

from pydantic import BaseModel
from agents import Agent, handoff, RunContextWrapper

class EscalationData(BaseModel):
    reason: str

async def on_handoff(ctx: RunContextWrapper[None], input_data: EscalationData):
    print(f"Escalation agent called with reason: {input_data.reason}")

agent = Agent(name="Escalation agent")
handoff_obj = handoff(agent=agent, on_handoff=on_handoff, input_type=EscalationData)

input_type은 핸드오프 도구 호출 자체의 인자 스키마예요. SDK가 그 스키마를 모델의 parameters로 노출하고, 반환된 JSON을 로컬에서 검증한 뒤 파싱된 값을 on_handoff에 전달해요. 기존 애플리케이션 상태나 의존성은 RunContextWrapper.context에 넣는 것과 구분해서 쓰는 게 좋아요.

입력 필터

핸드오프가 일어나면 새 에이전트가 대화를 이어받아 이전 대화 전체를 보게 돼요. 이 기록을 바꾸고 싶다면 input_filter를 써요. 필터 함수는 HandoffInputData를 받아 새 HandoffInputData를 반환해요. 도구 호출 기록을 모두 지우는 remove_all_tools 같은 공통 패턴은 agents.extensions.handoff_filters에 준비돼 있어요.

from agents import Agent, handoff
from agents.extensions import handoff_filters

agent = Agent(name="FAQ agent")
handoff_obj = handoff(agent=agent, input_filter=handoff_filters.remove_all_tools)

더 알아보기

에이전트 정의: Agents
멀티 에이전트 패턴: Multi-agent patterns
도구: Tools

핸드오프(Handoffs)로 에이전트 넘기기