OpenAI Assistants API 8월 26일 종료: Responses API로 AI 앱 구조가 바뀌는 이유

OpenAI Assistants API 8월 26일 종료: Responses API로 AI 앱 구조가 바뀌는 이유

핵심 요약

  • OpenAI는 Assistants API를 2026년 8월 26일 종료한다. 이 글을 쓰는 8월 17일 기준으로 9일 남았다. 그날 이후에는 Assistant·Thread·Run 호출이 더 이상 동작하지 않는다. 출처: Deprecations | OpenAI API
  • 신규 개발의 중심 API는 Responses API다. 모델 호출과 웹 검색·파일 검색·코드 실행·컴퓨터 사용·원격 MCP 같은 도구 사용을 한 번의 응답 흐름에서 처리한다.
  • 대화 상태는 없어지지 않는다. Responses API는 응답을 기본으로 저장하며(기본 보관 30일), previous_response_id로 직전 응답을 이어 붙이거나 Conversations API로 대화 객체를 유지할 수 있다. 저장을 원하지 않을 때만 store: false를 넣는다.
  • 공식 마이그레이션 가이드는 기존 Assistant를 Prompt 객체로 옮기는 경로를 안내한다. 그러나 재사용 가능한 Prompt 객체 자체도 2026년 6월 3일 지원 중단이 공지됐고 v1/prompts는 2026년 11월 30일 종료 예정이다. 신규 프로젝트는 Prompt 객체를 장기 구조로 전제하면 안 된다. 출처: Migrate from prompt objects | OpenAI API
  • 기존 사용자는 호출부만 바꾸면 끝나지 않는다. 종료 전에 Thread 데이터 이전, 도구 호출 루프 재작성, 같은 입력을 두 API에 넣어 비교하는 회귀 검증까지 마쳐야 한다.

Assistants API는 자기 서비스에 AI 비서를 넣는 개발자용 API였다

Assistants API는 개발자가 자신의 앱이나 웹서비스 안에 AI 비서를 만들어 넣도록 OpenAI가 제공해 온 API다. 대화 기록을 기억하고, 업로드한 파일을 검색하고, 외부 기능을 실행하는 일을 OpenAI 서버가 대신 관리해 줬다. 예를 들어 쇼핑몰 고객지원 챗봇을 만든다면 AI의 역할과 지침을 한 번 저장해 두고, 고객별 대화 기록을 유지하고, 주문 조회 같은 사내 기능까지 연결할 수 있었다. 이를 위해 제공한 주요 객체가 Assistant, Thread, Run이다.

헷갈리기 쉬운 지점이 하나 있다. Assistants API는 ChatGPT 화면에서 쓰는 ‘GPT 만들기’ 기능이 아니다. GPT 만들기는 ChatGPT 사용자가 ChatGPT 안에서 쓰는 기능이고, Assistants API는 개발자가 자기 서비스나 앱에 OpenAI 기반 AI 기능을 넣기 위해 코드에서 호출하는 API다. 8월 26일 종료 대상은 후자다. ChatGPT의 GPT 만들기는 이번 종료와 무관하다.

실제로 이 API 위에 올라간 제품은 사내 규정 문서 질의 봇, 고객지원 자동응답, 계약서·보고서 분석 도구처럼 대화와 문서 검색과 내부 시스템 호출이 함께 필요한 서비스였다. 벡터 검색 인프라를 따로 구축하지 않고도 파일을 붙여 지식 검색을 하거나 Code Interpreter로 계산을 시킬 수 있어서, 소규모 팀이 빠르게 만들기에 좋았다.

Assistants API는 어떻게 작동했나

세 객체의 역할은 이렇게 나뉘었다.

Assistant는 AI의 동작 설정을 담은 객체다. 어떤 모델을 쓸지, instructions에 어떤 지침을 넣을지, tools에 어떤 도구를 선언할지를 한곳에 저장했다. 고객지원 봇이라면 “반품 정책 문서를 먼저 검색하고, 환불 승인은 내부 함수를 호출하되 확인 질문을 거친다”는 규칙을 Assistant 하나에 넣어 두고 계속 재사용했다.

