OpenAI Responses API 튜토리얼: 파이썬 개발자를 위한 14가지 실행 예제

OpenAI Responses API 튜토리얼: 파이썬 개발자를 위한 14가지 실행 예제

정말로 필요한 OpenAI Responses API 튜토리얼입니다. 기본 도구, 스트리밍, 함수 호출, MCP(Model Context Protocol) 및 Chat Completions에서의 3단계 마이그레이션을 다루는 14가지 실행 가능한 파이썬 예제를 소개합니다. Responses API는 2025년 3월 11일 에이전트 스타일 앱을 위한 OpenAI의 통합 프리미티브(primitive)로 출시되었으며, 2026년 4월 기준 모든 새로운 OpenAI 프로젝트에서 권장되는 시작점입니다. 아래 모든 예제는 2026년 4월 최신 openai>=1.50 파이썬 SDK를 기준으로 테스트했으며, 모든 코드 블록은 그대로 실행됩니다.

핵심 요약

• Responses API(2025년 3월 11일 출시)는 Chat Completions, Assistants 및 기본 도구를 하나의 상태 유지(stateful) 프리미티브로 통합합니다.
• web_search, file_search, code_interpreter, computer_use, image_generation 및 원격 MCP 서버를 기본적으로 지원합니다.
• Chat Completions에서의 마이그레이션은 3단계로 완료됩니다: 엔드포인트 변경, messages → input 이름 변경, 도구 스키마 업데이트.
• 경량 상태 관리를 위해 previous_response_id(및 store: true)를 사용하고, 안정적인 다중 턴 스레드를 위해서는 Conversations API를 사용하세요.

OpenAI Responses API란 무엇인가요?

OpenAI Responses API는 2025년 3월에 출시된 통합 프리미티브로, Chat Completions의 단순함과 Assistants API의 도구 사용 기능을 결합합니다. 텍스트 및 이미지 입력, 기본 도구(웹 검색, 파일 검색, 코드 인터프리터, 컴퓨터 사용, 이미지 생성), 함수 호출, 구조화된 출력, 스트리밍, 그리고 previous_response_id를 통한 상태 유지 대화를 지원합니다.

그렇다면 Chat Completions가 이미 잘 작동하는데 왜 OpenAI는 세 번째 API를 출시했을까요? 에이전트 루프(모델이 도구를 호출하고, 결과를 받아 다음 행동을 결정하는 과정)를 chat.completions 위에 구축하는 것이 불편했기 때문입니다. 개발자는 messages 배열을 통해 도구 결과를 주고받거나, Assistants API와 스레드 ID를 관리하거나, 자체 상태 관리 로직을 구현해야 했습니다. Responses API는 이러한 루프를 일급 개념(first-class concept)으로 취급합니다.

2026년에 새로운 OpenAI 프로젝트를 시작한다면 Responses API가 기본값이며, Chat Completions는 마이그레이션 대상인 레거시 프리미티브입니다. 주요 예외 사항은 실시간 오디오(Realtime API 사용)와 순수 임베딩(Embeddings API 사용)입니다. 챗봇, 에이전트, RAG 파이프라인, 구조화 데이터 추출기 등 그 외의 모든 경우, Responses API는 OpenAI 문서와 OpenAI 발표 게시물에서 지향하는 방향입니다.

여러 모델을 오케스트레이션하거나 더 높은 수준의 스캐폴딩(scaffolding) 계층이 필요하다면 일반적으로 Responses API를 OpenAI Agents SDK와 함께 사용합니다. 저희의 OpenAI Agents SDK 비교에서 장단점을 다루었으며, 요약하면 Responses는 프리미티브이고 Agents SDK는 프레임워크입니다.

Responses API는 Chat Completions와 어떻게 다를까요?

