[OpenAI Agents SDK] 핸드오프 기반 멀티 에이전트 협업 구현

 

이번 글에서는 '핸드오프'라는 기능을 활용해 여러 에이전트가 존재할 때 어떻게 협업을 구현할 수 있는지 살펴보고자 합니다. 우선 에이전트 프레임워크는 OpenAI Agents SDK를 활용했으며, 학습은 '요즘 AI 에이전트 개발, LLM RAG ADK MCP LangChain A2A LangGraph' 책의 내용을 기반으로 진행했음을 미리 알려드립니다.

 

핸드오프(Hand-offs)란 여러 에이전트를 구현했을 때 특정 에이전트가 다른 에이전트에게 작업을 넘겨주는 기능으로, 멀티 에이전트 간 상호작용 방식 중 하나를 말합니다.

 

우선 실습 전, OpenAI의 Agents SDK를 활용할 것이기에 OpenAI의 API Key가 필요합니다. API Key를 발급받은 후 .env 파일을 생성해 Key를 입력해 줍니다.

OPEN_API_KEY={api-key}

 

아래 코드는 OpenAI Agents SDK 기반 핸드오프 실습 전체 코드입니다. 책의 실습 자료는 Github에 있습니다.

import asyncio
from agents import Agent, Runner
from dotenv import load_dotenv


load_dotenv()

async def simple_handoff_example():
    print("Agent 병원 안내 시스템\n")
    print("=" * 50)

    # ① 정형외과 전문의 에이전트
    정형외과의사 = Agent(
        name="정형외과 전문의",
        instructions="근골격계 문제(허리 통증, 관절염, 골절 등)를 진료합니다.",
    )

    # ② 내과 전문의 에이전트
    내과의사 = Agent(
        name="내과 전문의",
        instructions="내과 질환(감기, 소화불량, 두통 등)을 진료합니다. 근골격계 문제는 정형외과 의사에게 연결합니다.",
        handoffs=[정형외과의사],
    )

    # ③ 병원 안내 에이전트
    안내데스크 = Agent(
        name="병원 안내",
        instructions="""
        환자의 증상을 듣고 적절한 전문의에게 연결합니다:
        - 감기, 소화불량, 두통 → 내과 전문의
        - 허리, 관절, 골절 → 정형외과 전문의
        """,
        handoffs=[내과의사, 정형외과의사],
    )

    # ④ 핸드오프 테스트
    response_id = None
    current_agent = 안내데스크

    conversations = [
        "안녕하세요, 며칠 전부터 머리가 아파요",
        "커피를 마시면 아파요. 허리도 아파요.",
        "운동을 하면 좋아 질까요?",
    ]

    for msg in conversations:
        print(f"\n환자: {msg}")

        # 이전 대화가 있으면 response_id 전달
        if response_id:
            result = await Runner.run(
                current_agent, msg, previous_response_id=response_id
            )
        else:
            result = await Runner.run(current_agent, msg)

        response_id = result.last_response_id
        # handoff가 발생한 경우. 에이전트를 변경
        if current_agent != result.last_agent:
            print(
                f"<핸드오프 발생> {current_agent.name}에서 {result.last_agent.name}로 핸드오프"
            )
            current_agent = result.last_agent

        print(f"<Agent 병원> {current_agent.name}: {result.final_output}")


if __name__ == "__main__":
    asyncio.run(simple_handoff_example())

 

위 코드에는 현재 3개의 에이전트가 존재합니다.

 

1. 정형외과 전문의 에이전트

2. 내과 전문의 에이전트

3. 병원 안내 에이전트

 

에이전트에는 name(에이전트 이름)과 instructions(에이전트 지시 사항)을 기본적으로 입력합니다. 그리고 내과 전문의 에이전트와 병원 안내 에이전트에는 handoffs 파라미터가 입력되어있습니다. 내과 전문의는 정형외과 전문의 에이전트에게 작업을 넘길 수 있고, 병원 안내 에이전트는 내과와 정형외과 전문의 에이전트, 모두에게 작업을 넘길 수 있습니다.

 