Thread는 사용자별 대화 기록이다. 메시지 이력을 OpenAI 서버가 보관했기 때문에, 서비스의 customer_id와 Thread ID를 연결해 두면 고객이 사흘 뒤에 다시 접속해도 이전 메시지를 전부 다시 보내지 않고 대화를 이어 갈 수 있었다. 출처: Assistants API (v2) FAQ | OpenAI Help Center

Run은 특정 Thread를 대상으로 Assistant를 실행하는 과정이다. 애플리케이션은 Run을 만든 뒤 queued, in_progress, requires_action, completed 같은 상태를 폴링했다. 주문 조회 함수 호출이 필요하다고 나오면 앱이 인자를 받아 내부 API를 실행하고 결과를 제출했고, 같은 Run이 그 결과로 답변을 완성했다.

사내 문서 검색 서비스라면 여기에 file_search가 하나 더 붙는다. 이 도구는 벡터 스토어 생성과 청크 분할 같은 기본 설정을 관리형으로 대신해 줬다. 그래서 전환 범위는 채팅 응답 코드만이 아니다. 벡터 스토어, 파일 보존 정책, 문서별 접근 권한, 검색 결과 인용 표시까지 함께 옮겨야 한다.

OpenAI는 왜 Assistants API를 종료하나

대체 API인 Responses API부터 짚고 가자. Responses API는 모델 호출과 도구 사용을 하나의 응답 흐름에서 다루는 API다. 웹 검색, 파일 검색, Code Interpreter, 컴퓨터 사용, 원격 MCP, 이미지 생성 같은 도구와 개발자가 정의한 함수를 같은 요청 안에서 쓸 수 있다. Assistants API와 달리 AI 비서를 미리 만들어 둘 필요가 없고, Chat Completions처럼 한 번 호출하면 되는 형태에 도구 사용 기능이 들어가 있다. 출처: Migrate to the Responses API | OpenAI API

OpenAI 개발자 블로그는 Assistants API를 두고, 일부 개발자가 좋아하긴 했지만 Chat Completions에 비해 제약이 많고 도입하기 어려운 API 설계 탓에 널리 쓰이지는 못했다고 설명한다. 그래서 2024년 말 시점에 Chat Completions만큼 접근하기 쉽고 Assistants만큼 도구를 다룰 수 있으면서 멀티모달·reasoning 모델에 맞춰 만든 하나의 인터페이스가 필요하다고 판단했다는 것이 회사의 공식 설명이다. Responses API는 Chat Completions의 메시지 형식과 Assistants API에서 나온 도구 사용 기능을 합친 결과다. 출처: Why we built the Responses API | OpenAI Developers

일정은 이미 1년 전에 예고됐다. OpenAI는 2025년 8월 26일 Assistants API 사용 개발자에게 지원 중단을 통지했고, 정확히 1년 뒤인 2026년 8월 26일 API에서 제거한다고 못 박았다. 2025년 3월 Responses API를 내놓을 때부터 Assistants API의 기능을 Responses API로 모두 옮긴 뒤 2026년에 종료하겠다고 밝혀 온 계획의 마지막 단계다. 출처: Deprecations | OpenAI API

Assistant·Thread·Run은 무엇으로 바뀌나

공식 마이그레이션 가이드는 기존 객체와 새 객체를 아래처럼 대응시킨다. 다만 가운데 열은 기존 서비스를 옮길 때의 경로이고, 지금 새로 만드는 앱에 권장되는 구조는 오른쪽 열이다. 두 열이 다른 이유는 Prompt 객체 때문인데, 표 아래에서 설명한다.

