Assistants API가 사라진다 — 공식 일정 정리

결론부터 말씀드리면, OpenAI Assistants API는 2025년 8월 26일 deprecated 처리됐고, 2026년 8월 26일 완전 종료됩니다. 공식 문서(platform.openai.com/docs/guides/assistants/migration)에 명시된 내용입니다. 지금 Assistants API를 프로덕션에서 쓰고 있다면 남은 시간은 약 5개월입니다.

OpenAI는 이 변화를 “기능 패리티(feature parity) 달성 이후의 자연스러운 전환”이라고 설명했습니다. Assistants API에서 가능했던 것들, 즉 스레드 관리, 파일 검색, 코드 인터프리터, 함수 호출이 모두 Responses API로 흡수됐다는 의미입니다. 기존에 익숙하던 Assistant → Thread → Run → Run Steps 흐름은 Prompt → Conversation → Response → Items로 이름이 바뀌고 구조도 달라졌습니다.

▲ 목차로 돌아가기

Responses API가 뭐가 다른가요?

OpenAI Responses API는 Chat Completions API의 ‘진화형’입니다. 공식 문서(platform.openai.com/docs/guides/responses-vs-chat-completions)에서는 “모든 신규 프로젝트는 Responses API를 권장한다”고 명시하고 있습니다. Chat Completions는 지원을 유지하지만, 사실상 기능 추가 없이 유지만 되는 수준입니다.

구조적으로 가장 큰 차이는 에이전틱 루프가 기본 내장됐다는 점입니다. 기존에는 웹 검색, 파일 검색, 컴퓨터 사용 같은 도구를 직접 구현해야 했습니다. Responses API에서는 API 요청 하나 안에서 모델이 여러 도구를 자동으로 호출하고 결과를 이어받습니다. MCP(Model Context Protocol) 원격 서버 연동도 네이티브로 지원됩니다.

(출처: OpenAI 공식 비교 문서 — platform.openai.com/docs/guides/responses-vs-chat-completions)

▲ 목차로 돌아가기

비용이 줄어든다더니, 이 조건이 있었습니다

“Responses API로 바꾸면 비용이 줄어든다”는 말은 캐시 적중 조건을 전제로 합니다. OpenAI 공식 쿡북(developers.openai.com/cookbook/examples/responses_api/reasoning_items)에 따르면, Chat Completions에서 Responses API로 전환했을 때 캐시 활용률이 40%에서 80%로 올라갔다고 명시돼 있습니다. o4-mini 기준으로 캐시된 입력 토큰은 비캐시 대비 75% 저렴합니다.

그런데 여기서 걸립니다. 캐싱은 프롬프트 길이가 1,024 토큰을 넘어야 적용됩니다. 짧고 단발성인 요청, 예를 들어 간단한 분류 작업이나 1회성 요약이라면 캐시 히트가 거의 발생하지 않아 비용 절감 효과를 기대하기 어렵습니다. “Responses API = 저렴하다”는 공식이 성립하는 건 반복 패턴이 있는 멀티턴 대화, 혹은 동일한 시스템 프롬프트를 다량으로 재사용하는 배치성 작업에 한정됩니다.

실생활 해석: 1만 번의 동일 패턴 요청에서 8달러 넘게 줄어드는 수치지만, 이게 가능하려면 1,024토큰 이상의 공통 프롬프트 구간이 반복 요청 사이에서 동일하게 유지돼야 합니다. 매번 프롬프트 앞부분이 달라진다면 캐시 히트가 발생하지 않습니다.

▲ 목차로 돌아가기

Thread 데이터 어떻게 되나요?

마이그레이션에서 가장 당황스러운 부분이 이겁니다. OpenAI 공식 마이그레이션 가이드는 “Thread에서 Conversation으로의 자동화된 마이그레이션 도구는 제공하지 않는다”고 명시합니다. 기존에 쌓아둔 Thread 기록은 직접 스크립트를 짜서 변환해야 한다는 뜻입니다.

공식 문서에서 제공하는 예시 코드(Python)를 보면, 기존 Thread의 메시지를 순서대로 꺼내 role과 content를 분리한 뒤 Conversation의 items 형식으로 재구성하는 방식입니다. 텍스트 메시지는 비교적 변환이 간단하지만, image_url 타입이나 파일 첨부가 포함된 메시지는 추가 처리가 필요합니다. 운영 중인 서비스에 대화 히스토리가 수십만 건 있다면 이 작업이 가벼운 일이 아닙니다.

▲ 목차로 돌아가기

ZDR 환경이라면 이야기가 달라집니다

Responses API의 핵심 장점 중 하나는 store: true로 상태를 유지하는 것입니다. 이전 추론 아이템을 서버에 저장해두고 다음 턴에 활용하면 캐시 히트율이 높아지고 비용도 줄어듭니다. 그런데 ZDR(Zero Data Retention) 계약을 맺은 엔터프라이즈 고객은 이걸 그대로 쓸 수 없습니다.

ZDR 환경에서는 OpenAI가 강제로 store=false를 적용합니다. 추론 아이템을 서버에 저장하지 않으니 stateful한 이점이 사라집니다. 이를 보완하기 위해 OpenAI는 ‘암호화된 추론 아이템(encrypted reasoning items)’을 제공합니다. 추론 결과를 암호화해서 클라이언트 쪽으로 돌려주고, 다음 요청 시 이를 포함해 보내면 OpenAI 서버가 메모리 내에서 복호화해 사용한 뒤 즉시 폐기합니다.

