오픈AI SDK

OpenAI의 GPT 시리즈와 기타 모델을 Python, TypeScript 등에서 쓸 수 있는 공식 라이브러리.

OpenAI 모델을 코드로 부르는 통로

GPT 같은 모델은 결국 OpenAI 서버 어딘가에서 돌아간다. 내 프로그램에서 그 모델에게 말을 걸고 답을 받아오려면 매번 HTTP 요청을 직접 만들고, 헤더에 인증키를 넣고, 돌아온 JSON을 뜯어봐야 한다. 귀찮고 실수하기 쉬운 이 과정을 대신 처리해 주는 게 OpenAI SDK다. openai 패키지를 설치하고 클라이언트 객체를 하나 만들면, 채팅·이미지·음성·임베딩 같은 기능을 평범한 함수 호출처럼 쓸 수 있다. Python과 JavaScript/TypeScript용이 공식으로 나와 있어서 두 진영 모두 같은 감각으로 다룬다.

실제로 어떻게 부르나

가장 많이 쓰는 건 대화형 호출이다. client.chat.completions.create(...)에 모델 이름과 주고받은 메시지 목록을 넘기면 모델의 답이 돌아온다. 흥미로운 건 이 요청 형식이 사실상 업계 공용어가 됐다는 점이다. 다른 회사 모델을 쓰는 도구들도 "OpenAI 호환"을 내세우며 같은 모양의 요청을 받아준다. 덕분에 코드에서 서버 주소만 바꿔 끼우면 여러 모델을 같은 방식으로 부를 수 있어서, 모델을 갈아탈 때 부담이 적다.

최근에는 OpenAI가 responses라는 새 방식을 밀고 있다. 기존 채팅 방식과 목적은 같지만, 웹 검색·파일 검색·코드 실행 같은 기능을 옵션 하나로 켜서 모델이 알아서 쓰게 만들 수 있다. 예전에는 이런 도구를 직접 구현해 붙여야 했는데, 이제는 SDK가 그 배관 작업을 떠안는다. 새로 시작하는 프로젝트라면 이쪽을 권장하고, 이미 채팅 방식으로 짜둔 코드는 급히 바꿀 필요 없이 계속 쓸 수 있다.

단순 호출을 넘어 에이전트로

모델을 한 번 부르는 걸 넘어, 스스로 도구를 골라 쓰고 여러 단계를 밟아 일을 끝내는 에이전트를 만들고 싶을 때가 있다. 이걸 위한 별도 라이브러리가 openai-agents, 이른바 Agents SDK다. 뼈대는 단순하다. 지시문과 쓸 수 있는 도구를 묶은 에이전트를 정의하고, 러너에게 넘겨 실행하면 모델이 도구를 부르고 결과를 받아 다시 판단하는 반복 루프가 자동으로 돌아간다.

여기에 세 가지 개념이 더 붙는다. 한 에이전트가 자기가 못 할 일을 다른 에이전트에게 넘기는 핸드오프, 입력과 출력이 규칙에 맞는지 병렬로 검사해 이상하면 즉시 멈추는 가드레일, 그리고 어떤 모델을 부르고 어떤 도구를 썼는지 전 과정을 기록해 대시보드에서 들여다보게 해 주는 트레이싱이다. 특히 트레이싱은 기본으로 켜져 있어서, 에이전트가 왜 이상하게 행동하는지 추적할 때 요긴하다. 다만 편의를 위해 감춰둔 부분이 많은 만큼, 세밀한 제어가 필요한 복잡한 시스템에서는 SDK가 무엇을 대신 해 주고 있는지 이해하고 쓰는 편이 좋다.