Assistants API 8월 26일 종료｜Responses API 마이그레이션 순서

OpenAI Assistants API는 2026년 8월 26일 종료 예정이므로 /assistants, /threads, /runs를 호출하는 운영 서비스는 즉시 Responses API와 Conversations API로 전환해야 합니다. 기존 Assistant 설정은 Prompt로, Thread 상태는 Conversation으로, Run 실행은 Response로 대응시키되 객체가 일대일로 자동 변환된다고 가정하면 안 됩니다. Azure OpenAI Assistants를 쓰는 경우에는 OpenAI 직접 API 경로와 달리 Microsoft Foundry Agents 마이그레이션 지침을 따라야 합니다.

8월 26일에 정확히 무엇이 종료되나요?

OpenAI API 지원 종료 목록은 Assistants API의 종료일을 2026년 8월 26일로 명시하고, 대체 경로로 Responses API와 Conversations API를 제시합니다. 이는 단순히 문서에서 ‘deprecated’ 표시가 붙는 날짜가 아니라 기존 Assistants API 통합의 가용성에 영향을 줄 수 있는 종료일입니다.

Chat Completions나 모든 OpenAI 모델이 함께 종료된다는 뜻은 아닙니다. 코드가 assistant_id, Thread, Run 객체를 만들거나 조회하는지부터 확인해야 합니다. 모델 호출만 하고 Assistants·Threads·Runs 엔드포인트를 사용하지 않는 서비스라면 이 종료의 직접 대상이 아닐 수 있습니다.

기존 객체는 새 API에서 무엇으로 바뀌나요?

OpenAI 공식 Assistants 마이그레이션 가이드는 핵심 개념을 다음과 같이 대응시킵니다.

기존 Assistants API	새 구조	마이그레이션 핵심
Assistant	Prompt	모델·도구·지침 구성을 대시보드에서 버전 관리
Thread	Conversation	메시지뿐 아니라 도구 호출·출력 등 Item 흐름을 보존
Run	Response	입력 Item을 보내고 출력 Item을 받으며 실행 상태 처리
Run step	Item	메시지·도구 호출·도구 결과를 일반화된 Item으로 관리

이 표는 개념 대응이지 데이터베이스 레코드를 이름만 바꾸라는 뜻이 아닙니다. 응답 저장 방식, 도구 호출 루프, 재시도, 스트리밍 이벤트, 파일과 벡터스토어 참조를 새 API 동작에 맞게 다시 검증해야 합니다.

우리 서비스가 영향을 받는지 어떻게 찾나요?

• 소스와 로그에서 /v1/assistants, /v1/threads, /v1/runs 경로를 검색합니다.
• SDK 코드에서 beta.assistants, beta.threads, createAndPoll 같은 호출을 찾습니다.
• 환경변수나 데이터베이스에 저장한 assistant_id, thread_id, run_id 사용처를 찾습니다.
• File Search·Code Interpreter·Function Calling을 어느 단계에서 연결했는지 목록화합니다.
• 스트리밍 이벤트와 Run 상태값에 의존하는 UI·백그라운드 작업을 확인합니다.
• OpenAI 직접 API와 Azure OpenAI 엔드포인트를 별도 서비스로 구분합니다.
• 트래픽이 없는 오래된 작업·예약·웹훅도 실제 운영 호출 가능성이 있는지 확인합니다.

예를 들어 서버 코드에 threads.runs.create가 있고 고객별 thread_id를 저장한다면 직접 영향 대상입니다. 반대로 단발성 responses.create만 호출하고 Conversation이나 Assistants 객체를 사용하지 않는 새 서비스라면 기존 Assistants 데이터 마이그레이션 대상은 아닙니다.

OpenAI 직접 API는 어떤 순서로 옮기나요?

1. 재고 고정: 운영 Assistant와 도구·파일·지침·모델, 호출량과 담당 서비스를 목록으로 확정합니다.
2. Prompt 구성: Assistant의 instructions·tools·모델 설정을 새 Prompt 구조로 옮기고 버전을 고정합니다.
3. 상태 이전: 신규 대화는 Conversation으로 시작하고 기존 Thread 이력을 얼마나 가져갈지 정책을 정합니다.
4. 실행 교체: Run 생성·폴링 코드를 Response 생성과 출력 Item 처리로 바꿉니다.
5. 도구 루프: 함수 호출 결과를 어떤 Item으로 다시 전달하는지, 실패·중복 실행을 어떻게 막는지 검증합니다.
6. 파일 검증: File Search와 벡터스토어, 첨부파일 접근이 새 경로에서 같은 결과를 내는지 확인합니다.
7. 회귀 테스트: 대표 질문, 긴 대화, 도구 실패, 스트리밍 중단, 재시도와 비용을 기존 기준과 비교합니다.
8. 단계 전환: 일부 트래픽부터 새 경로로 보내고 오류율·지연·출력 차이를 확인한 뒤 전체 전환합니다.

