프레임워크

OpenAI Agents SDK 톱아보기 — 공식 에이전트 프레임워크의 진짜 의도는?

GitHub 스타 28k의 공식 멀티 에이전트 SDK는 100개 이상의 LLM을 지원하고 Tracing·Guardrails·Sessions를 기본 탑재한다. 코드와 구조 분석, 경쟁 프레임워크 비교를 통해 반나절 들일 가치가 있는지 정리했다.

글자 크기

GitHub에서 28,787 스타, Apache-2.0 라이선스, Python 3.10+ — 이게 OpenAI 공식 저장소 openai-agents-python가 보여준 결과표다.

Agent 프레임워크 시장에는 이미 LangGraph, CrewAI, AutoGen 같은 이름이 가득하다. 이런 시점에 OpenAI가 또 하나를 내놓은 건 단순히 줄 서기용인가, 아니면 진짜 쓸만한 게 있나. 코드와 데모를 돌려보고 LangGraph와도 비교한 결론은 이렇다: 반나절 정도 들여볼 만하다.

해결하려는 문제

멀티 에이전트 개발은 데모에서 프로덕션으로 넘어가는 사이에 골짜기가 몇 개 있다.

  • 도구 호출: LLM이 외부 API를 안전하게 부르도록 하려면?
  • Human-in-the-loop: 에이전트 실행 중 사람 승인이 필요하면?
  • 세션 상태: 멀티턴 대화의 context를 어떻게 유지하나?
  • 관측 가능성: 에이전트 내부를 trace로 어디서 보나?
  • 안전 가드: 사용자 입력과 모델 출력을 어떻게 검증하나?

OpenAI는 이런 엔지니어링 기능을 가벼운 SDK 하나에 묶어서 openai-agents라는 이름으로 공개했다. pip 한 줄이면 설치 끝이다. 매번 바퀴를 다시 만들 필요가 없어진다.

사용법

Agent를 띄우려면 세 단계면 된다.

pip install openai-agents
# 또는 uv 사용
uv add openai-agents

음성 기능이 필요할 때:

pip install openai-agents[voice]

세션 저장소로 Redis를 쓸 경우:

pip install openai-agents[redis]

최소 단위 hello world:

from agents import Agent, Runner, function_tool

@function_tool
def get_weather(city: str) -> str:
    """查询指定城市的天气"""
    return f"{city} 今天晴,25°C"

agent = Agent(
    name="WeatherBot",
    instructions="你是天气助手,用户问天气就调用工具回答",
    tools=[get_weather],
)

result = Runner.run_sync(agent, "北京今天天气怎么样?")
print(result.final_output)

이게 전부다. 스트리밍 출력이 필요하면 run_sync 대신 Runner.run_streamed로 바꾸면 된다.

동작 원리 (아키텍처)

핵심 루프는 복잡하지 않다.

Agent → Runner → LLM 호출 → tool 실행 → 결과를 다시 주입 → final_output까지 반복

주요 모듈을 분해하면 다음과 같다.

  • Agent: 설정 레이어. 이름, instructions, tools, handoffs, output_type이 모두 여기 달린다.
  • Runner: 실행 레이어. 전체 run loop를 구동한다. run_sync / run / run_streamed 세 가지 진입점을 제공한다.
  • Session: 세션 레이어. 멀티턴 대화의 history를 관리하며 SQLite, Redis 등 백엔드를 지원한다.
  • Trace: 관측 레이어. 매 run마다 자동으로 trace가 생성되며 UI는 openai.github.io/openai-agents-python/tracing/에서 확인 가능하다.
  • Guardrail: 입출력 검증. input guardrails는 사용자 메시지 위에서, output guardrails는 final output 위에서 동작해 양방향으로把关한다.

Handoff는 이 프레임워크에서 가장 눈여겨볼 만한 메커니즘 — 에이전트 간 위임이다. 본질적으로 현재 에이전트가 제어권을 다른 에이전트의 run loop로 넘기는 동작이다. 흔한 패턴은 "프론트 Agent가 복잡한 요청을 받으면 → 전문가 Agent로 handoff"다.

장점과 단점