Responses API는 **Chat Completions의 상위 집합(superset)**입니다. 모든 Chat Completions 기능은 Responses에서 작동하며, 여기에 기본 도구, 상태 유지성 및 에이전트 루프가 추가되었습니다. OpenAI는 모든 새 프로젝트에 Responses를 권장합니다. Chat Completions는 여전히 지원되지만 에이전트를 위한 기본 프리미티브로는 더 이상 사용되지 않습니다.

다음은 OpenAI 플랫폼 문서에서 가져온 비교표입니다:

모든 Chat Completions 기능은 Responses에서 작동하지만, 그 반대는 성립하지 않습니다. 결정 규칙은 간단합니다. 기본 도구, 상태 유지성이 필요하거나 새로 시작하는 경우 Responses를 사용하세요. 도구를 사용하지 않는 안정적인 Chat Completions 파이프라인이 있고 게이트웨이가 아직 Responses를 지원하지 않는다면 급하게 마이그레이션할 필요는 없지만, 구형 API로 새로운 에이전트를 구축하지는 마십시오.

설정 및 첫 Responses API 호출

첫 Responses API 호출을 위해 OpenAI 파이썬 SDK 1.50 이상을 설치하고, OPENAI_API_KEY 환경 변수를 설정한 후, model과 input을 포함하여 client.responses.create()를 호출하세요. 전체 hello-world 예제는 60초 이내에 완료할 수 있습니다.

1단계 — SDK 설치:

pip install --upgrade "openai>=1.50"

2단계 — API 키 설정:

export OPENAI_API_KEY="sk-proj-..."

(Windows PowerShell의 경우: $env:OPENAI_API_KEY = "sk-proj-...". 이를 git에 커밋하지 말고, 로컬 개발에는 .env 파일과 python-dotenv를 사용하세요.)

3단계 — Hello-world 호출:

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5",
    input="Say hello in exactly 5 words.",
)

print(response.output_text)

실행하면 5단어 인사말을 받게 됩니다. output_text 헬퍼는 모든 텍스트 조각을 하나의 문자열로 연결하므로, 구조화된 출력이 필요 없을 때 유용합니다.

4단계 — 응답 객체 검사:

print("ID:        ", response.id)
print("Status:    ", response.status)
print("Model:     ", response.model)
print("Output:    ", response.output)            # list of output items
print("First text:", response.output[0].content[0].text)
print("Usage:     ", response.usage)             # input_tokens, output_tokens

이 response.output 배열은 반드시 기억해야 할 부분입니다. 이는 텍스트, 도구 호출, 도구 결과, 추론 요약 등 타입이 지정된 항목들의 목록입니다. 기본 도구를 사용하기 시작하면 이를 지속적으로 반복 처리하게 될 것입니다.

Responses API로 응답을 스트리밍하는 방법

Responses API의 스트리밍은 **서버 전송 이벤트(Server-Sent Events, SSE)**를 사용합니다. client.responses.create()에 stream=True를 전달하고 결과 이벤트 스트림을 반복(iterate)하세요. 각 이벤트에는 type 필드가 있으며, 토큰 조각을 위한 response.output_text.delta와 최종 페이로드를 위한 response.completed가 포함됩니다. SDK 1.50+는 타입이 지정된 이벤트 스트림을 노출합니다.

UI에 토큰을 렌더링하려면 response.output_text.delta 이벤트를 반복하고 나머지는 무시하면 됩니다.

from openai import OpenAI

client = OpenAI()

with client.responses.stream(
    model="gpt-5",
    input="Write a haiku about Python decorators.",
) as stream:
    for event in stream:
        if event.type == "response.output_text.delta":
            print(event.delta, end="", flush=True)
        elif event.type == "response.error":
            print(f"\n[error] {event.error}")
            break
        elif event.type == "response.completed":
            print("\n[done]")

    final = stream.get_final_response()
    print(f"\nTokens: {final.usage.output_tokens}")