이게 어떤 의미냐면, ZDR 고객은 암호화된 추론 아이템을 직접 관리하는 별도 로직이 필요합니다. 단순히 API 엔드포인트만 바꾸는 마이그레이션이 아니라, 응답 객체에서 encrypted_content를 파싱하고 다음 요청에 포함하는 코드를 추가해야 합니다. (출처: OpenAI Responses API 쿡북 — developers.openai.com/cookbook/examples/responses_api/reasoning_items)

▲ 목차로 돌아가기

추론 모델 + Responses API 조합, 실제 수치로 봤습니다

“Responses API가 추론 모델에서 더 잘 작동한다”는 말을 들어봤을 겁니다. 이 부분은 수치로 뒷받침이 됩니다. OpenAI 내부 테스트 결과, 동일한 프롬프트와 셋업에서 SWE-bench 벤치마크 기준으로 약 3% 성능 개선이 확인됐습니다. (출처: OpenAI 공식 Responses API 쿡북)

3%라고 하면 적어 보이지만, 이 수치가 의미 있는 이유가 있습니다. 이 개선은 추론 아이템을 이전 턴에서 넘겨받을 때 발생합니다. 추론 모델(o3, o4-mini 등)은 각 턴마다 내부 사고 과정을 생성하는데, 그 다음 턴에서 이 사고 흐름을 참조할 수 있으면 단순히 입출력 텍스트만 이어받는 것보다 더 정교하게 문제를 이어갑니다. 특히 함수 호출 루프처럼 여러 단계를 거치는 작업에서 이 차이가 누적됩니다.

▲ 목차로 돌아가기

마이그레이션 할 때 막히는 지점

막상 코드를 바꿔보면 몇 가지 포인트에서 예상보다 시간이 걸립니다. 먼저 함수 정의 방식이 바뀌었습니다. Chat Completions에서는 {"type": "function", "function": {...}} 형태였는데, Responses API에서는 {"type": "function", "name": "...", "parameters": {...}}처럼 내부 태그 방식으로 바뀌었습니다. 또한 Responses API에서는 함수가 기본적으로 strict 모드입니다. 기존에 느슨하게 정의했던 파라미터 스키마가 있다면 validation 오류가 발생할 수 있습니다.

두 번째는 Structured Outputs 정의 위치입니다. 기존에는 response_format 필드를 썼지만, Responses API에서는 text.format으로 이동했습니다. 이 부분을 빠뜨리면 JSON schema 출력이 적용되지 않아 파싱 오류가 생깁니다.

세 번째는 오디오가 아직 미지원이라는 점입니다. 공식 비교 문서에 “Coming soon”으로 표시돼 있습니다. 음성 기반 인터페이스를 Assistants API로 구현 중이었다면 Responses API로의 완전 전환이 어렵습니다. 오디오 기능이 필요한 부분은 Realtime API나 Chat Completions를 병행할 수밖에 없습니다. (확인 필요: 오디오 지원 출시 일정은 공개되지 않음)

개인적인 판단을 덧붙이자면, Responses API 전환 자체가 어려운 건 아닌데, ‘지금 당장 다 바꿔야 하나?’라는 조급함이 오히려 장애물이 됩니다. OpenAI도 Chat Completions와 병행 운영을 허용하고 있으니, 신규 기능부터 Responses API로 구현하고 레거시 코드는 순차적으로 옮기는 방식이 현실적입니다.

▲ 목차로 돌아가기

자주 묻는 것들

▲ 목차로 돌아가기

마치며 — 지금 어떻게 움직이면 될까요

OpenAI Responses API는 분명히 좋아진 API입니다. 에이전트 루프를 직접 구현하지 않아도 되고, 추론 모델을 제대로 쓰려면 사실상 필수적인 선택지입니다. 그런데 “그냥 엔드포인트만 바꾸면 되지 않나요?”라는 생각으로 접근하면 함수 strict 모드, Thread 데이터 이전, ZDR 환경 암호화 처리 같은 곳에서 예상 외의 시간을 씁니다.

이 글에서 확인된 핵심은 두 가지입니다. 첫째, 비용 절감은 1,024토큰 이상 반복 구조가 있을 때만 실제로 일어납니다. 단발성 요청 위주라면 전환 후에도 비용 차이를 느끼기 어렵습니다. 둘째, Thread→Conversation 이전은 OpenAI가 자동으로 해주지 않습니다. 마감일(2026.08.26)이 넉넉해 보여도 히스토리 규모에 따라 작업량이 커질 수 있어 서두르는 게 맞습니다.

Assistants API를 쓰지 않고 Chat Completions만 쓰는 경우라면 당장 강제 마이그레이션은 없습니다. 하지만 o3, o4-mini 같은 추론 모델을 에이전트로 활용할 계획이 있다면, 지금부터 Responses API를 신규 코드에 적용해보는 게 맞는 타이밍입니다.

📚 본 포스팅 참고 자료

1. OpenAI 공식 — Responses API vs Chat Completions 비교 가이드
   https://platform.openai.com/docs/guides/responses-vs-chat-completions
2. OpenAI 공식 — Assistants API 마이그레이션 가이드
   https://platform.openai.com/docs/guides/assistants/migration
3. OpenAI 공식 쿡북 — Reasoning items & Responses API 성능
   https://developers.openai.com/cookbook/examples/responses_api/reasoning_items/
4. Microsoft Azure Foundry — Assistants API 개념 (종료 일정 포함)
   https://learn.microsoft.com/ko-kr/azure/ai-foundry/openai/concepts/assistants
5. OpenAI 공식 — 에이전트 구축 새 도구 발표 (2025.03.11)
   https://openai.com/ko-KR/index/new-tools-for-building-agents/