OpenAI Responses API
⚠️ 2026.08.26 종료 확정
OpenAI Responses API 4가지, 공식 문서에서 직접 확인했습니다
Assistants API를 쓰고 있다면, 지금 당장 일정부터 확인해야 합니다. 2026년 8월 26일이 마감입니다. 그런데 “Responses API로 바꾸면 돼”라는 말이 생각보다 단순하지 않습니다. 공식 문서를 직접 들여다봤더니 몇 가지 예상 밖의 내용이 있었습니다.
Assistants API 종료, 정확한 타임라인을 알아야 늦지 않습니다
OpenAI가 Assistants API를 공식 deprecated로 지정한 건 2025년 8월 26일입니다. 그리고 종료(sunset) 일은 정확히 1년 뒤인 2026년 8월 26일로 못 박혔습니다. (출처: OpenAI 공식 커뮤니티 공지, 2025.08.26)
오늘(2026년 3월 26일) 기준으로 남은 기간은 약 153일입니다. 현재는 여전히 작동하지만, 공식 문서에는 이미 “deprecated” 딱지가 붙어 있고 새 기능 업데이트는 Responses API에만 이루어지고 있습니다.
OpenAI는 공지에서 “Responses API가 기능 동등성(feature parity)에 도달했기 때문에 Assistants를 종료한다”고 밝혔습니다. 그런데 직접 확인해보면, 기능이 100% 같은 건 아닙니다. Prompt 생성 경로처럼 실제로 달라진 부분이 있고, 이걸 마이그레이션 전에 파악해야 코드 리팩터링 범위를 정확히 잡을 수 있습니다.
| 날짜 | 이벤트 |
|---|---|
| 2024.12.18 | Assistants API v1 베타 접근 종료 (v2만 유지) |
| 2025.03 | Responses API 공개, 신규 프로젝트에 권장 시작 |
| 2025.08.26 | Assistants API 공식 deprecated 발표 |
| 2026.08.26 | Assistants API 완전 종료 ← 이 날 이후 호출 불가 |
Responses API가 달라지는 핵심 4가지 — 이름만 바뀐 게 아닙니다
Assistants API에서 Responses API로의 전환은 단순한 엔드포인트 변경이 아닙니다. 핵심 개념 자체가 바뀝니다. 공식 마이그레이션 가이드에 정리된 변경 내용을 있는 그대로 풀면 이렇습니다. (출처: OpenAI 공식 마이그레이션 가이드)
| 이전 (Assistants API) | 이후 (Responses API) | 핵심 차이 |
|---|---|---|
| Assistants | Prompts | 버전 관리 가능, 단 API 생성 불가 |
| Threads | Conversations | 메시지뿐 아니라 툴 호출/결과까지 저장 |
| Runs (비동기) | Responses | 폴링 루프 불필요, 동기·스트리밍으로 단순화 |
| Run Steps | Items | 메시지·툴 호출·출력이 하나의 타입으로 통일 |
가장 눈에 띄는 변화는 비동기 Run의 제거입니다. 기존 Assistants API에서는 Thread에 메시지를 추가하고 Run을 생성한 뒤 상태가 “completed”가 될 때까지 1초마다 폴링(polling)해야 했습니다. Responses API에서는 그 루프가 사라집니다. 이 부분만 해도 코드 복잡도가 상당히 줄어듭니다.
비용이 줄어든다는 말, 실제 수치로 살펴보면 이렇습니다
OpenAI 공식 문서에는 Responses API의 장점으로 “캐시 활용률 향상으로 Chat Completions 대비 비용 40~80% 절감”이 명시돼 있습니다. (출처: OpenAI Responses vs Chat Completions 공식 가이드) 내부 테스트 기준이라는 단서가 붙어 있지만, 이 수치가 어디서 나오는지 구조를 보면 납득이 됩니다.
Responses API는 기본값으로 store: true가 설정됩니다. 응답 객체가 서버에 저장되면 같은 컨텍스트를 다음 요청에서 캐시로 재사용할 수 있습니다. Chat Completions에서는 매 요청마다 전체 대화 히스토리를 직접 붙여 보내야 했기 때문에, 대화가 길어질수록 입력 토큰 비용이 선형적으로 증가했습니다.
즉 캐시가 잘 맞으면 비용이 줄고, 매번 다른 입력이 들어오는 구조(예: 일회성 단순 질의)에서는 절감 효과가 크지 않을 수 있습니다. “40~80%”는 컨텍스트를 반복 재사용하는 멀티턴 대화 서비스에서 체감이 큽니다.
그리고 Responses API에서는 추론 모델(GPT-5 등)을 쓸 때 SWE-bench 기준 Chat Completions 대비 3% 성능 향상도 확인됩니다. (출처: 동일 공식 가이드) 수치가 작아 보여도, 코딩 에이전트처럼 다단계 툴 호출이 반복되는 워크플로우에서는 누적 효과가 나타납니다. 3%가 100번 반복되면 결과물의 품질 차이가 눈에 보이기 시작합니다.
반면 도구 사용 비용은 추가로 발생합니다. File search는 저장소 1GB 초과분부터 하루 $0.10/GB, 도구 호출당 $2.50/1,000회가 부과됩니다. Web search는 도구 버전·모델 클래스에 따라 다르지만 대략 $10/1,000회 수준입니다. (출처: Ragwalla 마이그레이션 가이드, 2026.01.28) 기능이 강해진 만큼, 사용하는 도구 수만큼 비용 항목이 늘어납니다.
Prompt는 API로 생성할 수 없습니다 — 코드로 자동화하던 방식이 막힙니다
이게 마이그레이션에서 가장 먼저 부딪히는 함정입니다. 기존 Assistants API에서는 Assistant 객체를 코드로 동적 생성할 수 있었습니다. 모델, 지시문(instructions), 도구를 프로그래밍으로 조합해서 만드는 방식이었습니다.
그런데 대체품인 Prompt는 반드시 OpenAI 대시보드에서만 만들 수 있습니다. API로 Prompt를 생성하는 엔드포인트가 없습니다. (출처: OpenAI 공식 마이그레이션 가이드 — “Assistants were persistent objects created/managed via API. Prompts replace them and are created in the dashboard”) 읽은 것을 그대로 옮기면 이렇습니다. Prompt ID는 코드에서 참조할 수 있지만, 생성 자체는 대시보드를 직접 열어야 합니다.
멀티테넌트 서비스처럼 코드에서 Assistant를 동적으로 대량 생성하는 구조를 쓰고 있다면, 마이그레이션 방식이 달라집니다. Prompt를 대시보드에서 미리 만들어두고 코드에서 ID를 참조하거나, Prompt 없이 Responses API를 직접 호출하면서 `instructions` 파라미터로 지시문을 넘기는 방식을 써야 합니다. 전자는 운영 유연성이 줄고, 후자는 버저닝 편의를 포기하는 트레이드오프가 생깁니다.
또 하나. previous_response_id와 conversation은 동시에 사용할 수 없습니다. 이 두 가지 상태 관리 방법을 혼용하면 API 오류가 납니다. 공식 문서에 명시된 내용입니다. “이전 응답을 연결하는 방법이 두 가지니까 둘 다 쓰면 더 좋겠지”라는 직관이 실제로는 에러로 돌아옵니다.
Thread 데이터를 자동으로 옮겨주는 도구가 없어서, 직접 처리해야 합니다
Assistants API에서 Conversations API로 넘어갈 때, OpenAI는 Thread를 Conversation으로 자동 이전해주는 도구를 제공하지 않습니다. 공식 마이그레이션 가이드에 이렇게 나옵니다 — “We will not provide an automated tool for migrating Threads to Conversations.” (출처: OpenAI 공식 마이그레이션 가이드) 마이그레이션 가이드를 훑으면서 가장 눈길이 멈춘 부분입니다.
대신 “신규 대화는 Conversations API로, 기존 Thread 데이터는 필요하면 직접 backfill하라”는 접근을 권장합니다. 이 말은 기존에 쌓인 Thread 메시지 이력을 보존해야 한다면, 직접 `openai.beta.threads.messages.list()`로 내보내고 Conversations API로 재삽입하는 스크립트를 작성해야 한다는 뜻입니다.
Responses API의 응답 객체는 기본 보존 기간이 30일입니다. 반면 Conversations API의 대화 아이템은 30일 제한이 없습니다. 장기 보존이 필요한 대화 이력이 있다면 Conversations API를 써야 합니다. store: false를 설정하면 저장 자체를 하지 않습니다. ZDR(Zero Data Retention) 정책이 있는 조직은 이 옵션이 강제됩니다.
여기에 암호화 추론 옵션(reasoning.encrypted_content)을 같이 쓰면, 상태를 저장하지 않으면서도 추론 토큰의 이점을 유지할 수 있습니다. 데이터를 서버에 두지 말아야 하는 환경에서 쓸 수 있는 현실적인 선택지입니다.
써보니까 Conversations API가 Thread보다 구조적으로 더 유연한 건 맞습니다. 메시지뿐 아니라 툴 호출 결과, 출력 아이템까지 동일한 스트림에 저장됩니다. 그런데 이 유연성이 오히려 기존 Thread 기반 코드를 그대로 이식하기 어렵게 만드는 측면이 있습니다. 개념이 달라지는 만큼 리팩터링이 필요합니다.
지금 당장 해야 할 것 — 2026년 8월 26일까지 남은 153일의 사용법
막연하게 “나중에 하지”가 가장 위험합니다. 실제 마이그레이션은 생각보다 시간이 걸립니다. 공식 가이드와 커뮤니티 논의를 종합하면, 남은 기간 동안 이 순서가 현실적입니다.
현황 파악이 먼저입니다. 프로덕션에서 `/v1/assistants`와 `/v1/threads`를 얼마나 쓰는지 확인합니다. Assistant 수, Thread 평균 길이, 사용 중인 도구(code interpreter, file search 등)를 정리해야 마이그레이션 범위가 나옵니다. 그리고 Responses API로 엔드포인트 한 개를 테스트해봅니다. `client.responses.create()`로 간단한 단일 호출이 잘 되는지 확인하는 것만으로도 감이 옵니다.
핵심 Assistant를 Prompt로 전환합니다. 대시보드에서 중요한 Assistant를 하나씩 Prompt로 만들고, 코드에서 Prompt ID를 참조하도록 변경합니다. 멀티턴 대화가 필요한 흐름은 Conversations API를 붙여봅니다. 이때 Thread 이력 보존이 필요한지 결정하고, 필요하면 backfill 스크립트를 먼저 만들어두는 게 낫습니다.
프로덕션 트래픽을 단계적으로 전환합니다. 전체를 한 번에 바꾸기보다 일부 플로우부터 Responses API로 스위칭하고 결과를 비교합니다. 그리고 종료일 8월 26일보다 최소 2~3주 앞서 완료하는 걸 목표로 잡아야 합니다. 마감 직전에 예상치 못한 호환성 문제가 나올 가능성을 여유분으로 남겨두는 겁니다.
만약 Responses API로 전환할 시간이 촉박하다면, Wire-Compatible 대안(기존 Assistants API 형식을 그대로 지원하는 서드파티 서비스)도 임시 선택지가 됩니다. 다만 최신 기능인 deep research, MCP, computer use는 사용할 수 없고, 서드파티 서비스의 동작 차이가 있을 수 있어서 장기 해법이 아닌 과도기 수단으로만 보는 게 맞습니다.
자주 묻는 질문 (Q&A)
마치며 — 이게 핵심!
Responses API 전환에서 실제로 걸리는 부분은 “엔드포인트 변경”이 아닙니다. Prompt 생성이 API로 안 된다는 점, Thread 자동 이전 도구가 없다는 점, 상태 관리 방법이 세 가지로 분기된다는 점 — 이 세 가지가 마이그레이션 설계를 복잡하게 만듭니다.
그러나 실제로 써보면 Run 폴링 루프가 없어진 것 하나만으로도 코드가 많이 단순해집니다. 비동기 상태 관리 로직 대신 응답이 바로 돌아오는 구조, 그리고 built-in 도구들을 한 번의 API 호출 안에서 쓸 수 있는 점은 개발 편의성이 확실히 올라갑니다.
결론부터 말씀드리면, 지금 당장 신규 기능을 만든다면 처음부터 Responses API로 시작하는 게 맞습니다. 기존 Assistants 기반 서비스는 종료일(2026.08.26) 기준 2~3주 전 완료를 목표로 잡고 지금부터 현황 파악부터 시작하는 것을 권합니다.
본 포스팅 참고 자료
- OpenAI 공식 마이그레이션 가이드 — platform.openai.com/docs/guides/assistants/migration
- OpenAI Responses vs Chat Completions 공식 비교 문서 — platform.openai.com/docs/guides/responses-vs-chat-completions
- OpenAI 커뮤니티 공식 deprecation 공지 (2025.08.26) — community.openai.com
- Ragwalla 마이그레이션 가이드 & Wire-Compatible 대안 (2026.01.28) — ragwalla.com
- Syntackle — Chat Completions·Assistants → Responses API 전환 튜토리얼 (2025.10.08) — syntackle.com
본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. OpenAI는 빈번하게 업데이트를 진행하며, 특히 API 요금·모델 지원 범위·종료 일정은 공식 문서에서 최신 내용을 확인하시기 바랍니다. 본 글의 수치는 2026년 3월 26일 기준 공식 문서를 토대로 작성됐습니다.
댓글 남기기