오픈AI 어시스턴트 API 만들기 — GPTs 대신 직접 구현

Published on Jake

GPTs(OpenAI가 제공하는 노코드 AI 챗봇 빌더)로 만든 어시스턴트는 편리하지만 한계가 있다. 대화 흐름을 세밀하게 제어하거나, 외부 서비스와 연동하거나, 응답을 프로그램 안에서 직접 가공해야 할 때는 GPTs만으로 해결이 안 된다. 이럴 때 쓰는 것이 Assistants API(어시스턴트 API)다.

Assistants API는 OpenAI가 제공하는 서버사이드 AI 어시스턴트 구축 인터페이스다. 대화 맥락을 서버에서 관리하고, 코드 실행이나 파일 검색 같은 도구를 붙일 수 있으며, Python 코드 몇 줄만으로 GPTs에서 할 수 없는 수준의 커스텀 어시스턴트를 만들 수 있다. 다만 한 가지 중요한 사실이 있다. OpenAI는 Assistants API를 2026년 8월 이후 공식 종료(deprecated) 예정으로 발표했다. 지금 배워두면 현재 프로젝트에 바로 쓸 수 있고, 이후 Responses API로 이전할 때 개념적 기반도 된다.

이 글은 2026년 6월 현재 작동하는 Assistants API v2 기준으로 작성했다.

Assistants API가 GPTs와 다른 점

GPTs는 OpenAI 플랫폼 안에서만 동작한다. 사용자가 ChatGPT 사이트나 앱에 접속해야 쓸 수 있고, 응답을 내 서비스 안에서 다루려면 별도로 연결하는 방법이 없다. Assistants API는 반대다. 내 서버나 로컬 환경에서 직접 API를 호출해 어시스턴트를 만들고, 대화 흐름을 관리하며, 응답을 내 앱 로직 안에서 바로 처리할 수 있다.

구체적인 차이를 정리하면 다음과 같다.

COMPARISON
A
GPTs
작동 환경
ChatGPT 플랫폼 내부에서만
코딩 필요 여부
불필요 (노코드)
응답 처리
플랫폼 안에서만 확인 가능
외부 서비스 연동
제한적 (Action 기능)
B
Assistants API
작동 환경
내 서버, 앱, 로컬 어디서든
코딩 필요 여부
Python 등 코드 필요
응답 처리
내 앱 로직 안에서 직접 가공
외부 서비스 연동
자유롭게 구현 가능

Thread, Message, Run — 세 가지 핵심 구조

Assistants API를 이해하려면 세 가지 개념부터 잡아야 한다. 이 세 가지가 API 전체 구조의 뼈대다.

Thread(스레드)는 하나의 대화 세션이다. 사용자가 어시스턴트와 나누는 대화 전체가 하나의 Thread에 담긴다. OpenAI 서버에 저장되므로, 앱이 꺼졌다 켜져도 대화 기록이 유지된다. 사용자 한 명당 하나씩 만들면 된다.

Message(메시지)는 Thread 안에 추가하는 발언이다. 사용자가 질문하면 user 역할로 메시지를 Thread에 추가하고, 어시스턴트가 답하면 assistant 역할의 메시지가 생긴다. 채팅창의 말풍선 하나하나가 Message다.

Run(런)은 “이 Thread를 지금 이 어시스턴트로 실행해줘”라는 요청이다. Run을 생성하면 OpenAI 서버가 Thread 안의 대화 내역을 읽고 어시스턴트 설정에 따라 응답을 만들어 Thread에 추가한다. Run이 완료되면 최신 Message를 읽어 응답을 가져온다.

흐름을 한 줄로 요약하면 이렇다. Thread 만들기 → 사용자 메시지 추가 → Run 실행 → 완료 기다리기 → 응답 메시지 읽기.

API 키 발급과 환경 준비

코드를 실행하려면 OpenAI API 키가 필요하다. API 키(Application Programming Interface Key — 프로그램이 OpenAI 서버에 접근할 때 본인임을 증명하는 고유 비밀번호)는 OpenAI 플랫폼에서 발급받는다. 무료 크레딧이 제공되므로 처음 시작할 때는 비용 걱정 없이 테스트할 수 있다.

키를 발급했으면 Python 환경에 openai 패키지를 설치한다.

pip install openai

발급받은 API 키는 환경변수로 설정하는 것이 안전하다. 코드에 직접 적어두면 실수로 외부에 노출될 수 있다.

# macOS / Linux 터미널
export OPENAI_API_KEY="sk-..."

# Windows PowerShell
$env:OPENAI_API_KEY = "sk-..."

Python으로 어시스턴트 만들고 대화하기

아래는 어시스턴트를 생성하고, Thread를 만들고, 메시지를 보내고, 응답을 받는 전체 흐름을 담은 Python 코드다. 2026년 6월 기준 openai Python SDK v1.x 에서 작동한다.

import time
from openai import OpenAI

client = OpenAI()  # OPENAI_API_KEY 환경변수 자동 인식

# 1. 어시스턴트 생성 (한 번만 만들면 재사용 가능)
assistant = client.beta.assistants.create(
    name="파이썬 튜터",
    instructions="당신은 파이썬 입문자를 돕는 친절한 튜터입니다. 코드 예시를 들어 쉽게 설명하세요.",
    model="gpt-4o",
)
print(f"어시스턴트 ID: {assistant.id}")

# 2. Thread 생성 (사용자 세션 하나에 하나)
thread = client.beta.threads.create()
print(f"Thread ID: {thread.id}")

# 3. 사용자 메시지 추가
client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="리스트 컴프리헨션이 뭔가요? 짧게 설명해주세요.",
)

# 4. Run 실행
run = client.beta.runs.create(
    thread_id=thread.id,
    assistant_id=assistant.id,
)