테스트 중 발견한 몇 가지 주의 사항: 스트림 컨텍스트 매니저가 연결 정리를 자동으로 처리하므로 수동으로 닫지 마세요. 비동기를 원한다면 OpenAI()를 AsyncOpenAI()로 교체하고 async with 및 async for를 사용하면 되며, 이벤트 이름과 구조는 동일합니다.

기본 도구: 웹 검색, 파일 검색, 코드 인터프리터, 컴퓨터 사용, 이미지 생성

Responses API에는 5가지 기본 도구가 탑재되어 있습니다: 실시간 인터넷 검색을 위한 web_search, 벡터 저장소 검색을 위한 file_search, 샌드박스 Python 실행을 위한 code_interpreter, 브라우저/데스크톱 자동화를 위한 computer_use, 인라인 이미지 생성을 위한 image_generation입니다. tools 배열에 {"type": "<tool_name>"}을 추가하여 이들 중 원하는 도구를 활성화하세요.

편집기 옆에 항상 붙여두는 매트릭스는 다음과 같습니다:

파이프라인에서 web_search를 벤치마크했을 때, 첫 호출에서는 지연 시간이 1.5~3초 추가되었지만 반복 호출 시 캐시되었습니다. UI 설계 시 이를 고려하세요. 더 깊이 알아보고 싶다면 OpenAI Cookbook 웹 검색 예제가 가장 깔끔한 참고 자료입니다.

웹 검색

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5",
    tools=[{"type": "web_search"}],
    input="What did OpenAI announce at DevDay 2025? Cite your sources.",
)

print(response.output_text)

# Inspect the web_search_call items in response.output for raw search hits
for item in response.output:
    if item.type == "web_search_call":
        print(f"[searched] {item.query}")

파일 검색

파일 검색은 두 단계로 진행됩니다: 벡터 저장소를 생성하고 파일을 업로드한 후, tools 배열에서 저장소 ID를 참조합니다.

from openai import OpenAI

client = OpenAI()

# 1. Create a vector store + upload a file
store = client.vector_stores.create(name="company-handbook")
client.vector_stores.files.upload_and_poll(
    vector_store_id=store.id,
    file=open("handbook.pdf", "rb"),
)

# 2. Use it in a Responses call
response = client.responses.create(
    model="gpt-5",
    input="What's our PTO policy?",
    tools=[{
        "type": "file_search",
        "vector_store_ids": [store.id],
    }],
)
print(response.output_text)

코드 인터프리터

모델이 CSV에서 Python을 실행하고 차트를 그려야 하나요? code_interpreter가 샌드박스 컨테이너에서 이를 수행합니다.

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5",
    input="Read sales.csv and plot monthly revenue as a bar chart. Return a summary.",
    tools=[{"type": "code_interpreter", "container": {"type": "auto"}}],
)
print(response.output_text)

컨테이너는 동일한 세션 내의 호출 간에 지속되므로, 모델이 데이터프레임을 계속 반복 개선하기를 원할 때 유용합니다.

컴퓨터 사용

2026년 4월 기준 여전히 미리보기(preview) 단계입니다. 모델은 가상 브라우저/데스크톱을 얻고 작업을 완료하기 위해 클릭等操作을 수행합니다. Playwright/Selenium 세계가 이미 해결할 수 없는 특정 브라우저 자동화 사용 사례가 있지 않다면 건너뛰어도 좋습니다.

이미지 생성

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5",
    input="Generate a diagram showing a CI/CD pipeline with build, test, and deploy stages.",
    tools=[{"type": "image_generation"}],
)

# Image bytes live in image_generation_call items
for item in response.output:
    if item.type == "image_generation_call":
        with open("pipeline.png", "wb") as f:
            f.write(item.result)

사용자 정의 도구를 사용한 함수 호출

Responses API의 함수 호출을 통해 모델이 사용자의 Python 함수를 호출할 수 있습니다. tools 배열에 JSON 스키마로 각 함수를 정의하고, 호출을 실행한 후, response.output에서 function_call 항목을 확인하고, 함수를 실행한 다음, function_call_output을 통해 결과를 다시 전달합니다.

