OpenAI Assistants API 종료: Responses API 마이그레이션 가이드

2026년 8월 26일이 다가온 지금, Assistants API 마이그레이션에서 가장 위험한 판단은 이를 단순한 이름 변경으로 보는 것이다. OpenAI는 2025년 8월 26일 지원 종료 공지를 통해 정확히 1년 전에 일정을 알렸고, 후속 플랫폼은 Responses API로 정해졌다. Assistants API 지원 종료 문서만 보면 객체 이름은 깔끔하게 대응된다. 하지만 그 아래의 오케스트레이션 방식까지 같지는 않으며, 공식 가이드를 충실히 따라간 개발팀에서도 실제 장애가 발생했다. 무엇이 종료되는지, 객체 매핑이 감추는 변화는 무엇인지, 남은 시간에 따라 무엇을 해야 하는지 정리한다.

2026년 8월 26일 이후 중단되는 것과 남는 것

마감일 이후에는 Assistants 관련 모든 엔드포인트 계열이 오류를 반환한다. /v1/assistants, /v1/threads, 스레드 메시지, runs, run steps가 모두 대상이며 OpenAI-Beta: assistants=v2 헤더를 보내는 워크플로도 예외가 아니다. API를 통해 Assistant 설정과 스레드 이력에 접근하는 것도 불가능해진다.

다만 Assistants 연동에 딸려 있던 모든 기능까지 함께 사라지는 것은 아니다.

OpenAI의 지원 종료 추적 페이지도 Responses와 Conversations를 지정된 대체 수단으로 안내한다.

객체 4종 매핑보다 중요한 두 가지 변화

OpenAI의 마이그레이션 가이드는 Assistants의 핵심 개념 4가지를 Responses 시대의 객체로 다음과 같이 연결한다.

이 변화는 공식 예제에서도 확인할 수 있다. gpt-4.1로 완료한 run은 프롬프트 토큰 34개와 완료 토큰 130개를 보고하지만, gpt-5.5로 완료한 response는 입력 토큰 17개와 출력 토큰 150개를 보고한다. 작업의 성격은 비슷해도 필드명은 달라진다.

이것이 첫 번째 주의점이다. 기존 usage 필드에 맞춰 만든 과금 대시보드나 페이로드 파서는 필드명이 바뀌면 조용히 잘못 동작할 수 있다.

두 번째는 아키텍처의 문제다. Prompts는 API가 아니라 대시보드에서만 만들 수 있다. 고객, 워크스페이스, 문서 세트마다 Assistant를 동적으로 생성하던 시스템이라면 이 제약이 바로 걸린다. 공식 가이드도 장기 운영 연동에서 prompt 객체를 채택하기 전, prompt 지원 종료 일정을 확인하라고 권한다. 재사용 가능한 prompt 객체 역시 별도의 지원 종료 위험을 갖기 때문이다. 오래 가는 패턴은 instructions, 도구 스키마, 모델 선택을 자체 소스 제어에 두고 요청마다 전달하는 방식이다. 기존 스레드 이력에 대해서 OpenAI의 입장은 한 문장으로 명확하다. "We will not provide an automated tool for migrating Threads to Conversations."

내장 도구 3종은 어떻게 옮겨야 하나

Assistants의 각 도구는 Responses에서 갈 자리가 정해져 있다. 대신 애플리케이션이 직접 책임져야 할 일이 늘어난다.

멀티 테넌트 앱에서는 file search 항목이 조용하지만 큰 구조 변화다. 예전에는 테넌트별 벡터 스토어를 Assistant 객체에 설정 시점에 연결할 수 있었다. 이제는 들어온 세션의 소유 테넌트를 판별하고, 요청을 보내기 전에 해당 스토어 ID를 찾아 넣어야 한다.

먼저 옮긴 팀들이 실제로 부딪힌 문제

OpenAI는 Responses가 기능 동등성에 도달했다는 이유를 제시한다. 그러나 아래 마이그레이션 사례를 보면 객체 수준의 동등성과 내부 리팩터링의 규모는 별개다. 한 멀티 테넌트 챗봇 SaaS 운영자는 r/aiagents에 2주간의 마이그레이션 경험을 기록했다. 공식 가이드를 충실히 읽고 진행했지만 문제가 남았다.