Prompt는 기존 Assistant와 달리 대시보드에서 만들고 버전 관리하는 구조이므로, 배포 코드와 Prompt 버전이 서로 어긋나지 않게 릴리스 기록을 남겨야 합니다. 애플리케이션은 대화 정리, 도구 루프, 재시도 같은 오케스트레이션 책임을 더 명확히 가져갑니다.

기존 Thread 대화는 그대로 복사하면 되나요?

무조건 전체 복사하는 방식은 피하는 것이 좋습니다. Conversation은 메시지뿐 아니라 도구 호출과 결과를 포함한 Item 흐름을 다루므로, 기존 Thread 메시지만 옮기면 도구 실행 맥락이 빠질 수 있습니다. 반대로 오래된 전체 이력을 모두 넣으면 토큰과 개인정보 보관 범위가 불필요하게 커질 수 있습니다.

예를 들어 고객지원 Assistant가 최근 주문 조회 함수를 호출했다면 사용자 질문과 최종 답변만 저장할지, 도구 호출 결과까지 보존할지 정책을 먼저 정해야 합니다. 이전 대화는 읽기 전용 보관하고 새 Conversation부터 전환하는 방법과, 필요한 요약만 새 대화 첫 Item에 넣는 방법을 비교하십시오.

도구 호출과 파일 검색은 무엇을 다시 시험하나요?

Responses API에서는 도구 호출 결과를 명시적으로 처리하는 루프가 중요합니다. 같은 함수가 재시도 중 두 번 실행되지 않는지, 도구 결과를 잘못된 Response에 붙이지 않는지, 타임아웃 후 재개가 가능한지 확인하십시오. 결제·메일·외부 변경처럼 부작용이 있는 함수는 멱등성 키와 승인 경계를 두는 것이 안전합니다.

File Search는 기존 파일과 벡터스토어가 새 Prompt·Response 경로에서 올바르게 참조되는지 확인합니다. 문서 인용, 접근권한, 삭제된 파일 처리, 검색 결과가 없는 경우를 각각 시험하고, Code Interpreter가 만든 파일의 다운로드·보관 흐름도 별도로 검증하십시오.

Azure OpenAI Assistants는 같은 방법으로 옮기나요?

대체 방향이 다릅니다. Microsoft Learn의 Azure OpenAI Assistants 안내도 2026년 8월 26일 종료를 명시하지만, Azure 사용자는 일반 제공되는 Microsoft Foundry Agents 서비스와 해당 마이그레이션 가이드를 따르라고 안내합니다.

엔드포인트가 openai.azure.com 아래의 Assistants·Threads·Runs를 호출하는지, 새 services.ai.azure.com 프로젝트 기반 Foundry Agents를 쓰는지 먼저 구분하십시오. OpenAI 직접 API용 Responses 예제를 Azure 코드에 그대로 붙이거나, Azure Foundry Agents의 별도 지원일정을 OpenAI Assistants API에도 적용하면 안 됩니다.

전환 완료로 판단하는 기준은 무엇인가요?

• 운영 트래픽에서 Assistants·Threads·Runs 호출이 0건입니다.
• 대표 입력의 정답성·도구 선택·구조화 출력이 기존 허용범위 안입니다.
• 긴 대화와 파일 검색에서 필요한 맥락이 유지됩니다.
• 함수 재시도에도 중복 결제·중복 메시지 같은 부작용이 없습니다.
• 스트리밍 중단·타임아웃·도구 오류가 사용자에게 복구 가능한 상태로 표시됩니다.
• Prompt 버전과 애플리케이션 배포 버전을 추적할 수 있습니다.
• 기존 키·웹훅·백그라운드 작업에서 레거시 엔드포인트가 남아 있지 않습니다.

FAQ

Assistants API 종료가 ChatGPT의 모든 Assistant를 뜻하나요?
이 글은 OpenAI API의 Assistants·Threads·Runs 통합을 다룹니다. ChatGPT 제품 기능이나 다른 API 전체가 함께 종료된다는 뜻으로 확대하면 안 됩니다.

기존 assistant_id를 Responses API에 그대로 넣을 수 있나요?
아닙니다. 기존 Assistant 구성은 Prompt로 옮기고, Thread·Run 흐름도 Conversation·Response 구조에 맞춰 다시 구현해야 합니다.

기존 Thread의 모든 메시지를 새 Conversation으로 옮겨야 하나요?
서비스의 보존 정책과 필요한 맥락에 따라 다릅니다. 도구 결과 누락과 과도한 개인정보·토큰 보존을 함께 고려해 읽기 전용 보관, 요약 이전, 선별 이전 중 하나를 정하십시오.

Azure OpenAI도 Responses API로만 옮기면 되나요?
Azure OpenAI Assistants는 Microsoft Foundry Agents라는 별도 권장 경로가 있습니다. 실제 엔드포인트와 사용 중인 서비스 세대를 확인한 뒤 Microsoft 가이드를 따르십시오.