본문으로 건너뛰기

OpenAI Agents SDK로 프로덕션급 LLM 에이전트 구축하기

OpenAI Agents SDK를 사용하여 OpenAI 모델과 Hugging Face의 오픈소스 모델을 통합하고, 멀티 에이전트 협업 및 구조화된 출력을 구현하는 실전 가이드이다.

챕터별 상세

00:00

Intro

OpenAI Agents SDK는 Swarm의 실험적 성격을 넘어 프로덕션 환경을 겨냥해 출시된 프레임워크이다. 에이전트, Handoff, Guardrails, Sessions라는 네 가지 핵심 Primitives를 기반으로 작동했다. 가벼운 패키지 구조를 유지하면서도 복잡한 에이전트 워크플로를 지원하도록 설계됐다.
01:42

Quickstart

Agent 클래스를 인스턴스화할 때 이름, 지침, 모델명을 정의했다. @function_tool 데코레이터는 파이썬 함수의 Docstring과 타입 힌트를 분석하여 에이전트가 사용할 수 있는 도구 메타데이터로 변환했다. Runner.run은 비동기 방식으로 에이전트의 추론과 도구 호출 과정을 실행했다.
python
from agents import Agent, function_tool, Runner

@function_tool
def get_weather(city: str) -> str:
    """returns weather info for the specified city."""
    return f"The weather in {city} is sunny"

agent = Agent(
    name="Haiku agent",
    instructions="Always respond in haiku form",
    model="gpt-4o-mini",
    tools=[get_weather]
)

result = await Runner.run(agent, "What's the weather in New York?")
print(result.final_output)

OpenAI Agents SDK의 기본 에이전트 및 도구 설정 예시

05:33

Running open models from Hugging Face

openai-agents[litellm] 라이브러리를 설치하여 OpenAI 이외의 모델 지원을 확장했다. Hugging Face의 API 토큰을 환경 변수로 설정한 뒤 LiteLLMModel을 통해 오픈소스 모델을 호출했다. litellm/huggingface/ 경로 형식을 사용하여 Qwen이나 Llama 같은 모델을 OpenAI SDK 내에서 투명하게 사용했다.
python
from agents.extensions.models.litellm_model import LiteLLMModel

model = LiteLLMModel(
    model="huggingface/novita/Qwen/Qwen2.5-72B-Instruct",
    api_keyos_environ=["HF_TOKEN"]
)

hf_agent = Agent(
    name="Kimi agent",
    model=model,
    tools=[get_weather]
)

LiteLLM을 사용하여 Hugging Face의 오픈소스 모델을 연동하는 예시

08:54

Tracing runs in the OpenAI platform

OpenAI 플랫폼의 대시보드와 연동하여 에이전트의 실행 로그를 시각화했다. set_tracing_export_api_key 함수로 API 키를 등록하면 모든 추론 단계와 도구 호출 결과가 기록됐다. 이는 에이전트 내부의 블랙박스 과정을 투명하게 공개하여 디버깅과 성능 최적화를 돕는 도구였다.
12:13

Structured Output

Pydantic의 BaseModel을 상속받아 에이전트가 반환해야 할 데이터 구조를 정의했다. Agent 생성 시 output_type 파라미터에 해당 클래스를 전달하여 모델 응답 형식을 강제했다. 이 기능은 비정형 텍스트에서 특정 정보를 추출하여 시스템 간 데이터 연동을 자동화하는 데 기여했다.
python
from pydantic import BaseModel

class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]

agent = Agent(
    name="Calendar Extractor",
    output_type=CalendarEvent,
    model=model
)

Pydantic을 활용하여 에이전트의 출력을 구조화하는 예시

15:40

Multi-agent orchestration: handoff vs manager

에이전트 간의 협업 방식을 Handoff와 Manager 패턴으로 구분하여 구현했다. Handoff는 특정 조건에서 다른 에이전트에게 제어권을 완전히 넘기는 분산형 방식이었다. Manager 패턴은 중앙 에이전트가 하위 에이전트들을 도구처럼 호출하여 작업을 조율하는 오케스트레이션 구조를 가졌다.
python
history_tutor_agent = Agent(name="History Tutor", handoff_description="Specialist for history")
math_tutor_agent = Agent(name="Math Tutor", handoff_description="Specialist for math")

triage_agent = Agent(
    name="Triage Agent",
    handoffs=[history_tutor_agent, math_tutor_agent]
)

Handoff 기능을 이용한 멀티 에이전트 제어권 전환 예시

21:33

Building and using tools

커스텀 도구 제작 시 타입 힌트와 상세한 Docstring 작성이 에이전트의 도구 선택 정확도를 결정했다. SDK는 WebSearchTool, FileSearchTool 등 자주 사용되는 기능을 프리빌트 도구 형태로 제공했다. 이러한 도구들은 에이전트의 지식 범위를 실시간 웹 정보나 로컬 파일 시스템으로 확장시켰다.
23:39

Streaming tokens and agent events

Runner.run_streamed 메서드를 사용하여 모델의 응답 토큰을 실시간으로 수신했다. 텍스트 토큰뿐만 아니라 도구 호출 시작, 추론 단계 완료 등 에이전트 내부 이벤트도 스트리밍 데이터로 처리했다. 이는 사용자 경험을 개선하고 긴 추론 과정의 진행 상태를 실시간으로 피드백하는 데 유용했다.

용어 해설

에이전트(Agent)
LLM에 구체적인 지침과 도구 사용 권한을 부여하여 특정 작업을 자율적으로 수행하도록 설계된 소프트웨어 단위이다. 단순한 텍스트 생성을 넘어 외부 도구를 호출하거나 의사결정을 내리는 능력을 갖춘다.
핸드오프(Handoff)
멀티 에이전트 시스템에서 현재 작업을 수행 중인 에이전트가 특정 조건이나 전문 분야에 따라 다른 에이전트에게 대화의 제어권을 넘겨주는 메커니즘이다. 이를 통해 복잡한 작업을 전문화된 여러 에이전트가 나누어 처리했다.
구조화된 출력(Structured Output)
LLM이 생성하는 자유 형식의 텍스트를 JSON 스키마나 Pydantic 모델과 같은 정해진 구조로 출력하도록 강제하는 기능이다. 비정형 데이터에서 필요한 정보를 정확한 형식으로 추출하여 후속 시스템 연동의 신뢰성을 높였다.
트레이싱(Tracing)
에이전트가 사용자 요청을 처리하는 과정에서 발생하는 추론 단계, 도구 호출, 모델 응답 등을 순차적으로 기록하여 시각화하는 디버깅 기법이다. 에이전트 내부의 복잡한 실행 흐름을 투명하게 파악할 수 있게 했다.
멀티 에이전트 오케스트레이션(Multi-Agent Orchestration)
복잡한 문제를 해결하기 위해 여러 개의 전문 에이전트를 배치하고 이들 간의 작업 흐름과 상호작용을 관리하는 설계 패턴이다. 중앙 관리자가 조율하거나 에이전트 간 제어권을 넘기는 방식으로 구현했다.

언급된 리소스

AI 분석 전체 내용 보기

AI 요약 · 북마크 · 개인 피드 설정 — 무료

출처 · 인용 안내

원문 발행 2026. 01. 12.수집 2026. 02. 21.출처 타입 YOUTUBE

인용 시 "요약 출처: AI Trends (aitrends.kr)"를 표기하고, 사실 확인은 원문 보기 기준으로 진행해 주세요. 자세한 기준은 운영 정책을 참고해 주세요.