모든 optional 필드를 ["type", "null"]로 개조해야 했는데, 타입 시스템을 우회하는 느낌입니다. — u/aidenclarke_12

엄격한 도구 스키마에서는 선택 속성도 nullable로 선언해야 하고, 동시에 required 목록에도 넣어야 한다. 스키마가 커질 뿐 아니라, 값이 없다는 것을 곧 속성 부재로 처리하던 핸들러도 다시 검토해야 한다. 같은 개발자는 더 근본적인 변화가 어디에 있는지도 짚었다.

벡터 스토어 연결 방식의 변화가 진짜 아키텍처 전환입니다. — u/aidenclarke_12

두 번째로 놓치기 쉬운 지점은 스트리밍이다. Assistants의 run 스트리밍 코드를 Responses에 그대로 맞춰 쓸 수는 없다. response.created, response.output_text.delta, response.completed, response.function_call_arguments.delta / .done 같은 타입 지정 서버 전송 이벤트를 기준으로 다시 작성해야 한다. 명시적인 완료 이벤트와 달라진 도구 호출 이벤트 구조까지 포함되며, 이벤트명은 마이그레이션 분석 자료에 정리돼 있다. SSE 프록시와 클라이언트 핸들러 모두 재작성 대상이며 재연결 로직도 포함된다.

세 번째 문제는 API 자체보다 주변 생태계의 지원 지연에서 나온다.

response API가 나온 지 오래됐지만, 여전히 지원하지 않는 프레임워크와 SDK가 많습니다. — u/zhlmmc

스택이 아직 Threads/Runs 모델을 전제로 하는 에이전트 프레임워크 위에 있다면, u/zhlmmc가 겪은 것처럼 자체 접착 코드뿐 아니라 그 레이어를 위한 시간도 계획에 넣어야 한다.

상태 관리 선택지: 체이닝, Conversations, 직접 재생

Responses에서 멀티턴 문맥을 유지하는 방법은 세 가지다. 서로 완전히 대체 가능한 선택지는 아니다.

기존 thread 이력을 옮길 때 OpenAI가 권장하는 순서는 다음과 같다.

1. 스레드 메시지를 오름차순으로 조회한다.
2. 각 사용자 텍스트 메시지를 input_text로 변환한다.
3. 각 어시스턴트 텍스트 메시지를 output_text로 변환한다.
4. 이미지 URL 콘텐츠는 image_url과 detail을 유지한 채 input_image로 변환한다.
5. 변환한 items로 Conversation을 생성한다.

역할 매핑을 잘못하면 모델이 자신의 과거 답변을 새로운 사용자 지시로 읽는 구체적인 문제가 생긴다. 저장된 response의 기본 TTL은 30일이며 store: false를 넘기면 저장하지 않는다. 반면 conversation은 response TTL의 적용 대상이 아니고, 2026년 7월 말 기준 별도로 공개된 보존 기간도 없었다고 마이그레이션 추적 자료는 전한다. 삭제 기한을 고지하는 서비스라면 특히 중요한 차이다.

마이그레이션 후 토큰 비용은 어떻게 달라지나

과금 관점에서 확인할 사실은 두 가지다.

첫째, previous_response_id는 할인 기능이 아니라 편의 기능이다. OpenAI의 Responses 마이그레이션 가이드는 response 체인의 이전 입력 토큰도 입력 토큰으로 과금된다고 명시한다. 따라서 정리하지 않으면 장기 대화의 비용은 선형으로 증가한다.

둘째, 캐시된 입력은 캐시 미적용 입력보다 훨씬 저렴하다. 2026년 7월 기준 GPT-5.x 티어 전반에서 입력 요금의 대략 10분의 1 수준이며, OpenAI 내부 테스트에서는 Responses가 Chat Completions보다 캐시 활용률이 40~80% 더 높았다고 종합 분석 자료는 전한다. 다만 이 활용률 범위는 자체 대시보드로 확인하기 전까지 벤더 수치로 취급하는 편이 좋다. 진짜 비교해야 할 지표는 전환 전후의 세션당 자체 토큰 수다.

