Assistants API 종료, 이렇게 막힙니다

결론부터 말씀드리면, Assistants API는 2026년 8월 26일 완전히 꺼집니다. OpenAI가 2025년 8월 26일 공식 발표했고, 정확히 1년 뒤 일몰 예정입니다. 남은 시간이 5개월 남짓인데, 아직 전환 준비를 안 했다면 지금이 마지막 적기입니다.

Assistants API가 종료되는 정확한 이유

OpenAI는 2025년 8월 26일, Assistants API 베타를 종료(deprecate)하고 정확히 1년 뒤인 2026년 8월 26일을 공식 일몰(sunset) 날짜로 공표했습니다. 이미 Responses API가 기능 동등성(feature parity)에 도달했다는 것이 공식적인 이유입니다. (출처: OpenAI 커뮤니티 공식 발표, 2025.08.26)

솔직히 말하면, Assistants API는 추론 모델이 등장하기 전 시대에 설계된 “에이전트 V1″이었습니다. OpenAI 스스로도 공식 문서에 “Assistants were our early take on how agents could be built (before reasoning models)”라고 명시했습니다. GPT-5 같은 추론 모델이 등장한 지금은, 이전 방식이 오히려 성능을 제한하는 구조가 됐습니다.

가장 중요한 사실 하나는 이겁니다. Responses API는 이미 전체 토큰 활동량에서 Chat Completions를 추월했습니다. OpenAI가 직접 밝힌 수치입니다. 단순한 버전 교체가 아니라, 플랫폼 전략 자체가 Responses API 중심으로 완전히 전환됐다는 신호입니다. (출처: OpenAI 공식 공지문, platform.openai.com/docs/assistants/migration)

▲ 목차로 돌아가기

비용이 ‘알아서’ 폭증했던 구조적 원인

Assistants API를 실제로 써본 개발자라면 공감할 부분입니다. 작은 챗봇 하나 운영하는데 월 비용이 예상보다 5~10배 나왔던 경험, 의외로 흔한 일이었습니다. 이건 관리 부실이 아니라, 구조적 함정이었습니다.

도구 비용도 따로 붙었습니다. Code Interpreter는 세션당 $0.03, File Search 벡터 저장소는 GB당 하루 $0.10이었습니다. (출처: OpenAI 공식 Assistants API FAQ) 파일 크기가 아닌 벡터화된 데이터 크기 기준이라 예측이 더 어려웠고, 100개 세션이 동시에 열리면 Code Interpreter 비용만 하루 $3 이상 고정 지출이 됩니다. 이 숫자는 작아 보이지만, 트래픽이 조금만 올라가면 즉시 체감됩니다.

Responses API는 이 구조를 바꿨습니다. OpenAI 내부 테스트 결과 Chat Completions 대비 캐시 활용률이 40~80% 향상됐습니다. 같은 워크플로우를 Responses API로 돌리면 상당한 비용 절감이 가능하다는 뜻입니다. (출처: OpenAI 공식 가이드, platform.openai.com/docs/guides/migrate-to-responses)

▲ 목차로 돌아가기

Responses API, 이름만 바뀐 게 아닙니다

겉으로 보면 Assistants → Responses처럼 이름만 바뀐 것 같지만, 개념 구조가 통째로 바뀌었습니다. 아래 표가 핵심입니다.

Responses API에서 새로 추가된 기능은 단순한 업그레이드 수준이 아닙니다. Web Search, File Search, Computer Use, Code Interpreter, 원격 MCP 서버 연동이 기본 내장 도구로 들어왔고, Deep Research도 지원됩니다. 하나의 API 요청 안에서 여러 도구가 순차 또는 병렬로 호출되는 에이전트 루프가 네이티브로 작동합니다.

GPT-5 같은 추론 모델을 Responses API로 쓰면 SWE-bench에서 동일 프롬프트·동일 설정 기준 3% 성능 향상이 확인됐습니다. 수치 자체는 작아 보여도, 코드 생성·버그 수정 같이 정확도 한 끗 차이가 중요한 작업에서는 실질적인 차이가 납니다. (출처: OpenAI 공식 가이드, 2026년 기준)

▲ 목차로 돌아가기

막상 전환하면 여기서 막힙니다

가장 많은 개발자가 혼란을 겪은 지점은 Prompts(구 Assistants)를 API로 생성할 수 없다는 점입니다. 공식 문서를 보면 이렇게 명시돼 있습니다. “Their replacement, prompts, can only be created in the dashboard.”

두 번째 함정은 Thread → Conversation 자동 마이그레이션 도구가 없다는 점입니다. OpenAI 공식 문서에 직접 명시돼 있습니다. “We will not provide an automated tool for migrating Threads to Conversations.” 기존 Thread에 쌓인 대화 히스토리를 Conversation으로 백필하는 작업은 직접 코딩해야 합니다. (출처: platform.openai.com/docs/assistants/migration)