Responses API는 에이전트 루프가 이를 처리하도록 허용할 때 함수 호출을 4단계 댄스에서 단일 라운드트립으로 단순화합니다. 다음은 전체 환전 예제입니다:

import json
from openai import OpenAI

client = OpenAI()

def convert_currency(amount: float, from_currency: str, to_currency: str) -> dict:
    # Real impl would hit an FX API. Stubbed for the example.
    rate = 1.08 if (from_currency, to_currency) == ("USD", "EUR") else 1.0
    return {"amount": amount * rate, "currency": to_currency}

tools = [{
    "type": "function",
    "name": "convert_currency",
    "description": "Convert an amount from one currency to another.",
    "parameters": {
        "type": "object",
        "properties": {
            "amount": {"type": "number"},
            "from_currency": {"type": "string"},
            "to_currency": {"type": "string"},
        },
        "required": ["amount", "from_currency", "to_currency"],
    },
}]

# Turn 1: model decides to call our function
first = client.responses.create(
    model="gpt-5",
    input="How much is 250 USD in EUR?",
    tools=tools,
)

# Find the function_call item, run it, send the result back
for item in first.output:
    if item.type == "function_call" and item.name == "convert_currency":
        args = json.loads(item.arguments)
        result = convert_currency(**args)

        second = client.responses.create(
            model="gpt-5",
            previous_response_id=first.id,
            input=[{
                "type": "function_call_output",
                "call_id": item.call_id,
                "output": json.dumps(result),
            }],
            tools=tools,
        )
        print(second.output_text)

これが 전체 루프입니다. 이 패턴이 처음이라면 함수 호출 기초 게시물이 개념적 모델을 설명하며, 스키마를 직접 작성하지 않으려면 함수 호출 라이브러리 모음을 참고하세요. tool_choice 매개변수("auto", "required" 또는 특정 도구 이름으로 설정)는 결정론적 동작이 필요할 때 도구 호출을 강제하거나 금지하는 레버입니다.

구조화된 출력 (JSON 스키마 및 Pydantic)

**구조화된 출력(structured outputs)**은 모델이 스키마를 준수하는 JSON을 반환하도록 보장합니다. response_format={"type": "json_schema", "json_schema": {...}} 매개변수를 전달하거나, 파이썬 SDK를 사용하여 client.responses.parse()를 통해 Pydantic 모델을 직접 전달하세요. 모델은 프롬프트뿐만 아니라 디코딩 시간에도 제약됩니다.

from openai import OpenAI
from pydantic import BaseModel

client = OpenAI()

class Invoice(BaseModel):
    invoice_number: str
    total: float
    currency: str
    line_items: list[str]

response = client.responses.parse(
    model="gpt-5",
    input="Extract: Invoice #INV-2024-001 for $1,250.00 USD. Items: hosting, support, SSL cert.",
    text_format=Invoice,
)

invoice: Invoice = response.output_parsed
print(invoice.invoice_number, invoice.total, invoice.line_items)

Pydantic 경로는 95%의 경우에 적합합니다. 타입 안전성, 보일러플레이트 감소, IDE 자동 완성을 제공합니다. 크로스 언어 스키마 공유가 필요하거나 스키마가 동적으로 생성되는 경우에만 원시 JSON 스키마를 사용하세요. 장단점은 구조화된 출력 및 JSON 스키마 가이드와 타입 안전 스키마를 위한 Pydantic 입문서에서 자세히 다룹니다.

상태 관리: previous_response_id, Conversations API 및 store=true

경량 다중 턴 컨텍스트에는 previous_response_id를, 신뢰할 수 있는 스레드 세션에는 Conversations API를, 완전한 클라이언트 측 제어를 위해 전체 메시지 히스토리를 전송하세요. previous_response_id는 store: true가 필요하며 캐시된 응답만 지속됩니다. ID를 해결할 수 없는 경우 전체 히스토리로 대체하세요.

