OpenAI API
D-149
Assistants API 종료,
교체가 아니라 재설계입니다
OpenAI가 공식 확정한 종료일은 2026년 8월 26일입니다. 마감 기한이 아직 5개월 남았다고 여유롭게 생각했다면, 이 글을 먼저 읽어두는 게 낫습니다. 단순히 엔드포인트 하나 바꾸는 작업이 아니기 때문입니다.
Assistants API가 사라지는 날짜와 배경
OpenAI는 2025년 8월 26일에 Assistants API 베타 종료를 공식 발표했고, 정확히 1년 후인 2026년 8월 26일에 /v1/assistants와 /v1/threads 엔드포인트를 완전히 차단합니다. (출처: OpenAI 공식 deprecations 문서, 2025.08.26)
대체 경로는 Responses API + Conversations API입니다. Responses API는 2025년 3월 11일 출시됐고, Conversations API는 같은 해 8월 20일에 추가됐습니다. 즉 지금 기준으로 이 두 API를 쓰지 않고 있다면 이미 구버전 경로에 머물러 있는 셈입니다.
OpenAI가 Assistants API를 버리기로 한 이유는 크게 두 가지입니다. 첫째, Threads·Runs·Assistants라는 복잡한 서버 관리 구조를 걷어내고 더 유연한 agentic 인터페이스를 만들겠다는 것. 둘째, 추론 모델(GPT-5 계열)과 궁합이 맞지 않는다는 것입니다. OpenAI 공식 마이그레이션 가이드는 “Responses API는 에이전트 구축을 위한 미래 방향”이라고 명시하고 있습니다.
엔드포인트 교체가 아닌 이유
💡 공식 마이그레이션 가이드와 OpenAI 개발자 커뮤니티 토론을 나란히 놓고 보니 한쪽이 말하지 않는 부분이 보였습니다.
막상 작업을 시작하면 “엔드포인트만 바꾸면 되겠지”라는 예상이 금방 깨집니다. Assistants API는 Threads, Runs, Tool attachment lifecycle, Polling·Orchestration을 서버 측에서 전부 관리했습니다. Responses API는 이 구조를 완전히 뒤집습니다. OpenAI 공식 커뮤니티(2026.01.06)에서도 “Assistants API → Responses API is not a 1:1 migration”이라는 표현이 나왔습니다.
구체적으로 변경되는 개념 대응은 다음과 같습니다.
| Assistants API | Responses API | 변경 의미 |
|---|---|---|
| Assistant | Prompt | 대시보드에서만 생성 가능 (API 직접 생성 불가) |
| Thread | Conversation | 메시지 외 tool call, 출력 등 다양한 Item 포함 |
| Run | Response | 비동기 폴링 → 입력/출력 Items 직접 수신 |
| Run steps | Items | 메시지·tool call·출력물 모두 동일 타입 |
눈에 띄는 변화는 Prompt 객체는 API로 직접 생성할 수 없다는 점입니다. (출처: OpenAI Assistants migration guide, platform.openai.com/docs/assistants/migration) 기존에 Assistant 객체를 코드로 동적으로 생성해서 운영하고 있었다면, 이 부분에서 배포 프로세스 자체를 뜯어고쳐야 합니다. 대시보드 전용 작업이 CI/CD 파이프라인에 끼어든다는 뜻입니다.
Thread → Conversation 이전에서 막히는 이유
이전 작업 중 가장 많은 팀이 멈추는 지점입니다. OpenAI 공식 마이그레이션 가이드에는 이 문장이 있습니다.
“We will not provide an automated tool for migrating Threads to Conversations.”
(출처: OpenAI 공식 Assistants migration guide, platform.openai.com/docs/assistants/migration)
자동 마이그레이션 툴은 없습니다. 기존 Thread의 메시지를 직접 읽어서 Conversation Items 형식으로 변환하는 코드를 팀이 직접 작성해야 합니다. 수천 개의 Thread가 쌓인 운영 서비스라면 이 backfill 작업이 단순 코드 수정 수준을 넘어섭니다.
게다가 구조 차이도 있습니다. Thread는 메시지만 저장했지만, Conversation은 메시지 외에 tool call, tool output 등 다양한 Item을 담습니다. 단순 1:1 매핑이 되지 않는 이유가 여기 있습니다. OpenAI 가이드가 직접 제시한 backfill 예시 코드를 보면, role별 content 타입(text/image_url)을 일일이 input_text/output_text/input_image로 분리 처리해야 합니다.
Assistants API에서는 Thread나 Assistant 레벨에서 Vector Store를 묶을 수 있었습니다. Responses API에서는 매 요청마다 vector_store_ids를 명시적으로 전달해야 합니다. 즉 검색 범위를 앱 코드가 직접 책임져야 합니다. RAG 품질이 조용히 떨어지는 가장 흔한 원인입니다.
File search tool call 비용도 달라집니다. Responses API에서는 file search tool call당 $2.50 / 1,000건이 별도 청구됩니다. Assistants API에서 file_search를 사용하고 있었다면 이 항목을 새로 예산에 반영해야 합니다. (출처: OpenAI pricing 페이지, platform.openai.com/docs/pricing, 2026.03.30 기준)
상태 관리 전략, 두 갈래 중 하나를 골라야 합니다
Responses API로 넘어오면 상태 관리 방식이 두 갈래로 나뉩니다. 어느 쪽이든 의도적으로 선택해야 합니다. 혼용하면 나중에 비용 스파이크와 디버깅 지옥이 동시에 옵니다.
previous_response_id를 연결해 턴을 이어갑니다.
- 앱 레벨에서 히스토리를 완전히 제어할 수 있습니다
- 결정론적 재현이 쉽습니다
- 상태 정합성 코드를 직접 작성해야 합니다
Conversation ID를 매 요청에 넘기면 OpenAI가 히스토리를 유지합니다.
- 장기 고객 응대처럼 긴 세션에 적합합니다
- 로컬 히스토리 코드가 줄어듭니다
- OpenAI 서버 상태에 강하게 묶입니다
Zero Data Retention(ZDR) 요건이 있는 조직은 주의해야 합니다. 이 경우 Conversations API를 사용할 수 없고, 옵션 A에서 store: false를 설정한 뒤 encrypted_content를 활용해야 합니다. OpenAI는 ZDR 조직에 대해 store: false를 자동 강제 적용합니다. (출처: OpenAI 공식 migrate-to-responses 가이드, platform.openai.com/docs/guides/migrate-to-responses)
상태 전략 선택은 한번 정하면 쉽게 바꾸기 힘듭니다. 지금 사용 중인 서비스의 세션 패턴(단기 단발 vs 장기 연속)을 먼저 파악하고 결정하는 게 맞는 순서입니다.
비용이 오히려 줄어드는 조건이 있습니다
💡 “이전 비용이 더 들 것 같다”는 예상을 공식 수치가 뒤집습니다.
Responses API로 전환하면 비용이 는다고 예상하기 쉽습니다. 실제로는 반대인 경우가 있습니다. OpenAI 공식 쿡북 문서에는 이 수치가 나와 있습니다.
“In our tests, switching from the Completions API to the Responses API boosted cache utilization from 40% to 80%.”
(출처: OpenAI Developer Cookbook — Better performance from reasoning models using the Responses API, developers.openai.com/cookbook)
캐시 활용률이 두 배가 된다는 뜻입니다. 캐시된 입력 토큰은 기본 입력 토큰 요금의 10%만 청구되니, 시스템 프롬프트나 컨텍스트가 긴 서비스일수록 실질 비용 절감 폭이 큽니다.
성능 측면에서도 같은 프롬프트·같은 셋업 기준으로 SWE-bench 점수가 3% 향상됩니다. (출처: OpenAI 공식 migrate-to-responses 가이드) 수치가 작아 보이지만, 코딩 에이전트처럼 반복 tool call이 많은 구조에서는 누적 효과가 유의미하게 나타납니다.
| 항목 | Chat Completions | Responses API |
|---|---|---|
| 캐시 활용률 (내부 테스트) | 약 40% | 약 80% |
| SWE-bench 성능 (동일 셋업) | 기준 | +3% |
| 내장 Tool 지원 | ❌ | ✅ (웹검색, 코드인터프리터, MCP 등) |
| GPT-5.4 이후 tool calling | reasoning:none 강제 | ✅ 지원 |
3월 31일부터 Container 요금이 바뀝니다
💡 Responses API로 넘어오면서 Code Interpreter나 Hosted Shell을 쓰는 팀이라면 이 날짜를 놓치면 안 됩니다.
OpenAI 요금 페이지(2026.03.30 기준)에 이렇게 나옵니다.
| Container 크기 | 지금 (~3월 30일) | 3월 31일부터 |
|---|---|---|
| 1 GB | $0.03 | $0.03 / 20분 세션 |
| 4 GB | $0.12 | $0.12 / 20분 세션 |
| 16 GB | $0.48 | $0.48 / 20분 세션 |
| 64 GB | $1.92 | $1.92 / 20분 세션 |
지금은 “보유 기준” 과금이었는데 내일부터 “세션 단위” 과금으로 바뀝니다. Code Interpreter를 반복 호출하는 에이전트 루프를 짠 경우, 20분마다 요금이 재산정됩니다. 루프가 길면 Container 비용이 예측보다 수십 배 불어날 수 있습니다.
당장 내일부터 적용이니, Code Interpreter나 Hosted Shell을 Responses API와 함께 쓰고 있다면 오늘 안에 세션 길이와 루프 횟수를 점검해야 합니다. (출처: OpenAI pricing 페이지, platform.openai.com/docs/pricing, 2026.03.30 기준)
지금 당장 해야 할 것 5가지
생산 환경 기준으로 필요한 작업을 시간 역순으로 정리했습니다. 마감 직전에 몰아서 하면 스트리밍 파서 깨짐, RAG 품질 저하, 비용 폭증이 동시에 발생합니다.
코드베이스에서 openai.beta.threads, openai.beta.assistants를 전수 검색합니다. 수량과 사용 패턴을 먼저 파악해야 작업 범위가 나옵니다.
OpenAI 대시보드에서 기존 Assistant를 찾아 “Create prompt”를 클릭해 Prompt 객체로 전환합니다. Prompt는 대시보드에서만 만들 수 있으니 코드가 아닌 UI 작업으로 처리해야 합니다.
previous_response_id 체이닝(클라이언트 관리)과 Conversations API(서버 관리) 중 하나를 선택하고, 워크로드별로 문서화합니다. 두 방식을 혼용하면 디버깅이 급격히 복잡해집니다.
기존 Thread를 Conversation으로 옮기는 backfill 코드를 작성하고, file_search에 vector_store_ids를 명시적으로 연결한 뒤 RAG 응답 품질이 이전과 같은지 비교 테스트합니다.
Responses API의 SSE 이벤트 구조는 Chat Completions와 다릅니다. 프런트엔드 파서를 새로 작성하고, 5% → 25% → 50% 순서로 트래픽을 점진 전환하면서 레이턴시·비용·오류율을 모니터링합니다.
Q&A
마치며
이번 마이그레이션의 핵심을 솔직히 말하면, OpenAI가 복잡한 서버 관리를 개발자에게 넘기는 대신 유연성과 비용 효율을 줬다는 구조입니다. 지금까지 Assistants API가 대신 처리해주던 상태 관리·오케스트레이션·tool lifecycle을 이제 앱 코드가 직접 담당해야 합니다.
기대했던 것과 달랐던 점은, “간단한 마이그레이션”이라는 초반 인식이 실제 작업 범위를 상당히 과소평가하게 만든다는 것입니다. Thread 자동 이전 툴이 없다는 사실, Prompt 객체가 API가 아닌 대시보드 전용이라는 사실, Container 요금 방식이 내일부터 바뀐다는 사실까지 — 공식 문서를 직접 뜯어보지 않으면 놓치기 쉬운 부분들입니다.
D-149. 여유 있어 보이지만 실제로 parity test, 카나리 배포, 롤백 훈련까지 포함한 일정을 역산하면 지금 바로 시작해야 하는 타이밍입니다.
- OpenAI 공식 Assistants Migration Guide — platform.openai.com/docs/assistants/migration
- OpenAI 공식 Migrate to Responses Guide — platform.openai.com/docs/guides/migrate-to-responses
- OpenAI API Pricing 페이지 (2026.03.30 기준) — platform.openai.com/docs/pricing
- OpenAI Developer Cookbook — Reasoning Items / Cache Utilization — developers.openai.com/cookbook
- OpenAI Community — “Assistants API → Responses API: this is not a 1:1 migration” (2026.01.06)
본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. 모든 수치와 내용은 2026년 3월 30일 기준 OpenAI 공식 문서를 참고하였으며, 최신 정보는 반드시 공식 문서에서 직접 확인하시기 바랍니다.
댓글 남기기