OpenAI API를 프로덕션에 배포하기 전에 확인해야 할 체크리스트다. 흔히 간과하지만 품질·속도·비용·안정성을 크게 개선하는 codex Responses API 설계 선택지를 중심으로 정리했다.

1. Responses API 사용

항상 Responses API를 사용하라. Completions API(레거시)가 아닌 Responses API가 OpenAI의 최신 에이전트 기능·내장 도구·상태 관리를 지원하는 플래그십 API다.

2. reasoning.effort 설정

추론 모델을 사용할 때 작업 난이도에 맞게 추론 강도를 조절한다. 과도한 추론은 지연 시간과 비용을 높이고, 부족한 추론은 품질을 낮춘다.

response = client.responses.create(
    model="gpt-5.5",
    reasoning={"effort": "medium"},  # "low" | "medium" | "high"
    input=[{"role": "user", "content": "..."}]
)

3. text.verbosity 설정

응답의 상세함 수준을 명시적으로 설정한다. 기본값이 항상 최적이 아닐 수 있다.

4. 어시스턴트 phase 파라미터 유지

gpt-5.3-codex 이상 모델을 사용할 때 어시스턴트 메시지에 포함된 phase 값을 후속 요청에 그대로 전달한다. 이는 에이전트가 최종 답변에 도달할 때까지 조기 종료되지 않도록 도와준다.

5. tool_search 활용

도구가 많을 때 매번 전체 목록을 전달하지 말고, 내장 tool_search를 사용해 관련 도구만 동적으로 선택하게 한다. 컨텍스트 사용량을 줄이고 응답 품질을 높인다.

6. 내장 도구 활용

웹 검색, 파일 검색, 코드 인터프리터, 컴퓨터 사용 등 OpenAI의 내장 도구를 먼저 검토한다. 직접 구현하는 것보다 안정적이고 비용 효율적인 경우가 많다.

7. 컴팩션(compaction) 활용

긴 대화에서 컨텍스트 창이 가득 찰 때 OpenAI의 컴팩션을 활용한다.

중요: 컴팩션된 출력을 수동으로 수정하지 말 것. 사람이 읽는 요약이 아닌 모델 상태 표현이므로 그대로 전달해야 한다.

8. prompt_cache_key 사용

반복되는 시스템 프롬프트나 고정 컨텍스트가 있으면 prompt_cache_key를 설정해 프롬프트 캐싱 효율을 높인다. 캐시 히트 시 입력 토큰 비용이 크게 절감된다.

9. reasoning.encrypted_content 활용

추론 과정의 암호화된 중간 결과를 후속 요청에 전달하면 재추론 없이 연속된 작업을 처리할 수 있다.

10. 장기 작업에 background=True 사용

수십 초 이상 걸리는 작업에는 백그라운드 모드를 사용한다.

job = client.responses.create(
    model="gpt-5.5",
    background=True,
    store=True,
    input="대용량 로그를 분석하고 주요 오류 패턴을 분류해줘.",
    tools=[{"type": "code_interpreter", ...}]
)

while job.status in {"queued", "in_progress"}:
    time.sleep(2)
    job = client.responses.retrieve(job.id)

UI에서는 “작업 진행 중” 상태를 표시하면 사용자 이탈을 줄일 수 있다. 주의: background=True는 제로 데이터 보존(ZDR)과 호환되지 않는다.

11. 도구 호출이 많은 워크플로에 WebSocket 모드 사용

20번 이상 도구 호출이 연속되는 에이전트 워크플로에는 WebSocket 모드가 HTTP보다 약 40% 빠르다. HTTP는 매 후속 요청마다 새 연결을 맺지만, WebSocket은 연결을 유지해 이전 응답 상태가 서버 메모리에 남아있다.

const ws = new WebSocket("wss://api.openai.com/v1/responses", {
  headers: { Authorization: "Bearer " + openai.apiKey }
});

단순한 요청-응답 워크플로라면 HTTP를 유지하는 것이 더 간단하다. WebSocket 연결 하나는 동시에 하나의 응답만 처리하므로, 병렬 작업은 여러 연결이 필요하다.

최종 요약

참고 자료

• API deployment checklist — OpenAI Developers (2026-04-26)