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 SDK | LangGraph | CrewAI | AutoGen |
|---|---|---|---|---|
| 형태 | SDK | 프레임워크 + 플랫폼 | 프레임워크 | 프레임워크 |
| 상태 표현 | 루프 + handoff | DAG 그래프 | 역할 협업 | 대화 |
| 진입 비용 | 낮음 | 중간 | 낮음 | 중간 |
| 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의 경험치가 현재로서는 가장 매끄럽다. 워크플로가 이미 그래프 구조라면 굳이 바꿀 이유는 없다.