08. 멀티 에이전트 팀 만들기

비유로 시작하기: 편집팀 꾸리기

리서치 보고서를 만든다고 합시다. 혼자 다 하기보다, 자료 조사원이 정보를 모으고, 분석가가 의미를 추려내고, 작가가 글로 다듬는 편집팀이 결과가 좋습니다. 각자 전문 영역에 집중하기 때문입니다.

OpenAI Agents SDK에서 이런 팀을 만드는 방법은 크게 두 가지입니다. 에이전트를 도구로 쓰는 방식(매니저가 부하들을 도구처럼 호출)과 핸드오프(한 에이전트가 다른 에이전트에게 대화 자체를 넘김)입니다. 이 장은 전자, 다음 부에서 후자를 다룹니다.

전문 에이전트 정의하기

먼저 역할별 에이전트를 만듭니다. 1부의 강좌 예제(Researcher & Analyst & Writer)를 따릅니다.

from agents import Agent

researcher = Agent(
    name="Researcher",
    instructions="주제에 대한 핵심 사실과 최신 정보를 수집해 정리한다.",
)

analyst = Agent(
    name="Analyst",
    instructions="수집된 정보에서 의미 있는 인사이트와 시사점을 도출한다.",
)

writer = Agent(
    name="Writer",
    instructions="분석 결과를 바탕으로 읽기 쉬운 보고서를 작성한다.",
)

패턴 1: 에이전트를 도구로 (agent as tool)

매니저 에이전트가 다른 에이전트들을 도구처럼 호출하는 패턴입니다. 매니저가 전체 흐름의 주도권을 쥐고, 필요할 때 전문가를 불러 쓴 뒤 결과를 종합합니다. 이렇게 여러 에이전트의 작업 순서와 협업을 한 주체가 지휘하는 것을 오케스트레이션(orchestration)이라 부릅니다. 오케스트라의 지휘자가 각 악기 파트를 조율하는 모습을 떠올리면 됩니다.

from agents import Agent, Runner

manager = Agent(
    name="Manager",
    instructions=(
        "너는 리서치 보고서 제작을 총괄한다. "
        "먼저 자료를 조사하고, 분석한 뒤, 최종 보고서를 작성하라. "
        "각 단계에 적절한 도구를 사용하라."
    ),
    tools=[
        researcher.as_tool(
            tool_name="research",
            tool_description="주제에 대한 정보를 수집한다.",
        ),
        analyst.as_tool(
            tool_name="analyze",
            tool_description="수집된 정보를 분석해 인사이트를 낸다.",
        ),
        writer.as_tool(
            tool_name="write_report",
            tool_description="분석 결과로 최종 보고서를 작성한다.",
        ),
    ],
)

result = Runner.run_sync(manager, "2026년 AI 에이전트 시장 동향 보고서를 만들어줘.")
print(result.final_output)

agent.as_tool(...)로 에이전트를 도구로 감싸면, 매니저는 이를 일반 도구처럼 호출합니다. 부하 에이전트의 답이 도구 결과로 매니저에게 돌아오고, 매니저는 그것을 종합해 다음 단계를 결정합니다.

flowchart TB
    classDef mgr fill:#80DEEA,stroke:#00838F,color:#000
    classDef worker fill:#90CAF9,stroke:#1565C0,color:#000
    classDef result fill:#A5D6A7,stroke:#2E7D32,color:#000

    M[Manager 에이전트]:::mgr
    R[research<br/>= Researcher]:::worker
    A[analyze<br/>= Analyst]:::worker
    W[write_report<br/>= Writer]:::worker
    F[최종 보고서]:::result

    M -->|도구 호출| R --> M
    M -->|도구 호출| A --> M
    M -->|도구 호출| W --> M
    M --> F

📌 핵심: "에이전트를 도구로" 패턴에서는 매니저가 항상 통제권을 유지합니다. 부하는 호출되어 답만 내고, 흐름의 결정은 매니저가 합니다. 이것이 다음 부의 핸드오프(통제권 자체를 넘김)와의 결정적 차이입니다.

패턴 1 vs 핸드오프: 무엇이 다른가

멀티 에이전트 추적하기

여러 에이전트가 얽히면 실행 흐름이 복잡해집니다. trace()로 묶으면 모든 LLM 호출·도구(=에이전트) 실행이 하나의 트레이스로 기록됩니다.

from agents import Runner, trace

with trace("리서치 보고서 워크플로"):
    result = Runner.run_sync(manager, "AI 에이전트 시장 동향 보고서를 만들어줘.")
    print(result.final_output)
# OpenAI Traces 대시보드에서 매니저→리서처→분석가→작가 흐름을 시각적으로 확인

💡 팁: 멀티 에이전트가 기대대로 협업하지 않을 때, 트레이스를 보면 "어느 단계에서 엉뚱한 결정을 했는지" 바로 보입니다. 디버깅의 1순위 도구입니다.

⚠️ 흔한 실수: 매니저의 instructions가 모호한 것. "보고서를 만들어줘"만 있으면 매니저가 부하 도구를 안 쓰고 혼자 답해버릴 수 있습니다. 단계와 순서를 명시("먼저 조사 → 그 다음 분석 → 마지막에 작성")하면 의도대로 협업합니다.

💡 실습 아이디어(강의의 Creative Advertising 팀 대응): 같은 패턴으로 광고 기획팀을 만들어 보세요. 시장조사 에이전트, 카피라이터 에이전트, 슬로건 검수 에이전트를 매니저가 조율하면, 한 번의 입력으로 광고 카피 후보가 종합되어 나옵니다.

이 장에서 배운 것

• 복잡한 작업은 역할별 전문 에이전트로 나눠 협업시키면 품질이 높아진다.
• "에이전트를 도구로(as_tool)" 패턴에서는 매니저가 통제권을 유지하며 부하를 호출·종합한다.
• 이는 통제권을 넘기는 핸드오프와 다르다. 작업 성격에 따라 고른다.
• trace()로 멀티 에이전트 실행을 추적하면 디버깅이 쉬워진다.

✍️ 확인 문제

1. "에이전트를 도구로" 패턴과 핸드오프 패턴에서 "통제권"이 어떻게 다르게 흐르는지 설명하라.
2. 매니저가 부하 에이전트 도구를 사용하지 않고 혼자 답해버린다. instructions를 어떻게 고쳐야 하는가?
3. 세 에이전트가 협업하는 워크플로에서 분석 단계의 결과가 이상하다. 어디서부터 원인을 찾는 것이 효율적인가?

이전 장: 07. SDK로 도구·메모리 다루기
다음 부: 3부 · 가드레일과 핸드오프 — 에이전트를 안전하게 만들고, 통제권을 넘기는 협업을 배웁니다.