Assistants API v2 기준
D-156 종료 예정
OpenAI Assistants API 종료,
8월 26일 전에 이 3가지 막힙니다
결론부터 말씀드리면, Responses API로 갈아타는 건 맞습니다. 그런데 ‘그냥 갈아타면 되겠지’라고 생각하면 세 군데서 막힙니다. 공식 마이그레이션 가이드에 직접 나와 있는 내용인데, 한국어로 정리된 곳이 거의 없어서 써봤습니다.
Assistants API, 왜 지금 없애는 걸까요?
OpenAI 공식 커뮤니티에 2025년 8월 26일 올라온 공지에 이렇게 나옵니다. “Assistants were our early take on how agents could be built (before reasoning models).” 쉽게 말해 추론 모델이 나오기 전에 만든 구조라는 겁니다. 에이전트 설계 방식이 달라졌으니 API도 바꾼다는 논리입니다. (출처: OpenAI 공식 커뮤니티, 2025.08.26)
공지에 따르면 Responses API는 이미 Chat Completions보다 토큰 사용량 기준 활동량이 더 높아졌습니다. OpenAI 입장에서는 새 구조로의 전환을 마무리할 시점이라고 판단한 셈입니다. 배타가 붙어 있던 Assistants API는 처음부터 완성된 구조가 아니었고, 실제로 2024년 12월 v1 베타 접속이 먼저 차단되면서 사실상 예고된 수순이었습니다.
종료 일정은 세 단계로 정리됩니다. 2024년 12월 18일에 v1 베타 접속 종료, 2025년 8월 26일에 deprecated 공식 선언, 2026년 8월 26일에 API 엔드포인트 완전 차단입니다. 지금 시점 기준으로 약 5개월 남았습니다.
Responses API로 바뀌는 핵심 개념 4가지
구조 이름이 전부 바뀝니다. 공식 마이그레이션 가이드에 나온 대응 관계를 그대로 가져오면 이렇습니다. (출처: OpenAI 공식 마이그레이션 가이드, developers.openai.com/api/docs/assistants/migration)
| Assistants API (이전) | Responses API (지금) | 핵심 차이 |
|---|---|---|
| Assistants | Prompts | 대시보드 전용 생성, 버전 관리 가능 |
| Threads | Conversations | 메시지 외 tool call·output 등 저장 가능 |
| Runs | Responses | 비동기 폴링 루프 제거, 단순화 |
| Run Steps | Items | 메시지·tool call·출력 등 통합 객체 |
구조가 단순해진 건 맞습니다. Runs의 비동기 상태 폴링(queued → in_progress → completed)이 사라지고, Responses는 요청을 보내면 바로 결과 items를 돌려줍니다. 개발 편의성으로는 확실히 개선됩니다.
그런데 구조 이름이 바뀌는 것보다 더 중요한 변화가 두 군데 있습니다. 다음 섹션에서 짚습니다.
당연히 될 것 같지만 막히는 첫 번째 지점 — Prompts 생성
💡 공식 마이그레이션 가이드와 커뮤니티 글을 함께 읽어보니 이게 가장 먼저 문제로 터집니다.
Assistants는 API로 직접 생성할 수 있었습니다. openai.beta.assistants.create()를 코드에 넣으면 끝이었죠. 그런데 그 자리를 대체하는 Prompts는 API로 생성할 수 없습니다. 공식 마이그레이션 가이드에 딱 이렇게 나옵니다.
“Prompts replace them and are created in the dashboard (and can be versioned).”
— OpenAI 공식 마이그레이션 가이드 (developers.openai.com/api/docs/assistants/migration)
코드로 동적으로 어시스턴트를 만들고 있었다면 구조를 바꿔야 합니다. 여러 고객사별로 서로 다른 어시스턴트 설정을 프로그래밍 방식으로 생성하는 멀티테넌트 서비스가 특히 영향을 받습니다.
OpenAI 커뮤니티에서도 이 부분에 대한 혼란이 있었습니다. “feature parity라고 했는데 이건 같은 기능이 아니지 않냐”는 반응이 나왔고, OpenAI는 공식 답변을 별도로 내놓지 않은 상태입니다. Prompt ID를 소스 코드에 저장해두고 참조하는 방식으로 우회하는 게 현재 공식 권고사항입니다.
Thread 데이터는 자동으로 넘어오지 않습니다
💡 OpenAI가 공식적으로 “자동 이전 도구는 제공하지 않는다”고 직접 밝혔습니다. 알고 넘어가면 일정 산정이 달라집니다.
Threads에 쌓아온 대화 데이터를 Conversations로 자동으로 옮겨주는 도구가 없습니다. 공식 마이그레이션 가이드 원문에는 이렇게 나옵니다. “We will not provide an automated tool for migrating Threads to Conversations.” 직접 백필하거나, 신규 세션부터 Conversations로 받고 기존 건은 필요 시 수동으로 채워야 합니다.
대화 이력이 중요한 서비스라면 실질적인 작업량이 예상보다 클 수 있습니다. 특히 Threads의 메시지만 Conversations로 옮기면 tool call이나 tool output 같은 항목은 별도로 매핑 작업이 필요합니다. Threads는 메시지만 저장했지만 Conversations는 Items라는 더 넓은 개념으로 저장하기 때문입니다.
또 하나, previous_response_id와 conversation을 동시에 쓸 수 없습니다. 공식 문서에서 이 부분을 명시하고 있으므로, 대화 흐름 연결 방식을 한 가지로 통일해야 합니다. 둘을 같이 넣으면 에러가 납니다.
비용이 줄었다는 말이 절반만 맞는 이유
💡 캐시 개선 수치와 신규 도구 비용을 같이 놓고 보면 그림이 달라집니다.
OpenAI 공식 마이그레이션 가이드에는 Responses API가 내부 테스트에서 캐시 활용도가 Chat Completions 대비 40~80% 개선됐다고 나와 있습니다. 토큰 비용만 보면 유리해질 수 있습니다. (출처: OpenAI 공식 마이그레이션 가이드, developers.openai.com/api/docs/assistants/migration)
그런데 동시에 도구 사용 비용이 별도로 붙습니다. Ragwalla 마이그레이션 가이드가 OpenAI 공식 가격 문서를 인용한 수치를 보면 세 가지가 중요합니다. File search 저장 비용은 첫 1GB를 초과하면 하루 $0.10/GB가 붙습니다. File search 도구 호출 비용은 1,000건당 $2.50입니다. Web search 도구 호출 비용은 더 높아서 버전·모델 조합에 따라 1,000건당 약 $10 수준입니다. (출처: OpenAI 공식 가격 문서 기반, ragwalla.com, 2026.01.28)
Assistants API에서 Code Interpreter나 File Search를 쓰던 서비스라면, 마이그레이션 전후 비용 비교를 반드시 직접 해봐야 합니다. 캐시 개선 효과가 도구 호출 비용을 상쇄하는지 케이스마다 다르기 때문입니다.
| 항목 | Assistants API | Responses API |
|---|---|---|
| 캐시 활용도 | 기본 수준 | 내부 테스트 40~80% 개선 |
| File search 도구 호출 | 별도 명시 없음 | $2.50 / 1k calls (신규) |
| File search 저장 | 1GB 초과 시 $0.10/GB/일 | 동일 구조 유지 |
| Web search 도구 호출 | 없음 | 약 $10 / 1k calls (버전별 상이) |
지금 당장 해야 할 것과 미뤄도 되는 것
Ragwalla의 마이그레이션 타임라인(2026.01.28 업데이트)을 기반으로 현재 시점 기준으로 재정리하면 이렇습니다.
사용 중인 Assistants·Threads·Vector store 목록 인벤토리 작성, Responses API로 소규모 프로토타입 구현, Conversations API 동작 방식 사전 검증
중요 Assistants를 대시보드에서 Prompts로 전환, function calling 도구 루프 재구현, 파일 검색 도구 비용 모니터링 셋업
프로덕션 트래픽 점진적 전환, Assistants vs Responses 섀도 비교, 기존 Thread 이력 중 보존 필요한 데이터 내보내기
완전 차단. 이 이후로는 Assistants API 엔드포인트 호출 자체가 작동하지 않습니다.
지금 당장 하지 않아도 되는 것: Thread 이력 전체를 한 번에 이전하려는 시도입니다. 공식 가이드가 신규 세션부터 Conversations로 받고, 필요한 기존 건은 점진적으로 백필하라고 권고합니다. 한꺼번에 하려다 오히려 일정이 늦어지는 경우가 있습니다.
Wire-compatible 대안(기존 Assistants API 코드를 그대로 두고 base URL만 바꾸는 서드파티 솔루션)도 단기 브리지로는 고려할 수 있지만, 그쪽에서는 deep research·MCP·computer use 같은 신규 도구가 지원되지 않을 수 있습니다. 장기 구조는 Responses API 기준으로 잡는 게 맞습니다.
Q&A 5가지
마치며
Responses API로의 이전 자체는 분명히 나은 방향입니다. 비동기 폴링 루프가 사라지고 구조가 단순해진 건 실제로 개발이 편해지는 부분입니다. GPT-5와의 연동에서 reasoning 토큰이 턴 사이에 유지되는 기능도 Assistants API에는 없던 것입니다.
다만 “그냥 API 이름만 바뀌겠지”라고 생각하면 세 군데서 막힙니다. Prompts는 대시보드에서만 만들어야 하고, Thread 데이터는 자동 이전 도구가 없고, 도구 호출 비용이 새로 붙습니다. 이 세 가지를 일정 산정 전에 파악해두면 실제 작업량 예측이 달라집니다.
남은 시간이 5개월 조금 넘습니다. 지금 인벤토리부터 잡아두면 여유 있게 이전할 수 있습니다.
본 포스팅 참고 자료
- OpenAI 공식 Deprecations 문서 — developers.openai.com/api/docs/deprecations/
- OpenAI 공식 Assistants → Responses 마이그레이션 가이드 — developers.openai.com/api/docs/assistants/migration
- OpenAI 커뮤니티 공식 공지 (2025.08.26) — community.openai.com
- Ragwalla 마이그레이션 가이드 (2026.01.28) — ragwalla.com
- Syntackle 마이그레이션 튜토리얼 (2025.10.08) — syntackle.com
본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. OpenAI API 관련 정보는 업데이트가 빈번하므로 중요 결정 전에는 공식 문서를 직접 확인하는 것을 권장합니다.
댓글 남기기