OpenAI Assistants API 8월 26일 종료, Responses API 마이그레이션 완전 정리

 

지난해 8월 OpenAI가 Assistants API 종료를 예고했을 때 많은 팀이 "1년이나 있으니 나중에 하면 되지"라고 생각했을 겁니다. 그런데 2026년 6월 26일 기준으로 남은 시간이 두 달도 안 됩니다. 8월 26일이 되면 /v1/assistants, /v1/threads 관련 엔드포인트가 전부 응답을 멈춥니다. 연장은 없다는 게 OpenAI 공식 입장이고, Azure OpenAI도 같은 날짜에 함께 종료됩니다. Zapier에서 Assistants API 기반 스텝을 쓰고 있는 워크플로우도 그날부터 멈춥니다. 이 글에서는 뭐가 어떻게 바뀌는지, 그리고 실제로 어떻게 옮겨야 하는지를 정리합니다.

---

왜 없애는 건가

Assistants API는 원래 에이전트를 만들기 전 시대, 즉 추론 모델이 나오기 전에 설계된 구조입니다. OpenAI가 공식적으로 밝힌 표현이 "에이전트 구축에 대한 우리의 초기 시도(Assistants were our early take on how agents could be built)"입니다. 당시에는 어시스턴트 객체를 API로 만들고, 스레드를 생성하고, 런을 돌리는 3단 구조가 그나마 합리적이었지만 GPT-5 계열 추론 모델이 나오면서 이 구조가 오히려 걸림돌이 됐습니다.

추론 모델은 내부 추론 과정을 클라이언트에 노출하지 않는 방식으로 동작하는데, Assistants API의 런/런스텝 구조와 잘 안 맞습니다. Responses API는 이 문제를 처음부터 고려해서 설계됐습니다. 입력 아이템을 넣으면 출력 아이템이 나오는 단순한 구조이고, 추론 스텝, 함수 호출, 도구 결과가 전부 같은 아이템 배열 안에서 처리됩니다.

---

개념 매핑 — 뭐가 뭐로 바뀌나

Assistants API와 Responses API의 개념이 1:1로 대응하지 않기 때문에 이 부분을 먼저 이해해야 합니다.

Assistants API의 어시스턴트(Assistant) 객체는 Responses API의 **프롬프트(Prompt)**로 대응됩니다. 가장 큰 차이는 어시스턴트는 API로 생성하고 관리할 수 있었지만, 프롬프트는 대시보드에서만 만들 수 있습니다. API로 프롬프트를 동적으로 생성하는 패턴은 더 이상 지원하지 않습니다.

**스레드(Thread)**는 **컨버세이션(Conversation)**으로 바뀝니다. 기존 스레드를 자동으로 컨버세이션으로 옮겨주는 마이그레이션 툴은 없습니다. OpenAI가 권장하는 방식은 기존 유저의 신규 대화는 컨버세이션으로 시작하고, 이전 스레드는 필요한 경우에만 수동으로 백필하는 것입니다.

**런(Run)**은 **응답(Response)**으로 대응됩니다. 기존 런은 비동기 폴링 방식이었는데, 응답은 동기 또는 스트리밍으로 처리합니다. 복잡한 폴링 루프가 필요 없어집니다.

**런스텝(Run Step)**은 **아이템(Item)**으로 바뀝니다. 응답 안에 들어있는 구조화된 단위로, 메시지, 추론, 함수 호출, 함수 결과가 전부 아이템 타입으로 표현됩니다.

---

코드 비교 — 실제로 어떻게 달라지나

어시스턴트 생성과 대화 실행의 기본 흐름을 비교하면 차이가 명확하게 보입니다.

Assistants API 방식 (Python)

from openai import OpenAI
import time

client = OpenAI()

# 1. 어시스턴트 생성
assistant = client.beta.assistants.create(
    model="gpt-5.5",
    name="코드 리뷰어",
    instructions="당신은 Python 코드를 리뷰하는 전문가입니다.",
    tools=[{"type": "code_interpreter"}]
)

# 2. 스레드 생성
thread = client.beta.threads.create()

# 3. 메시지 추가
client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="이 함수의 시간 복잡도를 분석해줘: def find(arr, x): return x in arr"
)

# 4. 런 생성 및 완료 대기 (폴링)
run = client.beta.threads.runs.create(
    thread_id=thread.id,
    assistant_id=assistant.id
)

while run.status != "completed":
    time.sleep(1)
    run = client.beta.threads.runs.retrieve(
        thread_id=thread.id,
        run_id=run.id
    )

# 5. 결과 조회
messages = client.beta.threads.messages.list(thread_id=thread.id)
print(messages.data[0].content[0].text.value)

이 코드에서 어시스턴트 생성, 스레드 생성, 메시지 추가, 런 생성, 폴링, 결과 조회까지 6단계가 필요합니다. 비동기 폴링 때문에 코드가 복잡하고 에러 처리도 까다롭습니다.

Responses API 방식 (Python)

from openai import OpenAI

client = OpenAI()

# 컨버세이션 생성 (선택적 — 상태 유지가 필요한 경우)
conversation = client.conversations.create()

# 단일 API 호출로 응답 획득
response = client.responses.create(
    model="gpt-5.5",
    instructions="당신은 Python 코드를 리뷰하는 전문가입니다.",
    input="이 함수의 시간 복잡도를 분석해줘: def find(arr, x): return x in arr",
    conversation_id=conversation.id,  # 대화 이어가려면 추가
    tools=[{"type": "code_interpreter"}]
)

