OpenAI Agents SDK 파이썬 5분 시작 가이드

작성자: AI·개발자 도구를 실무에서 쓰며 정리하는 블로그

최종 업데이트: 2026-04-20

검증 환경: Windows 11, Python 3.11.9, openai-agents 0.1.x

 

파이썬으로 AI 에이전트를 만들려다 길을 잃었다면 openai agents sdk를 먼저 보자. OpenAI가 직접 만든 얇은 에이전트 프레임워크로, 한 파일 10줄이면 첫 에이전트가 돈다. 이 글은 설치부터 자주 막히는 지점까지 5분 안에 끝내는 흐름을 정리한다.

왜 또 다른 프레임워크인가

LangChain은 강력하지만 체인·러너블·툴·메모리 개념이 겹쳐 입문 허들이 높다. 반면 Agents SDK는 설계 원칙을 세 가지로 고정했다. 에이전트(Agent), 툴 호출(Tool), 에이전트 간 이관(Handoff)이다. 이 세 개만 이해하면 기본 흐름이 끝난다.

또 하나의 차별점은 공식 후원이다. OpenAI 모델 업데이트가 나오면 SDK가 가장 먼저 대응하고, tracing 기능이 기본 제공돼 디버깅 시 OpenAI 플랫폼 대시보드에서 에이전트 호출 궤적을 그대로 확인할 수 있다. 실운영에 투입하려는 팀에게는 이 점이 선택의 결정 요인이 되기도 한다.

설치 전 준비 사항

세 가지만 맞추면 된다.

• Python 3.9 이상: 내부적으로 TypedDict의 NotRequired를 쓰기 때문. 3.10 이상을 권장한다.
• OPENAI_API_KEY 환경변수: 키가 없다면 OpenAI 플랫폼에서 발급받아 설정한다.
• 가상환경 사용: 프로젝트 간 의존성 충돌을 피하려면 venv나 conda를 쓴다.

python -m venv .venv
# macOS / Linux
source .venv/bin/activate
# Windows (PowerShell)
.venv\Scripts\Activate.ps1

pip install openai-agents

 

설치 직후 pip show openai-agents로 버전을 확인한다. 이 글은 0.1.x 기준이며, 메이저 버전이 올라가도 Agent·Runner API 시그니처는 유지되는 편이다.

첫 에이전트 10줄로 만들기

아래 코드를 first_agent.py에 저장한 뒤 python first_agent.py로 실행한다.

from agents import Agent, Runner

agent = Agent(
    name="Korean Assistant",
    instructions="한국어로 간결하게, 3문장 이내로 답하세요.",
    model="gpt-4.1-mini",
)

result = Runner.run_sync(agent, "파이썬에서 가상환경을 쓰는 이유를 알려줘.")
print(result.final_output)

 

실행하면 몇 초 뒤 콘솔에 한국어 답변이 출력된다. 여기서 주목할 것은 세 가지다. 먼저 Agent는 이름·지시문·모델만으로 완성된다. 다음으로 Runner.run_sync는 내부에서 메시지 루프·툴 호출·재시도를 감싸 블로킹 방식으로 최종 결과만 반환한다. 마지막으로 result.final_output은 모델이 마지막 단계에서 내놓은 텍스트다. 중간 단계가 필요하면 result.raw_responses를 뜯어보면 된다.

자주 막히는 지점 3가지

같은 스크립트가 여러 환경에서 깨지는 포인트는 거의 이 세 가지다.

1. AuthenticationError: OPENAI_API_KEY 환경변수가 비어 있거나 셸 세션에 적용되지 않은 경우. echo $OPENAI_API_KEY (Windows는 echo %OPENAI_API_KEY%)로 먼저 확인한다.
2. ImportError: cannot import name 'Agent': 패키지명을 pip install agents로 잘못 설치한 경우가 대부분이다. 올바른 명은 openai-agents, 임포트는 from agents import ...다.
3. 툴 반환값 직렬화 실패: 파이썬 기본 타입이 아닌 객체를 그대로 반환하면 내부 JSON 변환에서 실패한다. 반환 타입은 pydantic.BaseModel 또는 dataclass로 정리해야 한다.

다음 단계: 도구·스트리밍·핸드오프

기본 호출이 돌았다면 그다음 배울 축은 세 개다. 첫째, @function_tool 데코레이터로 외부 API 호출이나 로컬 함수를 툴로 붙인다. 둘째, Runner.run_streamed로 응답 스트리밍을 받아 UI에 토큰 단위로 뿌린다. 셋째, 에이전트 여러 개를 만들고 handoffs=[...]로 라우팅해서 멀티 에이전트를 구성한다. 이 세 가지를 묶으면 프로덕션급 워크플로가 나온다.

지금 바로 다음 실험을 돌리고 싶다면 아래 관련 글이 출발점이 된다.

 

함께 보면 좋은 글

• OpenAI API 키 발급과 환경변수 설정 완벽 가이드
• Claude vs ChatGPT 개발자가 골라야 할 도구

참고 자료

• GitHub: openai/openai-agents-python
• OpenAI Agents SDK 공식 문서
• OpenAI Platform 문서