Assistants API 종료,
넘어가면 되는 게 아닙니다
공식 문서가 말하지 않은 비용 함정과 수동 마이그레이션의 현실, 직접 확인했습니다.
스레드 자동 이전 없음
file_search 비용 주의
Assistants API는 왜 사라지는 건가요?
OpenAI는 2025년 8월 26일, Assistants API의 공식 종료를 예고했습니다. 종료 시점은 정확히 1년 뒤인 2026년 8월 26일이고, 이미 Deprecated 상태입니다. (출처: OpenAI 커뮤니티 공식 발표, 2025.08.26)
이유는 단순합니다. Assistants API는 추론 모델(GPT-4 이전 시대)을 전제로 설계된 구조였습니다. 에이전트형 작업이 점점 복잡해지면서 Assistant(설정 묶음) → Thread(대화 저장) → Run(실행) → Run step(결과 확인)이라는 4단계 흐름이 오히려 병목이 됐습니다. OpenAI 공식 마이그레이션 문서에는 “Responses are simpler — send input items and get output items back”이라고 나옵니다. 복잡한 상태 관리를 API가 대신 떠안고, 개발자는 입력과 출력에만 집중하게 만들겠다는 방향입니다.
솔직히 말하면, Assistants API가 beta 딱지를 평생 달고 있었던 것도 이 결정을 이해하는 데 도움이 됩니다. 처음부터 영구 지원 의도가 없었던 것입니다.
Responses API가 진짜 다른 이유
표면적으로는 “Assistants API를 단순하게 만든 버전”처럼 보이지만, 안을 들여다보면 설계 철학 자체가 다릅니다. 가장 눈에 띄는 변화는 네이티브 도구 내장입니다. Chat Completions에서는 web_search, file_search, code_interpreter 같은 기능을 직접 구현하거나 별도 함수로 연결해야 했습니다. Responses API에서는 이것들이 API 레벨에서 기본 제공됩니다.
성능 측면에서도 차이가 있습니다. OpenAI 내부 테스트 기준으로, Responses API는 Chat Completions 대비 캐시 활용률이 40~80% 개선됩니다. (출처: OpenAI 공식 마이그레이션 가이드, 2025) 같은 요청을 반복할 때 재사용 가능한 캐시 비중이 높아진다는 뜻으로, 운영 비용이 실질적으로 줄어드는 케이스가 생깁니다.
💡 공식 발표문과 실제 API 구조 변화를 같이 놓고 보니 이런 차이가 보였습니다
Responses API에서 GPT-5 같은 추론 모델을 쓰면 SWE-bench 기준 3% 성능 향상이 내부 평가에서 나왔습니다. (출처: OpenAI 공식 마이그레이션 가이드) 수치는 작아 보이지만, 캐시 비용 절감과 맞물리면 코딩 에이전트 운영 비용 구조가 달라집니다.
또한 Realtime API와 동일한 Prompt 설정을 공유할 수 있어, 챗봇·스트리밍·저지연 인터랙션을 하나의 프롬프트로 관리하게 됩니다. Assistants API에서는 각각 따로 설정해야 했던 부분입니다.
마이그레이션 전에 알았어야 했던 비용 변화
솔직히 이 부분은 많은 기술 블로그가 그냥 넘어가는 지점입니다. Responses API로 넘어가면 특정 케이스에서 실질 비용이 올라갑니다.
⚠️ file_search 도구 호출에 별도 비용이 붙습니다
Responses API에서 file_search 도구를 쓰면 호출 1,000건당 $2.50이 별도로 청구됩니다. Assistants API에서는 이 비용이 없었습니다. (출처: OpenAI 포럼 실사용자 확인, 2025.03)
구체적으로 계산해보면 이렇습니다. gpt-4o-mini 기준 입력 토큰 비용은 100만 토큰당 $0.15입니다. 대화 1건당 평균 20,000~40,000 토큰을 쓰면 1,000건 기준 약 $3~6입니다. 여기에 file_search를 매 대화에 사용하면 $2.50이 추가됩니다. 기존 대비 40~80% 비용이 증가하는 구조입니다.
| 항목 | Assistants API | Responses API |
|---|---|---|
| file_search 도구 호출 | 무료 | $2.50 / 1,000건 |
| 캐시 활용률 개선 | 기준 | +40~80% |
| 스레드 자동 마이그레이션 | 해당 없음 | 미제공 |
| Prompt 생성 방법 | API로 생성 가능 | 대시보드 전용 |
※ 표 내 수치는 OpenAI 공식 가이드 및 실사용자 보고 기반. 가격 정책은 변경될 수 있습니다.
스레드는 자동으로 옮겨지지 않습니다
여기서 가장 많은 개발자가 당황합니다. OpenAI 공식 마이그레이션 문서에는 이렇게 나옵니다.
“We will not provide an automated tool for migrating Threads to Conversations.”
(출처: OpenAI 공식 Assistants 마이그레이션 가이드)
자동 이전 도구를 제공하지 않습니다. 기존 Thread의 메시지를 직접 순회해서 Conversation items로 변환하는 코드를 직접 짜야 합니다. 즉, 수만 건의 기존 대화 기록이 있는 서비스라면 이것만으로도 상당한 공수가 발생합니다.
💡 공식 가이드가 제시한 백필 코드 구조를 실제로 풀어보면 이렇습니다
기존 Thread에서 메시지를 페이지 단위로 읽어 role별로 input_text / output_text 타입을 분리한 뒤 Conversation items로 재조합합니다. 이미지가 포함된 메시지는 input_image 타입으로 별도 처리가 필요합니다.
신규 사용자 대화는 바로 Conversations API로 시작하고, 기존 Thread는 필요한 것만 선별해 백필하는 전략이 현실적입니다.
한 가지 더 확인해야 할 것이 있습니다. Responses API에서 Response 객체는 기본적으로 30일 TTL이 적용됩니다. 반면 Conversation 객체에 연결된 items은 30일 제한 없이 보존됩니다. (출처: OpenAI 커뮤니티 Q&A, 2025.08.26) 대화 기록을 장기 보존해야 하는 서비스라면 반드시 Conversations API와 함께 사용해야 합니다.
Prompts는 API로 만들 수 없습니다
Assistants API에서는 Assistant 객체를 API로 동적으로 생성·수정할 수 있었습니다. Responses API에서는 그에 상응하는 Prompts 객체가 대시보드에서만 생성 가능합니다. (출처: OpenAI 공식 Assistants 마이그레이션 가이드)
대규모 SaaS처럼 고객사별로 수백 개의 Assistant를 동적으로 생성하는 구조라면 이것이 핵심 문제입니다. 기존처럼 “신규 고객 등록 시 API 호출로 Assistant 자동 생성”하는 흐름이 그대로 작동하지 않습니다.
💡 마이그레이션 가이드 흐름과 실제 운영 시나리오를 같이 놓고 보니 보이는 것이 있었습니다
OpenAI는 “대시보드에서 Prompt를 만들고 버전 관리하라”고 안내합니다. 즉, 가변적인 per-customer 설정은 Prompt에 넣지 말고, 고정된 행동 정의만 Prompt에 담고 가변 정보는 런타임에 system instructions나 input에 주입하는 구조로 분리하는 것이 대안입니다. 동적 생성이 필수인 서비스라면 설계 패턴을 바꿔야 합니다.
다만 버전 관리 측면에서는 오히려 나아집니다. 기존 Assistants는 변경사항을 추적하기 어려웠습니다. Prompts는 대시보드에서 스냅샷·diff·롤백이 가능하고, 코드에서는 프롬프트 ID만 참조하면 됩니다. A/B 테스트도 프롬프트 ID 교체로 처리 가능합니다.
실제 전환 후기에서 나온 체크 포인트
수만 명 사용자를 가진 RAG 기반 챗봇 서비스를 Assistants API에서 Responses API로 전환한 사례가 OpenAI 커뮤니티 포럼에 상세히 공유돼 있습니다. (출처: OpenAI 커뮤니티, kduffie, 2025.03.22) 여기서 나온 내용들입니다.
① API 전환 자체는 2시간이면 됩니다. TypeScript 기준으로, 구조가 완전히 달라졌지만 타입 정의가 명확해서 오히려 마이그레이션이 수월했다는 평가입니다.
② 기존 Assistant instructions가 그대로 작동합니다. Assistants API에서 쓰던 system instructions을 그대로 Responses API에 적용했을 때 동일하게 작동했습니다. 프롬프트를 처음부터 다시 짤 필요는 없습니다.
③ gpt-4o-mini는 지원됩니다. 공식 문서에 최신 모델 위주로 예시가 나와서 gpt-4o-mini 지원 여부가 불분명해 보이지만, 실제로는 지원됩니다.
④ 속도는 체감상 개선되지 않습니다. Assistants API의 느린 응답 속도(스트리밍 시작 기준 5~10초)가 Responses API에서도 유사하게 유지됐습니다. 모델과 file_search 도구가 동일하기 때문입니다.
⑤ Playground 환경이 사라집니다. Assistants Playground는 설정 전체를 시각적으로 확인하며 테스트할 수 있어 개발 초기에 매우 유용했습니다. Responses API에는 직접적으로 대응하는 Playground가 없습니다. 대시보드의 Chat(Prompts) 탭이 일부 역할을 하지만 동일하지는 않습니다.
Q&A
마치며
Responses API로의 전환은 방향성 자체는 맞습니다. 더 단순한 구조, 네이티브 도구 내장, 캐시 효율 개선까지 실질적인 이점이 있습니다. 그런데 “간단하게 넘어가면 된다”는 말은 절반만 맞습니다.
file_search를 쓰는 RAG 서비스라면 비용 구조가 바뀝니다. 스레드를 대화로 옮기는 작업은 직접 코드를 짜야 합니다. 동적으로 Assistant를 생성하던 서비스라면 설계 패턴을 바꿔야 합니다. 이 세 가지를 미리 파악한 상태로 전환 작업에 들어가는 것과 모르고 들어가는 것은 결과가 다릅니다.
마감은 2026년 8월 26일입니다. 지금 당장 전환하지 않아도 되지만, 서비스 규모가 클수록 여유 있게 시작하는 것이 좋습니다. 공식 마이그레이션 가이드에 코드 예시까지 상세하게 나와 있으니, 이번 포스팅에서 짚은 포인트들을 확인하고 시작하면 됩니다.
📚 본 포스팅 참고 자료
- ① OpenAI 공식 Assistants 마이그레이션 가이드 — platform.openai.com/docs/assistants/migration
- ② OpenAI 공식 Responses API vs Chat Completions 마이그레이션 — platform.openai.com/docs/guides/migrate-to-responses
- ③ OpenAI 커뮤니티 공식 발표 (Assistants API 종료 공지) — community.openai.com
- ④ OpenAI Responses API 공식 레퍼런스 — platform.openai.com/docs/api-reference/responses
- ⑤ Microsoft Azure: Assistants API 종료 안내 — learn.microsoft.com
본 포스팅은 2026.03.22 기준으로 작성됐습니다. 본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. 최신 정보는 OpenAI 공식 문서에서 직접 확인하는 것을 권장합니다.
댓글 남기기