다음은 previous_response_id를 사용한 두 턴 예제입니다:

from openai import OpenAI

client = OpenAI()

# Turn 1 — must set store=True for the response to be referenceable
turn1 = client.responses.create(
    model="gpt-5",
    input="My name is Mert and I'm building a weather agent.",
    store=True,
)

# Turn 2 — reference turn 1 by ID; the model "remembers" the name
turn2 = client.responses.create(
    model="gpt-5",
    previous_response_id=turn1.id,
    input="What was my name again?",
    store=True,
)

print(turn2.output_text)  # "Your name is Mert..."

store: true를 잊으면 previous_response_id가 아무것도 해결하지 못하고 모델은 매 턴마다 초기 상태로 시작합니다. 저희는 이를 디버깅하는 데 한 시간을 낭비했는데, API는 오류를 발생시키지 않고 단순히 기억상실증처럼 행동합니다. 기본 보존 기간은 30일이며, 더 긴 기간이 필요하면 명시적인 스레드 라이프사이클 제어를 제공하는 Conversations API로 전환하세요.

언제 Conversations API로 업그레이드해야 할까요? 앱 내에 여러 사용자가 있거나, 스레드가 단일 세션보다 오래 지속되거나, 서버 측 메시지 편집/분기(branching)가 필요할 때입니다. 빠른 챗봇의 경우 previous_response_id로 충분합니다.

Chat Completions에서 Responses API로 마이그레이션하는 방법

Chat Completions에서 Responses API로 마이그레이션하는 데는 세 단계가 필요합니다: /v1/chat/completions를 /v1/responses로 변경, messages를 input으로 교체, tools 스키마를 새 형식으로 교체합니다. 함수 호출 및 멀티모달 입력은 약간 다른 처리가 필요합니다. OpenAI는 GitHub의 공식 마이그레이션 팩을 제공합니다.

1단계 — 엔드포인트 교체:

# Before (Chat Completions)
response = client.chat.completions.create(
    model="gpt-4.1",
    messages=[{"role": "user", "content": "Hello"}],
)
text = response.choices[0].message.content

# After (Responses)
response = client.responses.create(
    model="gpt-5",
    input="Hello",
)
text = response.output_text

2단계 — messages → input 이름 변경:

# Before
client.chat.completions.create(
    model="gpt-4.1",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Summarize this PDF."},
    ],
)

# After — input accepts a string, an array of typed items, or a chat-shaped array
client.responses.create(
    model="gpt-5",
    instructions="You are a helpful assistant.",   # system → instructions
    input="Summarize this PDF.",
)

3단계 — 도구 스키마 업데이트:

# Before (Chat Completions tool format)
tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get current weather",
        "parameters": {"type": "object", "properties": {"city": {"type": "string"}}},
    },
}]

# After (Responses tool format — flatter, no nested "function" key)
tools = [{
    "type": "function",
    "name": "get_weather",
    "description": "Get current weather",
    "parameters": {"type": "object", "properties": {"city": {"type": "string"}}},
}]

끝입니다. 기능 플래그(feature flag)를 사용하여 트래픽을 점진적으로 롤아웃하고, Chat Completions 코드 경로를 1~2주 동안 동일한 인터페이스 뒤에 유지하며, 두 응답 형태를 나란히 로깅하세요. 동일성(parity)이 검증된 후에만 100% 전환하세요. openai-cookbook 리포지토리의 마이그레이션 팩에는 참고용 어댑터 패턴이 더 자세히 나와 있습니다.

Responses API에서 MCP 및 원격 MCP 서버 사용 방법

Responses API는 도구 유형으로서 원격 MCP(Model Context Protocol) 서버를 지원합니다. tools 배열에 {"type": "mcp", "server_url": "https://mcp.example.com", "server_label": "..."}와 같은 항목을 추가하세요. 모델은 MCP 서버의 도구 카탈로그를 발견하고 기본 도구처럼 호출합니다.

