OpenAI 공식 문서 기준
OpenAI Assistants API 종료, 마이그레이션이 쉽다는 말이 절반만 맞습니다
결론부터 말씀드리면, 2026년 8월 26일에 Assistants API가 완전히 꺼집니다. OpenAI는 Responses API로의 전환이 간단하다고 했지만, 공식 문서를 직접 뜯어보니 “단순 교체”가 아닌 아키텍처 수준의 재설계가 필요한 부분들이 있었습니다. 특히 동적으로 Assistant를 생성하는 구조를 쓰고 있다면 지금 바로 확인이 필요합니다.
Assistants API, 처음부터 ‘베타’였다는 사실
솔직히 말하면, Assistants API는 출시부터 종료까지 단 한 번도 정식 안정 버전(GA) 딱지를 달지 못했습니다. OpenAI 공식 Deprecations 문서에는 “2025년 8월 26일, Assistants API 베타의 종료를 개발자들에게 통지했다”고 직접 명시돼 있습니다. (출처: OpenAI Deprecations 공식 문서)
2023년 11월 처음 공개됐을 때 OpenAI는 “에이전트 경험을 쉽게 구축하는 새로운 방법”이라고 소개했지만, 당시는 추론 모델(Reasoning model)이 존재하기 전이었습니다. 공식 발표문에는 “Assistants는 추론 모델이 등장하기 이전, 에이전트를 어떻게 만들 수 있는지에 대한 초기 시도였다”고 직접 밝히고 있습니다. 처음부터 실험적 성격이었다는 이야기입니다.
💡 OpenAI 공식 발표문(2025.08.26)과 Deprecations 페이지를 같이 놓고 보면 이런 구도가 보였습니다: Assistants API를 공개하면서 “GA 출시”라는 표현을 한 번도 쓰지 않았고, Responses API가 기능 동등에 도달한 시점을 종료 기준으로 삼았습니다. 즉, ‘베타가 끝났으니 베타를 닫는다’는 구조입니다.
2024년 4월에는 v1 → v2 베타 전환이 있었고, v1은 2024년 12월 18일에 이미 종료됐습니다. 이번이 두 번째 종료입니다. 이미 한 번 마이그레이션을 겪은 분들이라면 이번이 더 큰 변화입니다.
4가지 개념이 전부 이름부터 바뀝니다
단순히 엔드포인트 URL을 교체하는 수준이 아닙니다. Assistants API의 핵심 객체 4개가 전부 다른 이름과 다른 역할로 교체됩니다. 공식 마이그레이션 가이드에 나온 비교표입니다. (출처: OpenAI Assistants Migration 공식 문서)
| Assistants API (종료) | Responses API (신규) | 핵심 변화 |
|---|---|---|
| Assistants | Prompts | 버전 관리 + 대시보드에서만 생성 가능 |
| Threads | Conversations | 메시지만 저장 → 도구 호출 결과까지 저장 |
| Runs | Responses | 폴링 루프 제거 → 입력/출력 단순화 |
| Run steps | Items | 메시지·도구 호출·출력을 통합 객체로 처리 |
가장 체감이 큰 변화는 Runs의 폐지입니다. 기존에는 Thread에 메시지를 추가하고 → Run을 생성하고 → 상태를 폴링하는 3단계 루프를 작성해야 했습니다. Responses API에서는 입력을 넘기면 출력이 바로 돌아옵니다. 폴링 코드를 쓴 분들이라면 해당 로직 전체를 걷어낼 수 있습니다.
Responses API가 실제로 더 빠른 이유 (수치로 확인)
막연히 “더 좋다”는 말보다 수치가 납득이 빠릅니다. OpenAI 공식 마이그레이션 가이드에 직접 공개된 내부 테스트 결과입니다. (출처: OpenAI migrate-to-responses 공식 가이드)
📊 공식 수치 (OpenAI 내부 테스트 기준)
- 캐시 이용률: Chat Completions 대비 40~80% 개선 — 같은 요청을 반복하는 앱일수록 비용 절감이 큽니다.
- 모델 성능: GPT-5 사용 시 SWE-bench 기준 3% 향상 — 같은 프롬프트·설정 기준입니다.
- 토큰 활동량: 이미 Responses API가 Chat Completions를 역전했습니다.
캐시 이용률 40~80% 개선은 단순한 속도 이야기가 아닙니다. OpenAI API 요금에서 입력 토큰 캐시 히트는 일반 입력 가격의 50%가 적용됩니다. 하루 수백만 토큰을 처리하는 서비스라면 단순 마이그레이션만으로 비용이 눈에 띄게 바뀝니다.
또한 Responses API에는 웹 검색·파일 검색·코드 인터프리터·원격 MCP·컴퓨터 사용 같은 네이티브 도구가 내장돼 있습니다. Chat Completions에서는 이 모든 도구를 직접 구현해야 했지만, Responses API에서는 요청 한 번으로 멀티 스텝 워크플로우가 처리됩니다.
“기능 동등”이라고 했는데, 이 부분만은 다릅니다
OpenAI는 “Responses API가 Assistants API와 기능 동등에 도달했다”는 표현을 공식 발표에서 사용했습니다. 막상 개발자 커뮤니티에서는 다른 반응이 나왔습니다. 핵심은 Prompts(구 Assistants)를 API로 동적 생성하는 기능이 없다는 점입니다.
⚠️ 이 구조를 쓰고 있다면 반드시 확인하세요
기존에 openai.beta.assistants.create()로 런타임에 어시스턴트를 동적으로 생성하는 코드가 있다면, 현재 Responses API에는 이에 대응하는 API 엔드포인트가 없습니다. Prompts는 대시보드(Playground)에서만 생성할 수 있고, 코드로 만들 수 없습니다. (출처: OpenAI 커뮤니티 공식 발표 스레드, 2025.08.26)
OpenAI 마이그레이션 가이드에도 이 내용이 직접 나와 있습니다: “Assistants의 대체인 Prompts는 대시보드에서만 생성할 수 있으며, 여기서 제품을 개발하면서 버전 관리를 할 수 있습니다.” 이유는 아직 공개되지 않았습니다.
이 부분은 고객별로 커스텀 어시스턴트를 프로그래밍 방식으로 생성하던 서비스 — 예를 들어 “고객사마다 다른 시스템 프롬프트와 도구 설정을 가진 어시스턴트를 자동으로 만드는 SaaS” — 에서 가장 크게 체감됩니다. 이런 구조라면 Prompts 방식이 아닌 Responses API 직접 호출(instructions 파라미터 활용) 방향으로 재설계가 필요합니다.
Thread 대화 기록, 직접 옮겨야 합니다
OpenAI는 Threads → Conversations 자동 마이그레이션 도구를 제공하지 않습니다. 공식 문서에 이 부분이 명시돼 있습니다: “Thread를 Conversation으로 이전하는 자동화 도구는 제공하지 않습니다. 신규 사용자 대화는 Conversations로 받고, 기존 것은 필요에 따라 수동으로 백필하는 방식을 권장합니다.” (출처: OpenAI Assistants Migration 공식 문서)
💡 공식 마이그레이션 가이드와 실제 작동 방식을 교차해서 보니 이런 그림이 나왔습니다.
기존 Thread에서 메시지를 페이지 단위로 가져온 다음, 각 메시지의 role과 content를 Conversations의 items 형태로 변환해서 openai.conversations.create()로 새로 만드는 방식입니다. 이미지가 포함된 메시지는 별도로 처리해야 하며, 파일 기반 검색(File Search)에 연결된 Tool Resources는 새 Vector Store ID 매핑이 필요합니다.
Conversations의 가장 큰 차이는 저장 범위입니다. 기존 Threads는 메시지만 저장했지만, Conversations는 메시지뿐만 아니라 도구 호출 결과와 도구 출력까지 Items로 함께 저장합니다. 단순 텍스트 대화보다 코드 인터프리터나 파일 검색을 많이 쓴 Thread라면 백필 코드의 복잡도가 올라갑니다.
마이그레이션 순서, 공식 문서 기준 7단계
공식 마이그레이션 가이드(migrate-to-responses)에 나온 7가지 단계를 요약했습니다. 순서대로 처리하면 누락 없이 전환됩니다.
- 엔드포인트 교체:
POST /v1/chat/completions→POST /v1/responses. 함수나 멀티모달을 안 쓴다면 여기서 끝. - Item 정의 업데이트: Messages(역할+콘텐츠 배열) → Items(타입별로 분리된 객체).
- 멀티턴 대화 관리: 직접 히스토리를 관리하거나,
previous_response_id또는 Conversations API를 사용. - 스테이트풀 여부 결정: ZDR(Zero Data Retention) 환경은
store:false+reasoning.encrypted_content조합 사용. - Function 정의 교체: 외부 태그 방식 → 내부 태그 방식. Responses API에서 함수는 기본값이 strict(엄격 모드)입니다. Chat Completions는 기본값이 비엄격 — 이 차이를 놓치면 기존 함수가 오류를 냅니다.
- Structured Outputs 수정:
response_format→text.format으로 이동. - 네이티브 도구 전환: 직접 구현한 웹 검색·파일 검색 함수를 OpenAI 내장 도구로 교체 가능.
5번(Function 엄격 모드)이 실제로 가장 많은 오류를 만드는 지점입니다. 기존 Chat Completions에서 함수 파라미터 스키마에 additionalProperties: false를 명시하지 않았던 코드는, Responses API에서 그대로 사용하면 엄격 모드 위반으로 에러가 발생합니다. 마이그레이션 전 함수 스키마 전수 점검이 필요합니다.
자주 묻는 것들
마치며
OpenAI Assistants API 종료는 단순한 엔드포인트 교체 이벤트가 아닙니다. 2023년 11월에 “에이전트 구축의 새로운 방식”이라고 소개됐던 API가, 추론 모델의 등장으로 인해 2년 반 만에 구조 자체를 바꿔야 하는 상황이 됐습니다. 이번 전환의 핵심은 “OpenAI가 대화 상태를 관리해주는 구조”에서 “개발자가 어떤 상태 전략을 쓸지 직접 선택하는 구조”로의 이동입니다.
기능이 많아졌다는 건 맞습니다. 캐시 효율이 좋아진 것도 맞고, 네이티브 도구가 편해진 것도 맞습니다. 하지만 Prompts의 API 생성 불가, Thread 자동 이전 도구 미지원, 함수 엄격 모드 기본 적용 같은 부분들은 기존 코드를 그대로 들고 가는 분들에게 예상치 못한 지점에서 걸립니다.
종료까지 약 5개월이 남았습니다. 지금 당장 전환이 어렵다면, 적어도 기존 Thread 데이터 조회·보관 계획부터 세우는 것이 안전합니다. 8월 26일 이후에는 Assistants API로 Thread를 읽는 방법도 사라집니다.
📚 본 포스팅 참고 자료
- ① OpenAI Deprecations 공식 문서 — https://developers.openai.com/api/docs/deprecations/
- ② OpenAI Assistants → Responses 마이그레이션 가이드 — https://developers.openai.com/api/docs/assistants/migration/
- ③ OpenAI Chat Completions → Responses 마이그레이션 가이드 — https://platform.openai.com/docs/guides/migrate-to-responses
- ④ OpenAI 커뮤니티 공식 발표 스레드 (2025.08.26) — https://community.openai.com/t/assistants-api-beta-deprecation-august-26-2026-sunset/1354666
- ⑤ Microsoft Learn – Azure OpenAI Assistants 사용 중지 공지 — https://learn.microsoft.com/ko-kr/azure/foundry-classic/openai/how-to/assistant
본 포스팅은 2026년 3월 23일 기준 OpenAI 공식 문서를 바탕으로 작성됐습니다. 본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. 최신 정보는 OpenAI 공식 문서에서 직접 확인하시기 바랍니다.
댓글 남기기