이번 마이그레이션을 GPT-5.x 워크로드 자체의 가격을 다시 검토할 계기로 삼는다면, GPT-5.6 가격 분석에서 토큰당 비용 계산을 확인할 수 있다. GPT-5.6 API 페이지 같은 OpenAI 호환 엔드포인트도 같은 Responses 방식의 워크로드를 처리하므로 직접 비교할 수 있다.

남은 기간별 Assistants API 마이그레이션 계획

1~6일 남았다면. 먼저 백업부터 한다. limit=100으로 assistants와 vector stores를 나열하고, 파일을 내려받고, SDK 객체는 model_dump()로 직렬화한다. 백업 우선 가이드가 지적하듯 치명적인 제한도 있다. threads를 나열하는 엔드포인트는 없으므로, 애플리케이션이 이미 저장해 둔 thread ID만 내보낼 수 있다. 이후 플래그 뒤에서 전환한다. 새 세션은 즉시 Responses로 보내고, 기존 thread는 사용자가 다시 열 때만 지연 백필한다.

1주 이상 남았다면. 나머지 흐름을 건드리기 전에 위험이 낮은 흐름 하나를 처음부터 끝까지 전환한다. 도구 루프를 새로 만들고 모든 함수 결과가 일치하는 call_id를 갖는지 확인한다. 스트림 처리는 이벤트 타입 분기로 교체한다. 이후 트래픽을 확대하기 전에 Assistants 기준선과 동작, 지연 시간, 토큰 사용량, 오류율을 비교한다.

마감일이 지난 뒤라면. 엔드포인트는 오류를 반환하고 Assistant 설정은 API에서 사라진다. 복구하려면 애플리케이션 데이터베이스와 백업에 남은 자료로 다시 구축해야 한다. 벡터 스토어와 파일은 여전히 file search를 통해 접근할 수 있다.

남는 핵심 트레이드오프는 이렇다. 폴링, 잘라내기, 도구 루프를 서버가 관리하던 수명 주기 대신, 단일 호출 모델과 직접 확인·테스트할 수 있는 오케스트레이션을 얻는다. 두 방식 모두로 출시한 한 개발자는 이 교환을 이렇게 표현했다.

Responses API는 딱 중간 지점입니다. 무거운 작업은 관리해 주면서도 자체 기능을 구현할 만큼 유연합니다. — u/landongarrison

OpenAI Assistants API 종료 FAQ

Chat Completions API도 함께 종료되나?

아니다. Chat Completions는 2026년 8월 26일 종료 대상에 포함되지 않는다. OpenAI의 안내도 강제 마감일에 맞춘 일괄 이전이 아니라, 흐름별로 Responses로 옮길 수 있는 API로 다룬다.

OpenAI가 기존 thread를 자동으로 옮겨 주나?

아니다. 공식 마이그레이션 가이드는 "We will not provide an automated tool for migrating Threads to Conversations."라고 명시한다. 앞서 설명한 item 변환 순서에 따라 애플리케이션 코드로 백필해야 한다.

2026년 8월 26일 이후에도 Assistants API를 계속 쓸 수 있나?

안 된다. Assistants, threads, messages, runs, run steps는 해당 날짜 이후 모두 오류를 반환하며 assistants=v2 워크플로도 마찬가지다. 필요한 데이터는 마감일 전에 내보내야 한다.

저장된 response는 만료되나?

그렇다. 저장된 response의 기본 보존 기간은 30일이며 store: false를 전달하면 저장하지 않는다. 2026년 7월 보도 기준으로 conversations는 이 TTL 밖에 있다.

Assistant 설정을 반드시 Prompts로 옮겨야 하나?

아니다. 동적으로 생성하는 Assistant라면 특히 그렇게 하지 않는 편이 좋다. Prompts는 대시보드에서만 생성할 수 있고, 공식 가이드도 재사용 prompt 객체의 지원 종료 여부를 검토하라고 안내한다. instructions와 도구 스키마를 소스 제어에 보관하고 요청마다 전달하는 방식이 더 오래 유지할 수 있는 패턴이다.