무슨 일이 일어나고 있는가 — 종료 타임라인 전체

OpenAI는 2025년 8월 26일, Assistants API의 공식 종료(deprecation)를 선언하며 정확히 1년 후인 2026년 8월 26일을 서비스 완전 종료(sunset) 날짜로 못 박았습니다. 현재 날짜 기준으로 162일이 남아 있습니다. 종료 이후에는 /v1/assistants 및 /v1/threads 엔드포인트로 보내는 모든 API 호출이 실패하게 됩니다. (출처: OpenAI 공식 마이그레이션 가이드, platform.openai.com/docs/assistants/migration)

타임라인을 정리하면 다음과 같습니다. 2024년 12월 18일에는 Assistants API v1 베타 접근이 중단됐고, 이후 v2만 사용 가능해졌습니다. 2025년 8월 26일에는 공식 deprecated 선언과 함께 마이그레이션 가이드가 발표됐습니다. 지금 이 시각에도 Assistants API는 작동하지만, 공식적으로 ‘종료 예정’ 상태입니다. 그리고 2026년 8월 26일, 모든 것이 멈춥니다.

▲ 목차로 돌아가기

Assistants API가 베타를 못 벗어난 진짜 이유

많은 개발자들이 “Assistants API가 꽤 잘 작동하는데 왜 없애는가?”라는 의문을 품었습니다. 하지만 OpenAI가 공식 마이그레이션 문서에 남긴 말은 매우 직접적입니다. Assistants API는 출시부터 종료 시점까지 단 한 번도 베타 딱지를 떼지 못했습니다. 구조적 한계 때문이었습니다.

Assistants API의 핵심 구조는 네 가지 객체(Assistant, Thread, Run, Run Step)가 서로 얽혀 비동기 폴링 루프를 구성하는 방식이었습니다. Run이 진행 중일 때는 Thread 전체가 잠기고, 도구 호출이 발생하면 클라이언트가 requires_action 상태를 직접 처리해야 했습니다. 스케일이 커질수록 복잡성이 비선형으로 증가하는 구조였습니다.

Responses API는 이 네 가지를 근본부터 다시 설계했습니다. Assistant → Prompt(대시보드 버전 관리), Thread → Conversation(아이템 스트림), Run → Response(입력 → 출력, 동기적), Run Step → Item(범용 객체)으로 각각 대체했습니다. 복잡한 비동기 폴링이 사라지고, 단 한 번의 API 호출로 도구 루프 전체가 처리됩니다.

▲ 목차로 돌아가기

Responses API로 바꾸면 비용이 더 든다? 수치로 확인한 결과

실제 OpenAI 공식 문서에 기재된 수치는 이 예상을 정면으로 뒤집습니다. OpenAI는 Responses API의 내부 벤치마크 결과를 직접 공개하면서, Chat Completions API 대비 캐시 활용률이 40%에서 최대 80% 개선됐다고 명시했습니다. (출처: OpenAI 공식 Responses API 전환 가이드, 2026.03 기준)

캐시 활용률이 높아진다는 것은 동일한 시스템 프롬프트나 컨텍스트가 반복될 때 토큰 비용의 상당 부분을 절약한다는 의미입니다. 예를 들어 월 1,000만 토큰을 사용하는 서비스라면, 40% 절감만 적용해도 비용 구조가 크게 달라집니다. 이 수치가 중요한 이유는 OpenAI가 “전환하면 비용이 오른다”는 우려를 인식하고, 공식 문서에서 반박 근거를 직접 제시했기 때문입니다.

(출처: Ragwalla 마이그레이션 가이드, 2026.01 / OpenAI 공식 요금 페이지)

단, Web Search와 File Search 도구를 대규모로 사용하는 서비스라면 도구 호출 건당 비용이 새로 발생하므로 반드시 사전 계산이 필요합니다. 캐시 절감이 도구 비용을 상쇄하는지 여부는 서비스 구조에 따라 다릅니다.

▲ 목차로 돌아가기

Threads → Conversations: 자동 이전 도구가 없다는 것의 의미

OpenAI 공식 마이그레이션 가이드에는 이런 문장이 명시되어 있습니다. “We will not provide an automated tool for migrating Threads to Conversations.” (출처: platform.openai.com/docs/assistants/migration) 번역하면: Threads를 Conversations로 이전하는 자동화 도구는 제공하지 않는다. 이 한 문장이 실은 가장 중요한 실무 함정입니다.