세 번째는 함수 정의 방식이 달라졌다는 점입니다. Chat Completions에서는 외부 태그 방식(externally tagged polymorphism), Responses API에서는 내부 태그 방식(internally-tagged)입니다. 그리고 함수 strict 옵션이 기본값으로 켜져 있습니다. 기존 코드를 그대로 갖다 붙이면 즉시 오류가 납니다.

네 번째로, Structured Outputs 정의도 바뀌었습니다. Chat Completions의 response_format 필드가 Responses API에서는 text.format으로 이동했습니다. 단순히 필드 이름만 찾아 바꾸는 게 아니라 JSON 스키마 구조 자체를 다시 작성해야 합니다.

▲ 목차로 돌아가기

실제 마이그레이션 순서와 코드 변경점

OpenAI 공식 마이그레이션 가이드는 다음 순서를 권장합니다. 일괄 전환이 아니라 점진적 마이그레이션(incremental migration)이 가능한 구조입니다. 트래픽이 많은 서비스라면 이 점을 활용하는 게 안전합니다.

Thread를 Conversation으로 백필할 때 공식 가이드가 제시하는 Python 패턴은 이렇습니다.

# Thread 메시지를 Conversation Items로 변환 (OpenAI 공식 예시)
thread_id = "thread_EIpHrTAVe0OzoLQg3TXfvrkG"
messages = []
for page in openai.beta.threads.messages.list(thread_id=thread_id, order="asc").iter_pages():
messages += page.data
items = []
for m in messages:
item = {"role": m.role, "content": []}
for content in m.content:
if content.type == "text":
item_type = "input_text" if m.role == "user" else "output_text"
item["content"].append({"type": item_type, "text": content.text.value})
items.append(item)
# 변환된 items로 Conversation 생성
conversation = openai.conversations.create(items=items)

이 패턴에서 주의할 점은 image_url 콘텐츠 타입도 별도로 처리해야 한다는 점입니다. 텍스트만 처리하다가 이미지 포함 Thread에서 누락이 생기는 경우가 많습니다. 반드시 Thread 내 콘텐츠 타입을 사전에 전수 조사하세요.

▲ 목차로 돌아가기

ZDR 환경이라면 이 설정은 필수입니다

Responses API는 기본적으로 대화 상태를 서버 측에 저장합니다(store: true). 응답 객체는 기본 30일 TTL로 보관되고, 대시보드 Logs 페이지에서 확인 가능합니다.

이 패턴은 금융, 의료, 법률 분야처럼 데이터 잔류 규정이 엄격한 산업에서 Responses API를 안전하게 도입하는 현실적인 방법입니다. ZDR 계약 조직에서는 OpenAI가 자동으로 store=false를 강제 적용합니다. (출처: OpenAI 공식 마이그레이션 가이드, 2026년 기준)

덧붙여, Conversation 객체에 연결된 Items는 30일 TTL이 적용되지 않습니다. 독립 Response 객체는 30일이지만, Conversation에 포함된 경우 별도 정책을 따른다는 점을 명심하세요. 이 차이를 모르면 장기 운영 서비스에서 데이터 유실이 생길 수 있습니다.

▲ 목차로 돌아가기

Q&A — 가장 많이 헷갈리는 것들

▲ 목차로 돌아가기

마치며 — 총평

Assistants API 종료가 “나는 해당 없다”라고 넘기기 쉬운 이슈인 건 압니다. 하지만 OpenAI 서비스를 연동한 앱을 운영 중이라면, 혹은 지금 빌드 중이라면 이 전환은 피할 수 없습니다. 특히 Thread 자동 마이그레이션이 없다는 점과 Prompt를 API로 동적 생성할 수 없다는 점은 생각보다 작업량이 큰 변경입니다.

한 가지 개인 의견을 드리자면, 이번 전환은 단순 API 교체가 아니라 아키텍처 재검토 기회입니다. Responses API의 캐시 효율 향상과 에이전트 루프 내장 기능은 비용과 성능 양쪽에서 실질적으로 더 나은 선택입니다. 한 번 제대로 전환하면 오히려 이전보다 운영이 깔끔해집니다.

남은 시간은 5개월입니다. 전환 우선순위는 ①동적 Assistant 생성 코드 → ②Thread 히스토리 보존 여부 판단 → ③함수 정의 및 Structured Outputs 형식 수정 순서로 잡으면 됩니다. 지금 시작하면 충분히 여유 있게 대응할 수 있습니다.

▲ 목차로 돌아가기

📎 본 포스팅 참고 자료

1. OpenAI 공식 Assistants API 마이그레이션 가이드 — platform.openai.com/docs/assistants/migration
2. OpenAI 공식 Chat Completions → Responses API 전환 가이드 — platform.openai.com/docs/guides/migrate-to-responses
3. OpenAI 커뮤니티 공식 발표 (2025.08.26) — community.openai.com/assistants-api-deprecation