새 프로젝트를 시작한다면 Assistants API보다 Responses API를 기준으로 잡는 편이 안전하다. OpenAI는 2025년 3월 11일 Responses API를 에이전트 빌딩의 새 기본 축으로 소개했고, 공식 migration 문서에서는 Assistants API 종료일을 2026년 8월 26일로 적어두고 있다. 이미 Assistants API를 쓰고 있다면 핵심 질문은 옮길까 말까가 아니라 무엇부터 옮길까에 가깝다.
빠르게 판단하면 이렇다.
- 새 프로젝트면 Responses API로 시작한다.
- 기존 Assistants API 프로젝트는 2026년 8월 26일 이전 migration 계획이 필요하다.
- 먼저 옮길 것은 tool/function integration이다.
- 종료 일정 같은 사실값은 모델 답변이 아니라 공식 문서로 고정한다.
먼저 판단부터
| 상황 | 지금 판단 |
|---|---|
| 새 에이전트 기능을 처음 만든다 | Responses API로 시작 |
| Assistants API를 이미 운영 중이다 | 2026년 8월 26일 이전 migration 계획 필요 |
| 무엇부터 옮겨야 할지 모르겠다 | tool/function integration부터 정리 |
| 모델이 날짜를 다르게 말한다 | 공식 migration 문서 기준으로 고정 |
왜 Responses API가 새 기본값인가
OpenAI가 Responses API를 내세우는 이유는 단순히 엔드포인트 이름을 바꾸려는 게 아니다. 기존에는 chat, tool 호출, 상태 관리, 스트리밍, 멀티모달 입력을 구현하면서 API 경계가 여러 군데로 나뉘는 느낌이 강했다. Responses API는 이 흐름을 한쪽으로 모으려는 방향에 가깝다.
직접 최소 예제를 돌려보면 차이가 더 빨리 보인다.
- 요청 모양이 단순하다.
- tool 호출이나 후속 응답 체인을 같은 mental model로 다룰 수 있다.
previous_response_id를 붙여 후속 질문을 이어가는 방식이 직관적이다.
작은 데모에서는 이 차이가 크게 안 보일 수 있다. 하지만 tool 호출이 섞이기 시작하면 어디에 상태를 두고, 어디서 다음 턴을 이어갈지가 코드 구조를 많이 바꾼다.
Assistants API 종료 일정이 의미하는 것
여기서 중요한 날짜는 2026년 8월 26일이다. OpenAI의 migration 문서는 Assistants API 종료일을 이 날짜로 명시한다.
- 새 프로젝트를 굳이 Assistants API 위에 올릴 이유가 거의 없다.
- 기존 프로젝트는 종료일 직전에 급하게 옮기지 않도록 migration 순서를 미리 나눠야 한다.
종료 일정이 있다고 해서 오늘 당장 모든 코드를 뒤엎을 필요는 없다. 다만 지금도 새 기능을 Assistants API 기준으로 더 얹고 있다면, 나중에 옮길 비용을 스스로 키우는 셈이다.
내가 실제로 돌린 최소 재현 예제
로컬에서는 아래 흐름만 검증했다.
client.responses.create(...)로 첫 응답 호출store=True로 응답 상태 저장- 두 번째 호출에서
previous_response_id=<첫 응답 id>전달
이번 테스트에 사용한 스크립트 이름은 wn101_responses_migration.py다.
핵심 부분만 보면 구조는 이 정도다.
from openai import OpenAI
client = OpenAI()
first = client.responses.create(
model="gpt-5-mini",
instructions="You are a concise API migration assistant.",
input="In three bullets, explain why the Responses API is the preferred starting point.",
store=True,
)
second = client.responses.create(
model="gpt-5-mini",
instructions="You are a concise API migration assistant.",
input="What is the shutdown date for the Assistants API, and what should I migrate first?",
previous_response_id=first.id,
store=True,
)
실행 로그는 로컬에서 JSON으로 남겨 재검토했다.
돌려보니 확인된 점
첫 번째 호출은 Responses API를 새 기본값으로 봐야 하는 이유를 비교적 일관되게 설명했다. 요약하면 아래 세 가지였다.
- chat, tool 호출, action 흐름을 한 엔드포인트 아래에서 다루기 쉽다.
- tool/function 호출을 에이전트 흐름 안에 넣기 편하다.
- 앞으로 추가되는 기능도 이 경로로 붙을 가능성이 높다.
이 정도는 공식 발표 방향과도 크게 다르지 않았다.
두 번째 호출도 previous_response_id 체인 자체는 정상적으로 동작했다. 첫 번째 맥락을 이어받아 migration 우선순위를 묻는 질문에 답했다. 문제는 여기서부터다. 모델은 Assistants API 종료일을 정확히 확정하지 못했고, 공식 문서를 확인하라고 답했다.
이 실패는 오히려 유용했다.
previous_response_id는 대화 체인을 이어주는 장치다.- 공식 사실값을 보장하는 장치는 아니다.
즉, Responses API를 직접 재현하는 데 모델 응답은 도움이 되지만, 종료 일정 같은 값은 문서 기준으로 써야 한다.
여기서 바로 얻은 migration 우선순위
실제 실행과 공식 문서를 같이 놓고 보면, 옮길 순서는 이렇게 잡는 편이 낫다.
1. tool/function integration
가장 먼저 볼 것은 tool manifest, function signature, 외부 연동 지점이다. 이 부분이 깨지면 에이전트는 겉으로만 살아 있고 실제 일은 못 한다. 모델이 무엇을 호출할 수 있는지, 호출 결과를 어디에 넣는지부터 Responses API 기준으로 다시 정리하는 편이 맞다.
2. state와 system instruction
그다음은 assistant 설정, system prompt, metadata, memory 비슷한 층이다. Assistants API에서 암묵적으로 묶여 있던 구조를 Responses API에서는 조금 더 명시적으로 다시 설계해야 할 수 있다.
3. streaming, UI, telemetry
프론트엔드에서 스트리밍을 어떻게 받아 보여주는지, 에러를 어떻게 기록하는지, 로깅을 어디에 남기는지도 마지막에 점검해야 한다. 이 단계는 데모에서는 잘 안 보이지만 실제 운영에서는 꽤 큰 차이를 만든다.
모델 답변만 믿으면 안 되는 이유
이번 실행에서 가장 기사 가치가 있는 부분도 여기다. 같은 세션 안에서 migration 질문을 이어갔는데도 모델은 종료일을 스스로 정확히 못 박지 못했다. 이건 모델이 나빠서가 아니라, 질문의 종류가 다르기 때문이다.
- API 동작 설명은 모델이 꽤 잘한다.
- 공식 문서의 특정 날짜나 정책은 문서 확인이 더 중요하다.
이 차이를 분리하지 않으면 기술 글이 얇아진다. 직접 실행한 결과, 공식 문서, 코드 예제를 한 자리에 놓고 교차 확인해야 글이 단단해진다.
그래서 지금 어떻게 움직이면 되나
새 프로젝트라면 Responses API를 기본으로 두고 시작하면 된다. 기존 Assistants API 프로젝트라면 아래 순서로 움직이는 편이 무난하다.
- 현재 tool/function 호출 지점을 목록으로 뽑는다.
- Responses API 기준으로 최소 호출 예제를 만든다.
previous_response_id같은 체인 구조가 현재 앱 흐름과 맞는지 확인한다.- 종료 일정과 migration 범위는 공식 문서 기준으로 체크리스트를 만든다.
- 그 다음에 UI와 운영 로깅을 옮긴다.
당장 하나만 해보라면, 지금 Assistants API로 돌고 있는 가장 작은 기능 하나를 골라 Responses API로 그대로 다시 붙여보는 편이 좋다. 이 한 번의 재현이 migration 난이도를 가장 빨리 보여준다.
FAQ
새 프로젝트에서도 Assistants API를 써도 되나
기술적으로는 아직 가능하다. 다만 OpenAI가 중심축을 Responses API로 옮긴 상태라, 지금 새로 시작한다면 굳이 이전 경로를 고를 이유가 약하다.
종료일만 보면 아직 여유가 있는 것 아닌가
여유는 있다. 문제는 종료일 자체보다 그 전까지 쌓이는 이전 API 의존성이다. 새 기능을 계속 Assistants API 기준으로 얹으면, 나중에 옮길 범위만 커진다.
previous_response_id만 쓰면 상태 관리가 끝나나
그 정도로 단순하지는 않다. 데모 수준의 후속 질문에는 편하지만, 실제 제품에서는 사용자 세션, tool 결과, UI 상태, 로깅까지 같이 봐야 한다.
참고 자료
실행 로그 첨부
아래 파일은 토큰, 세션, 개인 식별 정보를 마스킹한 공개용 실행 로그다.