Assistants API가 사라졌습니다. 지금 에이전트를 구축하는 방법

OpenAI Assistants API는 2026년 8월 26일부로 공식 폐지되었습니다. 이러한 지원 중단은 우리가 상태를 유지하는(stateful) 에이전트를 구축하는 방식에 근본적인 변화를 강요합니다. 관리되는 영구 스레드 모델에서 새로운 Responses 및 Conversations API를 사용한 보다 직접적이고 무상태(stateless) 접근 방식으로 전환해야 합니다. 이 변경 사항은 스택의 일부 부분을 단순화하지만, 상태 관리에 대한 책임은 개발자인 여러분에게 다시 전적으로 돌아옵니다.

무엇이 바뀌었나: Assistants에서 Responses로

기존 Assistants API는 대화형 AI를 구축하는 복잡성을 추상화하려는 시도였습니다. 이는 영구적인 "스레드(threads)"가 있는 상태 유지 환경을 제공하여, 개발자가 대화 기록을 직접 관리할 필요 없이 장기간의 상호작용에서 컨텍스트를 유지할 수 있는 에이전트를 구축할 수 있게 했습니다. 또한 Code Interpreter와 검색 시스템 같은 강력한 도구들을 묶어 제공했습니다.

하지만 이러한 추상화는 트레이드오프(trade-offs)를 가져왔습니다. API가 다소 투박하게 느껴질 수 있었고, 상태 유지적 특성 때문에 전체 대화 스레드가 매 턴마다 재처리될 수 있어 예측하기 어려운 비용이 발생했습니다. 성능 또한 문제가 되었는데, 개발자는 실시간 스트림을 사용하는 대신 업데이트를 폴링(poll)해야 했습니다.

Responses API를 중심으로 하는 새로운 모델은 보다 원시적이고 무상태적인 패러다임으로의 회귀입니다. 핵심 아이디어는 직접적인 요청/응답 흐름입니다. 영구 스레드는 여러분이 생성하고 관리해야 하는 Conversation 객체로 대체됩니다. 턴(turn) 간 컨텍스트를 유지하는 책임은 이제 애플리케이션 코드에 있습니다. 이는 중대한 아키텍처 변화이지만, 더 많은 제어력, 향상된 성능, 그리고 더욱 예측 가능한 비용을 제공합니다.

RAG의 새로운 핵심: file_search

검색 증강 생성(Retrieval-Augmented Generation, RAG) 시스템을 구축하는 개발자에게 가장 중요한 변화는 Responses API 내에 file_search 도구가 도입되었다는 점입니다. 이것은 기존의 Retrieval 도구의 후속작이며, 이제 모델이 여러분의 사설 문서에서 지식을 접근하는 표준 방식입니다.

워크플로우는 간단합니다. vector_store를 생성하고 파일을 여기에 업로드하면, OpenAI 백엔드가 청킹(chunking), 임베딩(embedding), 인덱싱(indexing) 전체 파이프라인을 처리합니다. 더 이상 자체적인 임베딩 및 검색 로직을 구축하고 관리할 필요가 없습니다.

Responses API를 호출할 때 file_search 도구를 사용할 수 있게 됩니다. 그러면 모델은 사용자의 질의에 따라 언제 이를 사용할지 지능적으로 결정합니다. 이는 벡터 스토어(vector store)에 대해 의미론적 검색(semantic search)을 수행하고, 가장 관련성 높은 구절들을 검색하여 인용문과 함께 응답에 통합합니다.

특정 벡터 스토어에 대한 도구를 활성화하는 Python의 API 호출이 어떻게 생겼는지 개념적으로 살펴보겠습니다:

from openai import OpenAI
client = OpenAI()

...

얻는 것과 잃는 것

이번 마이그레이션으로 얻는 주요 이점은 통제권입니다. 상태 비저장(stateless) API로의 전환은 대화 기록 및 상태 관리에 대한 직접적인 권한을 부여합니다. 이는 더 예측 가능한 성능과 비용을 의미하며, 더 이상 이전의 영구 스레드 시스템(persistent-thread system)이라는 블랙박스에 종속되지 않습니다. Responses API는 또한 복잡한 워크플로우를 단일 API 호출로 통합하여 전체 상호 작용 모델을 단순화합니다.

가장 큰 손실은 편리성입니다. 관리되는 무한 컨텍스트 스레드(managed, infinite-context thread)의 지원이 사라졌습니다. 만약 귀하의 애플리케이션이 OpenAI가 상태를 관리할 것이라는 가정 하에 설계되었다면, 이제는 상당한 마이그레이션 프로젝트가 남아 있습니다. OpenAI는 이전의 Threads를 새로운 Conversations로 마이그레이션하는 자동화된 도구를 제공하지 않습니다.

관리형 file_search 도구에는 중요한 기술적 트레이드오프가 있습니다. 이 도구는 RAG 파이프라인을 구축해야 하는 부담을 덜어주지만, 동시에 청킹(chunking) 전략에 대한 제어권도 빼앗아갑니다. 고도로 구조화되었거나 복잡한 문서의 경우, 자동화된 청킹 방식이 최적이지 않을 수 있으며, 이는 검색 품질에 영향을 미칠 수 있습니다. 따라서 이 내장 도구를 사용할지 아니면 자체 검색 시스템을 구축할지 결정할 때 인지해야 할 중요한 제한점입니다.

최종 정리

이러한 변화는 AI 개발 스택의 성숙도를 보여줍니다. 초기에는 매우 추상화되어 제공되던 Assistants API가 더 강력하고 원시적인 빌딩 블록으로 대체되었습니다. 이는 '마법 상자'를 제공하는 방식에서 벗어나, 엔지니어들에게 RAG 및 에이전트 시스템의 핵심 구성 요소에 대한 직접적인 접근 권한을 부여하는 방향으로 나아가고 있습니다. 개발자들에게 이것은 더 많은 책임감을 의미하지만, 동시에 더 큰 힘을 의미합니다. 완전히 관리되는(fully managed) 에이전트 시대는 끝났으며, 자체적으로 구축하는 시대가 도래했습니다.

출처

• Assistants 마이그레이션 가이드 | OpenAI API
• File search | OpenAI API