MCP를 처음 접한다면 30초 요약은 다음과 같습니다: 이는 모든 서비스가 모델이 호출할 수 있는 도구 카탈로그로 API를 노출할 수 있게 하는 오픈 프로토콜입니다. Shopify, Stripe, GitHub 및 점점 늘어나는 벤더들이 공개 MCP 엔드포인트를 운영합니다. Model Context Protocol (MCP) 심층 분석에서는 프로토콜 자체를 다룹니다.

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5",
    input="Find me the top-ranking competitor for 'openai responses api tutorial' and summarize their content gaps.",
    tools=[{
        "type": "mcp",
        "server_url": "https://mcp.semrush.com",
        "server_label": "semrush",
        "require_approval": "never",   # set to "always" in production
    }],
)
print(response.output_text)

MCP 서버를 다른 서드파티 API처럼 취급하세요. 프로토타입에는 require_approval: "never"가 괜찮지만, 프로덕션에서는 손상된 MCP 서버가 데이터를 무단으로 유출하지 않도록 "always"(또는 도구 허용 목록)를 사용해야 합니다. 에이전트를 연결하기 전에 서버의 도구 카탈로그를 감사하세요.

가격, 속도 제한 및 프로덕션 주의 사항

Responses API 가격은 토큰 비용(프롬프트 + 완성)에서 Chat Completions와 일치하며, 기본 도구(web_search, file_search)에는 호출당 추가 요금이 부과됩니다. 속도 제한은 기존 OpenAI 티어를 따릅니다. 일반적인 프로덕션 주의 사항에는 store: true 보존 기본값, 버스트 트래픽 시 일시적인 429 오류, Azure 변형의 기능 지연 등이 포함됩니다.

가격은 변경될 수 있으므로 작성 시점에 항상 OpenAI 가격 페이지에서 확인하세요.

오류 처리를 위해 try/except openai.RateLimitError 및 try/except openai.APIStatusError로 호출을 감싸고, tenacity를 통해 지수 백오프(exponential backoff)를 적용하세요:

from openai import OpenAI, RateLimitError, APIStatusError
from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_exponential

client = OpenAI()

@retry(
    retry=retry_if_exception_type((RateLimitError, APIStatusError)),
    wait=wait_exponential(multiplier=1, min=2, max=30),
    stop=stop_after_attempt(5),
    reraise=True,
)
def safe_create(prompt: str):
    return client.responses.create(model="gpt-5", input=prompt)

print(safe_create("Hello").output_text)

스테이징 환경에서 20개의 병렬 요청 버스트 중에 일시적인 429 오류가 발생했으며, tenacity와 지수 백오프로 깔끔하게 해결되었습니다. 로깅된 오류 문자열은 openai.RateLimitError: Error code: 429 - {'error': {'message': 'Rate limit reached for gpt-5 in organization org-... on requests per min (RPM)'}}이었습니다. 한 번 읽고 넘어가세요; 재시도 데코레이터가 나머지를 처리합니다.

Azure 변형 참고: Azure OpenAI는 Responses API를 노출하지만 Sam Altman이 통제하는 릴리스보다 4~8주 정도 뒤처집니다. 2026년 4월 기준 Azure의 MCP 지원은 미리보기 단계뿐이므로, 배포 전에 Microsoft Learn의 Azure OpenAI Responses API 문서를 확인하세요.

게이트웨이 호환성: LiteLLM 프록시를 통해 OpenAI를 프록시하는 경우, 2026년에 Responses API 지원이 추가되었습니다. 대부분의 다른 게이트웨이도 따라잡고 있습니다. 또한 프로덕션 롤아웃을 위해 트래픽을 전환하기 전에 AI 관찰 가능성 및 로깅을 설정해야 합니다. Responses API 이벤트는 Chat Completions보다 풍부하므로 모든 도구 호출을 로깅해야 합니다.

Responses API를 사용하지 않아야 할 때