기존 Assistants API 마이그레이션 가이드가 안내하는 대응 지금 새로 만들 때 권장되는 방식
Assistant (모델·instructions·tools 설정) Prompt 객체로 옮길 수 있음 (과도기 수단) 모델·instructions·tools를 애플리케이션 코드에서 관리하고 요청마다 전달
Thread (사용자별 대화 기록) Conversation Conversations API 또는 previous_response_id, 필요하면 자체 DB에서 이력 관리
Run (Thread에 Assistant 실행) Response Responses API 호출. 도구 호출 루프는 애플리케이션이 직접 관리
Run step (실행 단계) Item 메시지, 도구 호출, 도구 결과를 같은 output item 배열에서 처리

Prompt 객체를 새 구조의 정답으로 이해하면 안 된다. 마이그레이션 가이드는 기존 Assistant의 지침과 도구 묶음을 대시보드에서 Prompt로 다시 만드는 경로를 제시하면서도, 오래 유지할 통합에 Prompt 객체를 넣기 전에 prompts 지원 중단 일정을 확인하라고 함께 적어 두었다. 실제로 OpenAI 지원 중단 목록에는 재사용 가능한 Prompt 객체의 지원 중단이 2026년 6월 3일 공지되면서 플랫폼에서 프롬프트 생성 기능이 축소됐고, v1/prompts API는 2026년 11월 30일 종료 예정이라고 적혀 있다. 출처: Deprecations | OpenAI API, Assistants migration guide | OpenAI API

정리하면 Prompt는 8월 26일을 넘기기 위한 과도기 수단이다. 기존 Assistant가 수십 개라면 대시보드에서 Prompt로 옮겨 급한 불을 끄는 선택은 가능하지만, 11월 30일 전에 다시 한 번 걷어내야 한다. 신규 앱이라면 처음부터 Prompt 객체를 건너뛰는 편이 낫다.

대신 OpenAI가 권장하는 방식은 프롬프트 문구와 모델·instructions·tools 설정을 애플리케이션 코드에 두는 것이다. 공식 문서는 프롬프트를 prompts/ 모듈 안의 이름 붙은 빌더 함수로 두고, 프롬프트 변수는 타입이 있는 함수 인자로 바꾸고, 만들어진 메시지를 Responses API의 input과 instructions로 바로 넘기는 예를 든다. 이렇게 하면 프롬프트 변경이 PR 리뷰를 거치고 CI에서 테스트와 평가를 돌릴 수 있다는 것이 문서가 밝힌 이유다. 출처: Migrate from prompt objects | OpenAI API

Responses API에서도 대화 상태는 유지할 수 있다

Responses API로 바꾼다고 대화 기록이 사라지지 않는다. 여러 턴을 이어 붙이는 방법이 세 가지 있고, 셋 중 무엇을 쓸지 개발자가 고른다.

  • previous_response_id: 직전 Response의 ID를 다음 요청에 넣으면 OpenAI가 앞선 맥락을 이어 준다. 코드가 가장 단순하지만, 이어 붙인 앞 대화의 토큰이 매 요청에서 입력 토큰으로 다시 과금된다는 점을 감안해야 한다.
  • Conversations API: 대화를 고유 식별자를 가진 객체로 만들어 메시지·도구 호출·도구 결과를 item 흐름으로 보관한다. 기존 Thread에 가장 가까운 대체물이며, 여러 세션에 걸친 장기 대화에 적합하다.
  • 자체 DB: user와 assistant 메시지를 애플리케이션이 직접 저장했다가 요청마다 조립해 보낸다. 개인정보 보관 위치를 직접 통제해야 하는 서비스가 택하는 방식이다.

저장 동작도 정확히 알아 둘 필요가 있다. Responses API는 응답을 기본으로 저장한다. store: true를 넣어야 상태가 생기는 것이 아니라, 아무것도 지정하지 않으면 저장되고 Response 객체는 기본 30일 보관된다. 저장을 원하지 않으면 요청에 store: false를 넣는다. 다만 Conversation 객체는 이 30일 보관 규칙을 적용받지 않는다. 출처: Conversation state | OpenAI API