코드 상에서 4번 핸드오프 테스트 부분을 보겠습니다. 초기 설정된 에이전트는 '병원 안내 에이전트'이며, 환자는 총 3번을 말합니다. 대화 내용은 다음과 같습니다.

 

1. "안녕하세요, 며칠 전부터 머리가 아파요."

2. "커피를 마시면 아파요. 허리도 아파요."

3. "운동을 하면 좋아질까요?"

 

response_id를 통해 대화 맥락이 이어지며, 현재 에이전트(current_agent)와 대화 결과의 에이전트(result.last_agent)를 비교해 핸드오프가 발생했는지 판단하고, 핸드오프가 발생했다면 현재 에이전트를 변경해 줍니다.

 

대화에 따라 에이전트가 어떻게 반응하는지는 위 Python 파일을 실행한 결과를 보며 설명하겠습니다. 아래 텍스트가 그 결과입니다.

Agent 병원 안내 시스템

==================================================

환자: 안녕하세요, 며칠 전부터 머리가 아파요
<핸드오프 발생> 병원 안내에서 내과 전문의로 핸드오프
<Agent 병원> 내과 전문의: 안녕하세요. 머리가 아프신 경우 내과에서 진료를 받아볼 수 있습니다. 어떻게 도와드릴까요?

환자: 커피를 마시면 아파요. 허리도 아파요.
<핸드오프 발생> 내과 전문의에서 정형외과 전문의로 핸드오프
<Agent 병원> 정형외과 전문의: 커피를 마시면 머리가 아프고 허리도 아프시다면 두 가지 문제를 각각 다른 전문가에게 상담하는 것이 좋습니다. 머리 통증과 관련해서는 내과 또는 신경과를, 허리 통증은 근골격계 전문의인 정형외과에서 진료를 받아보시는 것이 좋겠습니다. 어떤 추가 정보가 필요하신가요?

환자: 운동을 하면 좋아 질까요?
<Agent 병원> 정형외과 전문의: 허리 통증에는 적절한 운동이 도움이 될 수 있습니다. 그러나 정확한 원인을 아는 것이 중요합니다. 다음을 시도해볼 수 있습니다:

1. **스트레칭**: 허리와 핵심 근육 강화를 위한 스트레칭.

2. **걷기**: 일상적으로 걷는 것은 허리 건강에 도움이 됩니다.

3. **물리치료**: 전문 물리치료사의 지도를 받는 것도 좋습니다.

그러나 특정 질환이 있다면 무리한 운동은 오히려 해로울 수 있으므로, 정형외과 전문의와 상의 후 적절한 운동 계획을 세우는 것이 좋습니다.

 

1) 초기 설정된 에이전트는 '병원 안내 에이전트'였으나, 환자가 머리가 아프다는 증상을 말해 '내과 전문의 에이전트'로 핸드오프를 합니다. 그래서 '내과 전문의 에이전트'가 답을 합니다.

2) 다음으로는 환자가 허리도 아프다고 합니다. 이때, 허리라는 키워드로 인해 '내과 전문의 에이전트'는 '정형외과 전문의 에이전트'로 작업을 넘깁니다. 이에 따라 답변도 '정형외과 전문의 에이전트'가 합니다.

3) 마지막 환자의 대화의 맥락은 핸드오프가 발생할 상황이 아닙니다. 따라서 '정형외과 전문의 에이전트'가 그대로 답을 하는 것을 볼 수 있습니다.

 

이번 글에서는 OpenAI의 Agents SDK와 핸드오프를 를 중심으로 설명했습니다. 추후에는 LangGrpah, CrewAI 등 다양한 프레임워크에 대해서도 에이전트를 어떻게 구현하고 있는지 살펴볼 예정입니다.

 

 

<참고>

1. https://ebook-product.kyobobook.co.kr/dig/epd/ebook/E000011924591

요즘 AI 에이전트 개발, LLM RAG ADK MCP LangChain A2A LangGraph | 박승규

 

2. https://velog.io/@gathers/Multi-%EC%97%90%EC%9D%B4%EC%A0%84%ED%8A%B8-%ED%95%B8%EB%93%9C%EC%98%A4%ED%94%84HandOffs

Multi 에이전트: 핸드오프(HandOffs)