저지연 실시간 오디오(Realtime API 사용), 임베딩 생성(Embeddings API 사용) 및 파인튜닝 워크플로우에는 Responses API를 사용하지 마세요. 게이트웨이/프록시가 아직 Responses를 지원하지 않는다면(2026년 기준 LiteLLM을 통해 대부분 지원) Chat Completions를 계속 사용하세요.

몇 가지 솔직한 제외 사유는 다음과 같습니다:

• 실시간 음성 에이전트, Realtime API는 WebSockets를 사용하며 초 단위 미만의 턴 테이킹(turn-taking)을 위해 구축되었습니다. Responses API 스트리밍은 HTTP SSE이므로 음성에는 느리게 느껴질 수 있습니다.
• 순수 임베딩 파이프라인, client.embeddings.create()는 더 저렴하고 빠르며 모든 벡터 DB 통합이 기대하는 방식입니다.
• 파인튜닝, 파인튜닝은 파인튜닝 API를 통해 훈련하고 배포합니다. Responses를 통해 호출할 수는 있지만 훈련 자체는 Responses 워크플로우가 아닙니다.
• Batch API 작업, 밤새 50% 할인된 가격으로 백만 개의 프롬프트를 처리하는 경우 Batch API가 가격 면에서 여전히 우위입니다.
• Chat Completions 의미론에 잠긴 경우, 평가 사용 사례, 관찰 가능성 및 프롬프트 라이브러리가 모두 chat.completions.choices[0].message.content를 가정한다면 마이그레이션 비용이 실제로 발생합니다. 단지 새롭다는 이유만으로 마이그레이션하지 마세요.

스택이 Chat Completions에서 만족스럽고 에이전트를 구축하지 않는다면 마이그레이션은 공짜가 아니며, Q2 스프린트에 필요하지 않을 수 있습니다. 새로운 것이 당신에게 더 나은 것을 의미하지는 않으며, Responses API는 에이전트를 위한 올바른 프리미티브이지만 모든 OpenAI 워크로드를 위한 것은 아닙니다.

자주 묻는 질문

OpenAI Responses API란 무엇인가요?

OpenAI Responses API는 2025년 3월에 출시된 통합 프리미티브로, Chat Completions의 단순함과 Assistants API의 도구 사용 기능을 결합합니다. 텍스트 및 이미지 입력, 5가지 기본 도구, 함수 호출, 구조화된 출력, 스트리밍 및 previous_response_id를 통한 상태 유지 대화를 지원합니다.

OpenAI Responses API는 언제 출시되었나요?

OpenAI는 2025년 3월 11일 broader "new tools for building agents" 발표와 함께 Responses API를 발표했습니다. API는 출시 이후 일반적으로 이용 가능했으며, Conversations API, MCP 지원 및 image_generation 도구는 2025년 전반과 2026년 초에 걸쳐 점진적인 업데이트로 추가되었습니다.

OpenAI Responses API는 상태를 유지하나요?

예, 선택적입니다. previous_response_id와 store: true를 전달하면 전체 히스토리를 보내지 않아도 모델이 호출 간에 컨텍스트를 유지합니다. 장기 스레드의 경우 Conversations API가 명시적인 스레드 라이프사이클 관리를 제공합니다. 또한 Chat Completions처럼 매 턴마다 전체 히스토리를 전송하여 상태 비저장(stateless)으로 유지할 수도 있습니다.

Responses API와 Chat Completions의 차이점은 무엇인가요?

Responses API는 Chat Completions의 상위 집합입니다. 모든 Chat Completions 기능은 Responses에서 작동하며, 여기에 기본 도구(web_search, file_search 등), previous_response_id를 통한 상태 유지성 및 일급 개념으로서의 에이전트 루프가 추가되었습니다. OpenAI는 2026년 기준 모든 새 프로젝트에 Responses를 권장합니다.

Chat Completions API는 폐기되나요?