print(response.output_text)

폴링이 사라지고 단일 호출로 끝납니다. 어시스턴트 객체를 미리 만들 필요 없이 instructions 파라미터로 바로 시스템 프롬프트를 넣을 수 있습니다.

멀티턴 대화를 이어가는 패턴도 바뀝니다.

# 이전 응답을 이어서 대화하는 패턴
response2 = client.responses.create(
    model="gpt-5.5",
    instructions="당신은 Python 코드를 리뷰하는 전문가입니다.",
    input="그럼 O(1)로 만들려면 어떻게 해야 해?",
    conversation_id=conversation.id  # 같은 컨버세이션 ID로 이어감
)

print(response2.output_text)

---

파일 검색과 Code Interpreter 마이그레이션

Assistants API에서 많이 쓰이던 두 도구의 마이그레이션 패턴입니다.

**파일 검색(File Search)**은 Responses API에서도 벡터 스토어 기반으로 동일하게 작동합니다. 기존 벡터 스토어 ID를 그대로 재사용할 수 있습니다.

# 기존 벡터 스토어 ID를 그대로 사용
response = client.responses.create(
    model="gpt-5.5",
    input="우리 환불 정책이 어떻게 돼?",
    tools=[{
        "type": "file_search",
        "vector_store_ids": ["vs_기존_ID"],
        "max_num_results": 5
    }]
)

Code Interpreter는 이전과 거의 동일하게 작동합니다.

response = client.responses.create(
    model="gpt-5.5",
    input="첨부된 CSV에서 월별 매출 추이를 분석하고 그래프로 그려줘",
    tools=[{"type": "code_interpreter"}],
    # 파일은 input 배열에 아이템으로 포함
    input=[
        {"type": "text", "text": "첨부된 CSV에서 월별 매출 추이를 분석하고 그래프로 그려줘"},
        {"type": "input_file", "file_id": "file-abc123"}
    ]
)

주의할 비용 변화가 있습니다. 파일 검색 스토리지는 첫 1GB 무료 이후 GB당 하루 $0.10이 청구됩니다. 도구 호출은 1,000회당 $2.50입니다. 기존 Assistants API에서 파일을 많이 쓰고 있었다면 비용 시뮬레이션을 먼저 해보는 게 좋습니다.

---

Function Calling 마이그레이션

함수 호출 패턴도 바뀌지만 개념 자체는 동일합니다. Assistants API에서는 런이 requires_action 상태가 되면 폴링해서 감지하고 결과를 제출하는 방식이었는데, Responses API에서는 출력 아이템에서 함수 호출을 감지하고 다음 요청에 결과를 넣는 방식으로 바뀝니다.

import json

# 첫 번째 응답에서 함수 호출 감지
response = client.responses.create(
    model="gpt-5.5",
    input="서울 날씨 어때?",
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "특정 도시의 현재 날씨를 가져옵니다",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "도시 이름"}
                },
                "required": ["city"]
            }
        }
    }]
)

# 출력 아이템에서 함수 호출 찾기
for item in response.output:
    if item.type == "function_call":
        # 실제 함수 실행
        result = get_weather(json.loads(item.arguments)["city"])

        # 함수 결과를 포함해서 다음 요청
        final_response = client.responses.create(
            model="gpt-5.5",
            input=[
                *response.output,  # 이전 출력 포함
                {
                    "type": "function_call_output",
                    "call_id": item.call_id,
                    "output": json.dumps(result)
                }
            ]
        )
        print(final_response.output_text)

---

마이그레이션 우선순위와 타임라인

두 달 남은 시간에 어떻게 움직여야 하는지 단계별로 정리하면 이렇습니다.

지금 당장 해야 할 일은 현재 코드베이스에서 openai.beta.assistants, openai.beta.threads, openai.beta.threads.runs를 쓰는 부분을 전부 파악하는 겁니다. 영향 범위가 어느 정도인지 먼저 확인해야 우선순위를 잡을 수 있습니다.

7월 중에는 Responses API로 핵심 플로우 하나를 먼저 포팅하고 프로덕션 트래픽 일부를 새 코드로 라우팅해서 동작을 비교해야 합니다. 특히 파일 검색 결과 품질과 함수 호출 성공률을 Assistants API 버전과 나란히 모니터링하는 것이 중요합니다.

8월 첫 2주 안에 전체 트래픽 전환을 완료하고 최소 1주일 이상 새 코드만으로 운영하면서 안정성을 확인해야 합니다. 8월 26일 직전에 전환하는 건 너무 늦습니다.

Azure를 쓰고 있다면 마이그레이션 경로가 다릅니다. Azure OpenAI Assistants API는 같은 날 종료되지만 이전 대상은 Responses API가 아니라 Microsoft Foundry Agent Service입니다. Foundry Agent Service가 내부적으로 Responses API 위에서 동작하긴 하지만 엔드포인트와 SDK가 다르므로 별도 검토가 필요합니다.

---

마무리

Responses API로의 전환은 엔드포인트 교체가 아니라 아키텍처 변경입니다. 어시스턴트→프롬프트, 스레드→컨버세이션, 런→응답 개념 변화를 이해하고 나면 코드 자체는 오히려 단순해집니다. 비동기 폴링이 사라지고 단일 호출로 정리되는 부분은 솔직히 개선입니다. 8월 26일이 생각보다 빠르게 옵니다. 지금 바로 영향받는 코드 범위부터 파악하는 게 먼저입니다.