한 가지 더. 대화 이력을 제품 상태로 착각하면 안 된다. 고객지원 AI는 주문 번호, 인증 수준, 상담 이관 여부, 환불 실행의 멱등성 키를 모델 대화와 별도로 자체 데이터베이스에 보관해야 한다. Conversation과 저장된 Response는 모델이 참고할 맥락을 담는 곳이지, 업무 트랜잭션 기록이 아니다.

Responses API에서는 검색·코드 실행·MCP를 한 요청에서 쓸 수 있다

Responses API를 새로운 채팅 호출로만 보면 가장 큰 차이를 놓친다. 공식 가이드는 웹 검색, 파일 검색, 컴퓨터 사용, Code Interpreter, 원격 MCP 같은 도구를 사용자 정의 함수와 함께 같은 인터페이스에서 쓸 수 있다고 안내한다. 응답도 문자열 하나가 아니라 유형이 있는 output item 배열이라, 앱은 최종 문장만 읽는 대신 어떤 도구가 어떤 결과를 남겼는지 각각 처리할 수 있다. 출처: Migrate to the Responses API | OpenAI API

사내 문서 검색: 권한은 file_search 호출 전에 서버가 정한다

직원이 “이번 분기 보안 예외 승인 절차는 무엇인가”라고 묻는 경우를 보자. 애플리케이션은 먼저 사용자와 소속 조직의 권한을 확인하고, 그 사람이 볼 수 있는 벡터 스토어만 file_search 도구에 연결해 Responses API를 호출한다. 모델이 문서 접근 권한을 판단하게 두면 안 된다. 권한 필터는 호출 전에 서버에서 확정하고, 인용이 없는 답변을 화면에 그대로 보여 줄지도 미리 정해 둬야 한다.

고객지원 챗봇: 조회는 모델에 맡기고 환불 실행은 서버가 검증한다

고객이 배송 지연을 물으면 모델은 주문 조회 함수를 호출하고 정책 문서를 파일 검색으로 확인해 답할 수 있다. 반면 환불이나 주소 변경처럼 실제 데이터를 바꾸는 작업은 다르다. 모델이 함수 호출 인자를 만들었다는 사실 자체는 실행 승인이 아니다. 서버가 인증된 사용자인지, 그 주문의 소유자인지, 금액과 정책 조건에 맞는지, 같은 요청이 두 번 들어와도 환불이 한 번만 되는지를 검증한 뒤에 내부 API를 호출해야 한다.

기존에 requires_action 폴링 코드 곳곳에 이 검증이 흩어져 있었다면, 이번 전환에서 도구 실행 코드를 별도 모듈로 분리해 정리할 수 있다. 도구 스키마에는 최소한의 인자만 노출하고, 고위험 동작은 확인 단계를 따로 두고, 성공·거절·재시도 결과를 감사 로그에 남기는 식이다.

파일 분석: 요약 품질과 계산 정확도는 따로 검증한다

계약서, 보고서, 스프레드시트를 분석하는 서비스는 파일 검색과 Code Interpreter를 상황에 따라 골라 쓴다. 월별 매출 파일에서 이상치를 찾는 요청은 계산 도구가 맞고, 여러 보고서의 정책 차이를 묻는 요청은 검색과 인용이 중심이다. 두 작업의 합격 기준은 다르다. “요약이 읽기 좋은가”와 “표에 적힌 숫자가 원본과 같은가”를 같은 테스트로 확인할 수 없다. 파일 업로드 완료, 인덱싱 완료, 도구 실행 실패, 답변 완료를 각각 사용자에게 보여 주는 화면 설계도 새로 필요하다.

웹 검색·MCP·computer use: 무엇을 보고 무엇을 실행했는지 기록에 남긴다

