OpenAI Agents SDK 소개
복잡한 AI 에이전트 시스템을 구축하려면 단일 에이전트의 한계를 넘어 여러 에이전트가 협력하는 멀티 에이전트 워크플로우가 필요합니다. 청구 처리는 청구 전문 에이전트가, 환불은 환불 전문 에이전트가 처리하도록 작업을 위임하는 구조, 그리고 사용자 입력이나 에이전트 출력이 안전한지 검증하는 가드레일이 이 모든 과정에 필요합니다. OpenAI는 2025년에 OpenAI Agents SDK(openai-agents-python)를 오픈소스로 공개하여 이러한 멀티 에이전트 워크플로우를 간단하고 직관적으로 구축할 수 있는 경량 프레임워크를 제공합니다.
OpenAI Agents SDK는 이전에 실험적으로 공개했던 Swarm 프레임워크의 후속작으로, 프로덕션 환경에서 사용할 수 있도록 안정화되고 기능이 확장된 버전입니다. OpenAI API뿐만 아니라 100개 이상의 다른 LLM 프로바이더와도 함께 사용할 수 있어 특정 모델에 종속되지 않습니다.
OpenAI Agents SDK의 핵심 개념
SDK는 9가지 핵심 구성 요소를 중심으로 설계되어 있으며, 각 개념이 명확하게 분리되어 있어 이해하고 조합하기 쉽습니다.
에이전트(Agent)와 도구(Tool)
에이전트(Agent) 는 지시사항(instructions), 도구(tools), 가드레일(guardrails), 핸드오프(handoffs)를 갖춘 LLM입니다. 일반 파이썬 함수를 @function_tool 데코레이터로 도구로 등록하거나, MCP 서버를 도구로 연결하거나, OpenAI의 호스팅 도구(웹 검색, 코드 해석기 등)를 사용할 수 있습니다.
from agents import Agent, function_tool, Runner
import asyncio
@function_tool
def get_weather(city: str) -> str:
"""도시의 현재 날씨를 반환합니다."""
# 실제 날씨 API 호출 로직
return f"{city}의 현재 날씨: 맑음, 기온 22°C"
weather_agent = Agent(
name="날씨 에이전트",
instructions="사용자에게 정확한 날씨 정보를 제공하세요.",
tools=[get_weather],
)
async def main():
result = await Runner.run(weather_agent, "서울 날씨 알려줘")
print(result.final_output)
asyncio.run(main())
핸드오프(Handoff): 에이전트 간 작업 위임
핸드오프(Handoff) 는 에이전트가 특정 작업을 다른 전문화된 에이전트에게 위임하는 메커니즘입니다. LLM에게는 일반 도구(tool)로 표현되어, 모델이 스스로 판단하여 적절한 시점에 위임을 결정합니다.
from agents import Agent, handoff
# 전문화된 서브 에이전트 정의
billing_agent = Agent(
name="청구 에이전트",
instructions="청구 및 결제 관련 문의를 처리합니다."
)
refund_agent = Agent(
name="환불 에이전트",
instructions="환불 요청을 처리하고 환불 상태를 확인합니다."
)
# 트리아지 에이전트: 적절한 전문 에이전트로 라우팅
triage_agent = Agent(
name="고객 지원 에이전트",
instructions="고객 문의를 분석하고 적절한 전문 팀으로 연결합니다.",
handoffs=[billing_agent, handoff(refund_agent)]
)
가드레일(Guardrail): 입출력 검증
가드레일(Guardrail) 은 에이전트의 입력과 출력에 대한 안전 검사와 유효성 검증을 수행합니다. 두 가지 실행 모드가 있습니다.
병렬 실행(Parallel, 기본값): 가드레일이 에이전트 실행과 동시에 시작됩니다. 지연 시간이 가장 적지만, 가드레일 위반 시 에이전트 실행을 중단해야 합니다.
차단 실행(Blocking): 가드레일이 완료된 후에야 에이전트가 시작됩니다. 가드레일이 트리거되면 에이전트가 아예 실행되지 않아 토큰 낭비와 도구 부작용을 방지할 수 있습니다.
from agents import Agent, InputGuardrail, GuardrailFunctionOutput
async def content_policy_check(ctx, agent, input_data) -> GuardrailFunctionOutput:
"""입력 콘텐츠가 정책을 준수하는지 확인합니다."""
prohibited_topics = ["폭력", "불법"]
violated = any(topic in str(input_data) for topic in prohibited_topics)
return GuardrailFunctionOutput(
tripwire_triggered=violated,
output_info={"reason": "정책 위반 콘텐츠 감지"} if violated else None
)
safe_agent = Agent(
name="안전한 에이전트",
instructions="사용자를 도와주세요.",
input_guardrails=[InputGuardrail(guardrail_function=content_policy_check)]
)
샌드박스 에이전트와 실시간 음성 에이전트
SDK는 기본 에이전트 외에도 컨테이너 기반으로 장시간 실행되는 샌드박스 에이전트(Sandbox Agent) 및 GPT-Realtime API를 활용한 실시간 음성 에이전트(Realtime Voice Agent) 도 지원합니다. 음성 에이전트는 pip install 'openai-agents[voice]'로 설치할 수 있습니다.
트레이싱과 세션 관리
SDK는 에이전트 실행 흐름을 자동으로 기록하는 트레이싱(Tracing) 기능을 내장하고 있습니다. 핸드오프 경로, 도구 호출 내역, LLM 응답 등이 모두 추적되어 디버깅과 품질 개선에 활용할 수 있습니다. 세션(Session) 관리를 통해 대화 이력이 자동으로 유지되며, 긴 대화에서도 컨텍스트를 일관되게 관리할 수 있습니다.
OpenAI Agents SDK 설치 방법
# pip으로 설치
pip install openai-agents
# 음성 에이전트 지원 포함
pip install 'openai-agents[voice]'
# uv 패키지 관리자 사용 시
uv add openai-agents
환경 변수로 OpenAI API 키를 설정하면 바로 시작할 수 있습니다. 100개 이상의 다른 LLM을 사용하려면 LiteLLM 또는 해당 프로바이더의 설정을 지정하면 됩니다.
라이선스
OpenAI Agents SDK 프로젝트는 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.
OpenAI Agents SDK 공식 문서
OpenAI Agents SDK GitHub 저장소
더 읽어보기
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 