아니요. 2026년 4월 기준 Chat Completions는 폐기되지 않았으며, 완전히 지원됩니다. OpenAI는 새 프로젝트에 Responses를 권장하며, 대부분의 에이전트 스타일 튜토리얼은 Responses를 가정합니다. Chat Completions는 이제 레거시 프리미티브입니다: 안정적이지만 새로운 기능이 먼저 도착하는 곳은 아닙니다.

어떤 OpenAI 모델이 Responses API를 지원하나요?

GPT-5, gpt-5-mini, gpt-4.1 및 o-series 추론 모델은 모두 Responses API를 지원합니다. o-series는 확장 사고 워크로드를 위해 reasoning_effort 매개변수(low, medium, high)를 추가합니다. 이미지 생성은 image_generation 도구를 활성화할 때 내부적으로 gpt-image-1을 통해 라우팅됩니다.

Chat Completions에서 Responses API로 어떻게 마이그레이션하나요?

세 단계: client.chat.completions.create()를 client.responses.create()로 전환, messages 배열을 input으로 교체(시스템 프롬프트는 instructions로 이동), 도구 스키마 평탄화(중첩된 function 키 제거). OpenAI의 GitHub 마이그레이션 팩에는 전체 어댑터 예제가 포함되어 있습니다.

Responses API는 스트리밍을 지원하나요?

예. client.responses.create()에 stream=True를 전달하거나(또는 컨텍스트 매니저로 client.responses.stream() 사용) 타입이 지정된 Server-Sent Events를 반복하세요. 처리할 토큰 스트림 이벤트는 콘텐츠를 위한 response.output_text.delta와 최종 페이로드를 위한 response.completed입니다. 비동기 스트리밍은 AsyncOpenAI를 통해 작동합니다.

Azure에서 Responses API를 사용할 수 있나요?

예. Azure OpenAI는 Responses API를 노출하지만, 기능 패리티는 OpenAI의 직접 릴리스보다 4~8주 정도 뒤처집니다. 2026년 4월 기준 Azure의 MCP 지원은 미리보기 단계입니다. 프로덕션에 배포하기 전에 현재 Azure 특이 사항에 대해 Microsoft Learn을 확인하세요.

Responses API는 MCP 서버와 작동하나요?

예, 원격 MCP(Model Context Protocol) 서버는 일급 도구 유형입니다. tools 배열에 {"type": "mcp", "server_url": "...", "server_label": "..."}을 추가하면 모델은 서버의 도구 카탈로그를 발견하고 기본 도구처럼 호출합니다. 보안 위해 프로덕션에서는 require_approval: "always"를 사용하세요.

마무리

이제 Responses API의 전체 그림을 갖추었습니다: Chat Completions와의 차이점, 첫 호출 배포 방법, 기본 도구 연결 방법 및 기존 Chat Completions 프로젝트를 세 단계로 마이그레이션하는 방법입니다. 다음과 같은 몇 가지 takeaway를 명심하세요:

• 먼저 구축한 후 최적화하세요. hello-world 예제로 시작하고, 기본 도구를 추가한 다음, previous_response_id로 상태를 층층이 쌓으세요.
• 점진적으로 마이그레이션하세요. 기능 플래그를 사용하고, 두 응답 형태를 로깅하며, 동일성 검증 후에만 100% 전환하세요.
• MCP 통합을 배포하세요. 이는 2026년의 개척지이며, 대부분의 벤더가 MCP 엔드포인트를 노출하기 위해 경쟁하고 있으며, Responses API는 이를 소비하는 가장 깔끔한 방법입니다.

Techsy에서는 Responses API 롤아웃 및 Chat Completions 마이그레이션을 포함하여 프로덕션 등급의 OpenAI 통합을 팀이 배포하도록 지원합니다. 무료 상담 받기.

Techsy 편집팀 작성, 2024년부터 OpenAI 통합을 배포하는 프로덕션 엔지니어들. 마지막 업데이트: 2026년 4월 25일.