웹 검색과 원격 MCP, computer use는 모델이 다룰 수 있는 범위를 외부로 넓힌다. 시장 조사 도구라면 웹 검색 결과로 초안을 만들고, 승인된 MCP 서버로 사내 카탈로그를 조회한 뒤, 산출물에 출처와 실행 내역을 남길 수 있다. 대신 MCP 서버에 어떤 데이터가 전달되는지, 도구별 시간 제한과 재시도는 어떻게 되는지, 실패했을 때 사용자에게 무엇을 보여 줄지를 먼저 정해야 한다. computer use는 화면 상태에 따라 결과가 달라지므로 실행 가능한 범위를 좁히고, 되돌리기 어려운 작업에는 사람의 승인을 넣는 편이 안전하다.

Run이 없어져도 도구 실행 관리는 애플리케이션 몫이다

Run은 비동기 실행을 표현하는 객체였다. Responses API는 입력 item을 보내고 출력 item을 받는 더 단순한 형태이고, 공식 대응표에도 도구 호출 루프는 애플리케이션이 명시적으로 관리한다고 적혀 있다. 즉 Run 상태 폴링이라는 코드가 없어지는 대신, 동기 호출·스트리밍·백그라운드 처리·도구 결과 제출을 어떻게 조합할지 서비스가 직접 정하게 된다. 출처: Assistants migration guide | OpenAI API

기존
사용자 메시지 → Thread에 저장 → Run 생성 → 상태 폴링
                              └→ 함수 호출 요구 → 앱이 결과 제출 → Run 완료

새 구조
사용자 입력 + 코드에서 만든 instructions·tools + Conversation(선택)
                    → Responses 호출 → output items
                    → 함수 호출 item이면 앱이 검증하고 실행
                    → 도구 결과를 넣어 다음 Responses 호출

마이그레이션 코드에서 가장 흔한 실수는 response.output_text만 읽고 끝내는 것이다. 단순 질의응답이면 충분하지만, 함수 호출과 인용과 구조화된 출력을 쓰는 앱은 item 유형별 처리기를 만들어야 한다. Chat Completions의 choices[].message와 달리 Responses는 고유 ID와 유형이 있는 output 배열을 반환하고, output_text는 그중 텍스트만 꺼내 주는 편의 필드다. 로깅과 재실행이 필요한 앱일수록 원본 item을 기준으로 저장해야 한다. 출처: Migrate to the Responses API | OpenAI API

기존 사용자는 무엇을 먼저 옮겨야 하나

8월 26일 전 우선순위는 SDK 버전을 올리는 일이 아니다. 서비스가 Assistants API의 무엇에 기대고 있는지 목록으로 만드는 일이 먼저다. 아래 항목을 제품·환경별로 확인한다.

  • 코드에서 Assistants API를 호출하는 위치. 화면에 보이는 채팅뿐 아니라 야간 배치, 관리자 도구, 오래된 고객 플랜, 장애 복구 경로까지 찾아야 한다. 여기 남은 호출은 8월 26일 이후 그대로 실패한다.
  • Assistant별 설정과 instructions. 새 코드로 옮길 원문이다. 모델명, 도구 선언, 응답 형식, 금지 행동, 사람에게 넘기는 기준까지 함께 적어 둬야 이전 후에 동작이 달라졌는지 판단할 수 있다.
  • Thread에 의존하는 대화 상태. 활성 고객의 진행 중 대화, 법적·운영상 보존 대상, 보관만 하면 되는 과거 대화를 구분한다. Thread를 Conversation으로 옮겨 주는 자동 도구는 제공되지 않는다. 메시지를 순서대로 읽어 item으로 변환하는 코드를 직접 작성해야 한다.
  • Run 폴링 또는 스트리밍 로직. Responses에는 Run 상태값이 없으므로, 진행 표시·취소 버튼·재시도·실패 알림을 어떤 신호로 대체할지 다시 설계해야 한다.
  • 사용 중인 도구. file search, Code Interpreter, function calling 중 무엇을 쓰는지, 어떤 벡터 스토어와 파일이 어느 Assistant에 붙어 있는지 확인한다. 이름이 같아도 설정 방식과 결과 형식이 달라서 인용 표시나 응답 파싱이 조용히 깨질 수 있다.
  • 데이터 이전 필요 여부. 모든 과거 대화를 옮길 필요는 없다. 옮기지 않기로 한 데이터는 종료일 이후 조회 수단이 없어지므로, 필요한 범위는 미리 내려받아 보관해야 한다.

