OpenAI 모델을 Python·TypeScript 코드에서 평범한 함수처럼 부를 수 있게 해 주는 공식 라이브러리로, HTTP 요청·인증키·JSON 처리를 대신 해 준다. 내 프로그램에 채팅·이미지·음성·임베딩 기능을 붙이거나 에이전트를 만들 때 쓴다.
| 패키지 | 하는 일 | 이럴 때 쓴다 |
|---|---|---|
openai | 모델 호출 | 앱에 대화·이미지·음성 기능 붙이기 |
openai-agents | 에이전트 실행 | 도구를 골라 쓰며 여러 단계로 일하는 에이전트 |
호출 방식은 두 가지다. 새로 시작한다면 responses를 쓰는 게 좋다. 웹 검색·파일 검색·코드 실행을 옵션 하나로 켜면 모델이 알아서 쓰기 때문에, 이런 도구를 직접 만들어 붙일 필요가 없다.
| 방식 | 특징 | 권장 |
|---|---|---|
client.chat.completions.create(...) | 모델 이름과 메시지 목록을 넘기면 답이 온다 | 이미 짜둔 코드는 계속 써도 된다 |
responses | 검색·코드 실행 같은 도구를 옵션으로 켠다 | 새 프로젝트 |
채팅 요청 형식은 사실상 업계 공용어가 됐다. 다른 회사 모델을 다루는 도구들도 "OpenAI 호환"으로 같은 모양의 요청을 받아 준다. 그래서 코드에서 서버 주소만 바꾸면 여러 모델을 같은 방식으로 부를 수 있어, 모델을 갈아탈 때 부담이 적다.
지시문과 쓸 수 있는 도구를 묶어 에이전트를 정의하고 러너에 넘기면 된다. 그러면 모델이 도구를 부르고, 결과를 보고, 다시 판단하는 반복이 자동으로 돈다. 여기에 아래 세 기능이 더해진다.
| 기능 | 하는 일 |
|---|---|
| 핸드오프 | 자기가 못 하는 일을 다른 에이전트에게 넘긴다 |
| 가드레일 | 입력과 출력이 규칙에 맞는지 동시에 검사하고, 어긋나면 바로 멈춘다 |
| 트레이싱 | 어떤 모델과 도구를 썼는지 기록해 대시보드에서 보여 준다 (기본으로 켜짐) |
에이전트가 이상하게 행동하면 트레이싱 기록부터 열어 보면 원인을 찾기 쉽다.
SDK는 여러 일을 보이지 않는 곳에서 대신 처리한다. 세밀하게 제어해야 하는 복잡한 시스템이라면 SDK가 무엇을 대신 해 주는지 먼저 알고 쓰는 게 안전하다.
가장 흔한 쓰임은 내 서비스 백엔드에서 모델을 부르는 통로로 두는 것이다. 요청 형식이 사실상 표준이라, OpenAI 모델이 아닌 모델을 부를 때도 이 SDK를 그대로 쓰는 경우가 많다.
| 어디서 | 어떻게 쓰나 |
|---|---|
| 웹·앱 백엔드 | 챗봇, 글 요약, 번역 같은 기능을 responses 호출 한 번으로 붙인다 |
| 사내 문서 검색 | 문서를 임베딩으로 바꿔 저장하고, 질문과 가까운 문서를 찾아 모델에게 답을 쓰게 한다 |
| 다른 모델 호출 | OpenAI 호환 서버나 로컬 모델에 서버 주소만 바꿔 같은 코드로 부른다 |
| 업무 자동화 에이전트 | openai-agents로 도구를 쓰는 에이전트를 만들고, 막히면 트레이싱으로 원인을 찾는다 |