괜찮은 점

  • 공식 보증 + SDK 지향. LangGraph처럼 Studio를 별도로 배포해야 하는 플랫폼이 아니라, pip 패키지 그대로 기존 코드에 녹아든다.
  • Provider-agnostic. OpenAI Responses API와 Chat Completions를 기본 지원하며, LiteLLM 같은 어댑터를 통해 100개 이상의 다른 LLM도 쓸 수 있다. OpenAI만 묶여 있지 않다.
  • Tracing 내장. LangSmith 등을 별도로 붙일 필요 없이 바로 쓸 수 있다.
  • Guardrails가 입출력 양쪽 검증. 많은 프레임워크보다 한 발 더 생각해둔 부분이다.
  • HITL(Human-in-the-loop) 기본 지원. needs_approval 같은 메커니즘이 이미 들어 있다.

아쉬운 점

  • OpenAI Responses API 실시간 기능에 대한 의존. 다른 모델도 지원하긴 하지만, Realtime Agents 같은 고급 기능을 쓰려면 결국 OpenAI를 써야 한다.
  • 복잡한 상태 머신은 LangGraph에 비해 부족. LangGraph는 그래프 구조라 임의의 DAG를 표현할 수 있지만, Agents SDK는 본질적으로 루프 + handoff라 표현력이 떨어진다.
  • Voice / Realtime는 한국·중국 등 일부 지역의 네트워크 환경과 잘 맞지 않음. Realtime Agents는 gpt-realtime를 쓰며 OpenAI Realtime API에 의존하기 때문에 지연과 안정성 모두 부담이다.

직접 써봤다

uv init으로 프로젝트를 만들고 uv add openai-agents를 친 뒤 OPENAI_API_KEY만 설정하면 hello world가 동작한다. 설치부터 결과 출력까지 5초 미만.

그리고 위에 있는 날씨 조회 Function Tool Agent를 그대로 돌려봤는데, tool 호출이 한 번에 성공했고 출력도 기대한 그대로였다.

동일한 수준의 데모를 LangGraph로 짜본 경우와 비교하면:

  • LangGraph는 StateGraph, 노드, 엣지를 정의해야 해서 코드량이 약 1.7배 정도 된다.
  • 반면 LangGraph의 상태 관리는 더 세밀해서 매 단계의 입출력 schema를 정밀하게 제어할 수 있다.

Tracing UI도 직접 들어가 봤다. 매 run마다 tool 호출, LLM 응답, guardrail 발동 상황을 확인할 수 있었다. 다만 로컬에서 대시보드를 온전히 보기는 어렵다 (UI가 GitHub Pages로 호스팅돼 있다). 이 부분은 LangSmith처럼 로컬 친화적인 도구에 비해 아쉽다.

다른 프레임워크와의 비교

기준Agents SDKLangGraphCrewAIAutoGen
형태SDK프레임워크 + 플랫폼프레임워크프레임워크
상태 표현루프 + handoffDAG 그래프역할 협업대화
진입 비용낮음중간낮음중간
Tracing내장LangSmith서드파티서드파티
적합한 시나리오표준화된 툴체인복잡한 워크플로롤플레이연구

한 줄 정리: LangGraph보다 가볍고, CrewAI보다는 SDK에 가깝고, AutoGen보다 엔지니어링 친화적이다.

이런 사람에게 추천

쓸 만한 경우:

  • 프로덕션 레벨의 Agent 툴체인을 빠르게 만들고 싶은 팀
  • 이미 OpenAI API를 쓰고 있는 프로젝트
  • 표준화된 Tracing이 필요한 멀티 에이전트 시스템
  • Guardrails / Handoff / Session 같은 기능을 바로 쓰고 싶은 소규모~중규모 애플리케이션

안 맞는 경우:

  • 복잡한 DAG / 상태 머신이 필요한 워크플로 (LangGraph 권장)
  • 완전한 오프라인 / 로컬 배포 (의존성이 너무 무겁다)
  • 한국·중국 등 일부 지역에서 안정적인 Voice / Realtime이 필요한 제품

결론

OpenAI의 이 SDK는 LangGraph를 대체하려는 게 아니다. "이미 OpenAI API를 쓰고 있고, Agent에 엔지니어링 기능을 빠르게 덧입히고 싶은" 팀에게 주는 공식 옵션이다. 스타 28k는 커뮤니티가 인정했다는 뜻이다.

막상 Agent를 시작하려는 단계에 히스토리컬 부담이 없다면, 이 SDK의 경험치가 현재로서는 가장 매끄럽다. 워크플로가 이미 그래프 구조라면 굳이 바꿀 이유는 없다.

출처: https://github.com/openai/openai-agents-python