8월 26일 전에는 기존·신규 API를 함께 검증해야 한다

새 API 호출이 200을 반환하는 것과 제품이 예전처럼 동작하는 것은 다르다. 남은 기간에 최소한 다음 순서는 밟는 편이 좋다.

  1. 대표 질의 30~50개를 골라 같은 입력을 기존 API와 Responses API에 넣고 결과를 비교한다. 문장이 글자 단위로 같을 필요는 없다. 모델 출력은 원래 매번 조금씩 달라진다. 확인할 것은 인용한 문서가 같은지, 호출한 함수와 인자가 같은지, 출력 스키마가 유효한지다.
  2. 정상 경로만 보지 말고 실패 경로를 함께 넣는다. 권한 없는 문서 요청, 함수 실행 실패, 네트워크 오류, 중단 후 재개, 긴 문맥이 잘리는 경우가 여기 해당한다. 도구 실행이 얽힌 코드는 이런 경로에서 먼저 깨진다.
  3. 스트리밍과 대화 이어짐을 따로 확인한다. 스트리밍 이벤트 형식이 Run 기반 코드와 다르고, previous_response_id나 Conversation으로 바꾼 뒤 두세 턴 뒤에야 맥락이 끊기는 문제가 드러나는 경우가 많다.
  4. 전체를 한 번에 바꾸지 말고 일부 트래픽부터 전환하고, 서비스별로 되돌릴 기준을 정해 둔다. 배포 버전과 프롬프트 변경 이력을 함께 기록해야 문제가 생겼을 때 원인을 가릴 수 있다.

지금 새 서비스를 만든다면 무엇을 기준으로 잡을까

새로 시작하는 프로젝트라면 Assistants API 문서는 볼 필요가 없다. 만들려는 기능이 한 번의 생성인지, 여러 턴이 이어지는 대화인지, 문서 검색인지, 외부 시스템을 바꾸는 자동화인지부터 정한다. 그다음 모델 호출은 Responses API로 하고, 대화가 이어져야 한다면 Conversations API나 previous_response_id를 붙이고, 프롬프트와 도구 선언은 소스 코드에 두고 git으로 관리한다. Prompt 객체는 11월 30일 종료 예정이므로 새 설계의 전제로 삼지 않는다.

다만 Prompts·Conversations·Responses가 모든 AI 앱의 표준이 된다고 단정할 근거는 없다. 다른 모델 제공사와 프레임워크는 각자의 상태·도구 모델을 쓰고 있다. 여기서 확실한 것은 OpenAI API를 쓰는 팀에게 종료일과 권장 방향이 이미 문서로 나와 있다는 사실이다.

정리하면 이렇다. 8월 26일 이후 OpenAI로 새 AI 앱을 만들 때는 Assistant를 미리 만들어 두고 Thread에 메시지를 쌓아 Run으로 실행하는 구조 대신, Responses API 한 번의 호출에 모델 설정과 도구를 넘기고 반환된 output item을 앱이 처리하는 구조가 기본이 된다. 대화를 이어 가야 하면 Conversations API나 이전 응답 ID를 쓰고, 도구 실행의 권한 확인과 재시도는 앱 코드가 맡는다. 기존 서비스를 운영 중이라면 남은 9일은 새 기능을 붙일 기간이 아니라, 지금 돌아가는 동작을 그대로 재현해 두는 기간이다.

참고 출처