Threads에 수십만 건의 대화 기록이 쌓여 있는 서비스라면, 직접 스크립트를 작성해 메시지를 추출하고 Conversations API 형식으로 변환·업로드해야 합니다. OpenAI가 제시한 백필(backfill) 예시 코드를 보면, Thread의 메시지를 페이지 단위로 순회하면서 content 타입에 따라 input_text / output_text로 분류해 Conversation Items 배열을 구성하는 방식입니다.

특히 응답 객체(Response)의 기본 보존 기간이 30일이라는 점을 주목해야 합니다. 상태 유지가 필요한 장기 대화 서비스라면 Conversations API를 우선 사용하고, 단순 체인 방식이라면 previous_response_id로도 충분합니다. 다만 두 가지를 혼용할 수 없으므로 아키텍처 결정을 먼저 내려야 합니다.

▲ 목차로 돌아가기

개념 대응표와 코드 전환 포인트

Assistants API와 Responses API는 개념 이름부터 달라서 처음에 혼란스럽습니다. 아래 표로 한 번에 정리합니다.

가장 자주 발생하는 전환 포인트 3가지

① Prompt는 코드에서 생성 불가 — 기존에 openai.beta.assistants.create()로 프로그램 방식으로 어시스턴트를 만들었다면, 이 방식은 더 이상 통하지 않습니다. Prompt는 오직 OpenAI 대시보드에서만 생성할 수 있으며, 생성된 Prompt ID를 코드에서 참조하는 방식으로 바뀝니다. 배포 파이프라인에서 Assistant를 자동 생성하던 팀이라면 워크플로 자체를 바꿔야 합니다.

② Structured Outputs 위치 변경 — Chat Completions의 response_format이 Responses API에서는 text.format으로 이동했습니다. 단순히 이름만 바뀐 게 아니라, JSON Schema 정의 방식도 달라졌으므로 코드 레벨에서 수정이 필요합니다.

③ Function Calling 형식 변경 — Responses API에서 함수 정의는 외부 태그드 방식(Chat Completions)에서 내부 태그드 방식으로 바뀌었고, 기본 strict 모드가 활성화됩니다. "type": "function" 래퍼가 사라지고 함수명·파라미터가 최상위로 올라오는 방식입니다.

▲ 목차로 돌아가기

마감 D-162, 지금 당장 해야 할 체크리스트

Ragwalla의 타임라인 분석(2026.01.28 업데이트)과 OpenAI 공식 가이드를 교차 분석해 3월 현재 시점 기준으로 단계별 행동을 정리했습니다.

▲ 목차로 돌아가기

Q&A — 가장 자주 묻는 질문 5가지

▲ 목차로 돌아가기

마치며 — 162일, 충분하지만 여유롭지는 않다

Assistants API 종료는 단순한 API 업데이트가 아닙니다. Assistant → Prompt, Thread → Conversation, Run → Response. 이름만 바뀐 게 아니라 설계 철학 자체가 바뀐 전환입니다. 특히 Threads 자동 이전 도구가 없다는 사실과 Prompt는 대시보드에서만 생성 가능하다는 사실, 이 두 가지는 기존 블로그 어디에서도 제대로 다루지 않은 핵심입니다.

개인적으로 이 전환에서 가장 흥미로운 지점은 비용입니다. 기능이 늘었으니 당연히 비용도 오를 것이라는 예상과 달리, 캐시 활용률 개선으로 오히려 비용이 줄어드는 구조가 됐습니다. 물론 File Search와 Web Search를 적극 사용하는 서비스라면 도구 호출 단가를 별도로 계산해야 하지만, 그것도 사전에 파악하면 충분히 관리 가능한 범위입니다.

162일은 준비하기에 충분한 시간이지만, 지금 시작하지 않으면 8월에 급하게 처리해야 할 양이 쌓입니다. 지금 당장 /v1/assistants 호출이 코드베이스 어디에 있는지 검색하는 것부터 시작하세요.

📚 본 포스팅 참고 자료

1. OpenAI 공식 Assistants 마이그레이션 가이드 — platform.openai.com/docs/assistants/migration
2. OpenAI 공식 Responses API 전환 가이드 — platform.openai.com/docs/guides/migrate-to-responses
3. Ragwalla — OpenAI Assistants API Shutdown 마이그레이션 가이드 (2026.01.28) — ragwalla.com
4. Microsoft Azure AI Foundry — Assistants API 개념 문서 — learn.microsoft.com
5. OpenAI Help Center — GPT-5.3 및 GPT-5.4 사용 한도 — help.openai.com