# 5. Run 완료 대기 (폴링 방식)
while run.status in ["queued", "in_progress"]:
    time.sleep(1)
    run = client.beta.runs.retrieve(
        thread_id=thread.id,
        run_id=run.id,
    )

# 6. 응답 메시지 읽기
if run.status == "completed":
    messages = client.beta.threads.messages.list(thread_id=thread.id)
    latest = messages.data[0]  # 가장 최신 메시지 = 어시스턴트 응답
    print(latest.content[0].text.value)
else:
    print(f"Run 실패: {run.status}")

코드에서 주목할 부분이 있다. client.beta.runs.retrieve()로 상태를 계속 확인하는 폴링(polling) 방식을 쓴다. Run은 즉시 끝나지 않고 OpenAI 서버가 처리하는 동안 queued나 in_progress 상태가 된다. 완료되면 completed로 바뀐다. 실패 시에는 failed나 expired가 된다.

어시스턴트 객체는 한 번 만들면 assistant.id로 계속 재사용할 수 있다. 서비스를 배포할 때는 어시스턴트를 미리 만들고 ID를 환경변수로 관리하는 방식이 일반적이다.

웹사이트나 앱에 AI 기능을 붙이는 방법이 궁금하다면 웹사이트에 AI 기능 추가하는 방법도 참고할 수 있다.

STEP BY STEP
Assistants API 호출 순서
airusk.com
1
어시스턴트 생성
이름, 지시사항(instructions), 사용 모델을 설정해 어시스턴트를 만든다. 한 번 생성하면 ID로 계속 재사용 가능.
2
Thread 생성
사용자 세션마다 Thread를 하나 만든다. 대화 기록이 서버에 저장되어 앱을 껐다 켜도 이어진다.
3
메시지 추가 후 Run 실행
사용자 입력을 Thread에 Message로 추가하고 Run을 생성한다. OpenAI 서버가 처리를 시작한다.
완료 확인 후 응답 수신
Run 상태가 completed로 바뀌면 Thread의 최신 Message를 읽어 응답을 가져온다.

알아두면 쓸모 있는 추가 기능

기본 대화 외에 Assistants API에서 자주 쓰이는 기능이 두 가지 더 있다.

Code Interpreter(코드 인터프리터)는 어시스턴트가 직접 Python 코드를 샌드박스(보호된 실행 환경) 안에서 실행할 수 있게 한다. 데이터 분석, 차트 생성, 수식 계산 같은 작업을 자연어 요청으로 처리할 수 있다. 어시스턴트 생성 시 tools=[{"type": "code_interpreter"}]를 넣으면 활성화된다.

File Search(파일 검색)는 PDF, 텍스트 파일, 문서를 업로드해두면 어시스턴트가 그 내용을 기반으로 답변하는 기능이다. 회사 내부 문서나 매뉴얼을 기반으로 답하는 Q&A 봇을 만들 때 유용하다. RAG(Retrieval-Augmented Generation — 외부 문서에서 관련 내용을 먼저 찾아 답변에 활용하는 방식)를 별도 구현 없이 쓸 수 있다는 점이 장점이다.

Function Calling(함수 호출)은 어시스턴트가 외부 API나 내 코드의 함수를 호출하도록 할 수 있는 기능이다. 날씨 조회, 예약 시스템 연동, 데이터베이스 조회 같은 실시간 정보가 필요한 작업에 활용된다. Run 상태가 requires_action이 되면 해당 함수를 실행하고 결과를 다시 전달하는 방식으로 동작한다.

커스텀 AI 모델을 훈련해 더 나아가고 싶다면 나만의 AI 모델 직접 훈련하기도 살펴볼 수 있다.

FAQ

Q1) Assistants API를 쓰면 비용이 얼마나 드나요?

사용한 토큰(입출력 텍스트 분량)만큼 과금된다. gpt-4o 기준으로 입력 1백만 토큰당 약 2.5달러, 출력은 10달러 수준이다. 일반적인 테스트나 소규모 서비스 수준이라면 월 몇 달러 안에서 처리되는 경우가 많다. Thread에 저장된 대화 기록도 토큰으로 계산되므로, 긴 대화가 쌓이면 비용이 늘어날 수 있다. File Search나 Code Interpreter는 사용 시 추가 요금이 붙는다.

Q2) Thread는 얼마나 오래 유지되나요?

Thread 자체는 명시적으로 삭제하지 않으면 OpenAI 서버에 남아 있다. 단, 마지막 Run으로부터 일정 시간이 지나면 Run이 만료(expired)될 수 있으므로 장기간 대화를 이어가려면 새 Run을 생성해야 한다. Thread ID를 DB에 저장해두면 나중에 같은 대화를 이어가는 것이 가능하다.

Q3) Assistants API가 2026년 8월에 종료된다면 지금 배울 필요가 있나요?

있다. 당장 운영 중인 프로젝트에는 계속 쓸 수 있고, Thread, Message, Run의 개념 구조는 후속인 Responses API에서도 Conversations, Items 등 유사한 형태로 이어진다. 지금 익혀두면 이전 작업도 빠르게 따라갈 수 있다. OpenAI는 마이그레이션(이전) 가이드를 공식 문서에서 제공하고 있다.

Q4) GPTs를 이미 쓰고 있는데 굳이 Assistants API로 넘어올 필요가 있나요?

GPTs로 충분하다면 굳이 넘어올 필요는 없다. Assistants API가 필요한 경우는 두 가지다. 내 서비스나 앱 안에 AI를 직접 내장하고 싶을 때, 그리고 응답을 프로그램으로 가공하거나 외부 시스템과 연동해야 할 때다. 단순 챗봇이나 FAQ 용도라면 GPTs가 더 빠르고 편하다.

댓글 남기기