핵심 요약

OpenAI Responses API는 text input, image input, structured output, tool call, conversation state를 함께 다룰 수 있는 주요 model response interface입니다. 단순 prompt 실험이 아니라 application workflow를 만들 때 사용합니다. 실무 구조는 보통 아래와 같습니다.

instructions + input + model + optional tools + optional structured output

요청 input에서 tool과 structured output으로 이어지는 OpenAI Responses API workflow

이미지는 이 글에서 설명하는 흐름을 보여줍니다. Application input, model response, tool access, structured output, logging이 이어집니다. Production AI 기능에는 반복 가능한 input, 예측 가능한 output, 실패를 확인할 수 있는 log가 필요합니다.

언제 Responses API를 쓰는가

아래 중 하나가 필요하면 Responses API를 고려합니다.

  • 일반 text answer
  • structured JSON answer
  • tool calling
  • web search 또는 file search 같은 built-in tool
  • image 또는 file input
  • streaming
  • previous_response_id 또는 conversations 기반 multi-turn state
  • 오래 걸리는 작업을 위한 background processing

Prompt를 한 번 테스트하는 정도라면 playground로 충분합니다. 제품 기능을 만들려면 API contract가 중요합니다.

이 글은 2026년 5월 23일 기준 OpenAI Responses API reference와 tools guide를 확인해 작성했습니다.

최소 요청

최소 요청에는 model과 input이 필요합니다. Model은 현재 OpenAI model guide에서 목적에 맞는 값을 선택합니다.

import OpenAI from "openai";

const openai = new OpenAI();

const response = await openai.responses.create({
  model: "YOUR_MODEL_ID",
  input: "Active recall과 rereading의 차이를 요약해줘."
});

console.log(response.output_text);

처음에는 예제를 작게 유지합니다. 최소 요청이 실패한다면 tool을 붙이기 전에 authentication, environment variable, package version, network access부터 확인해야 합니다.

Instructions 추가하기

안정적인 동작은 instructions에 둡니다. 모든 규칙을 user input 안에 묻어두지 않는 것이 좋습니다.

const response = await openai.responses.create({
  model: "YOUR_MODEL_ID",
  instructions: "간결한 technical editor처럼 답하세요. 필요한 경우에만 bullet을 사용하세요.",
  input: "Responses API를 다섯 문장으로 설명해줘."
});

좋은 instructions는 아래를 정합니다.

  • role과 audience
  • style과 length
  • safety boundary
  • formatting rule
  • 정보가 부족할 때의 처리 방식

“친절하게 답해줘”만 쓰면 반복 가능한 workflow에는 너무 모호합니다.

Structured Output 요청하기

다른 application code가 답변을 parsing해야 한다면 structured output이 유용합니다. 예를 들어 content planning tool은 title, slug, keyword, risk notes가 필요할 수 있습니다.

실무 schema 예시:

title: string
slug: string
primary_keyword: string
search_intent: string
outline: string[]
risk_notes: string[]

이때 model output은 data로 취급합니다. 저장하기 전에 validation을 해야 합니다. 필수 field가 비어 있으면 더 좁은 prompt로 재시도하거나 human review로 넘깁니다.

Structured output이 유용한 경우:

  • article brief
  • support ticket label
  • product description
  • document extraction
  • code review summary
  • SEO metadata draft

Structured output은 validation을 대체하지 않습니다. 더 나은 contract를 제공할 뿐입니다.

Tool은 좁게 연결하기

Responses API는 built-in tool과 custom function call을 지원합니다. Tool은 workflow를 강력하게 만들지만, 동시에 위험도도 높입니다.

좁은 tool이 좋습니다.

search_docs(query)
get_order_status(order_id)
create_draft_reply(ticket_id, body)
validate_front_matter(file_path)

너무 넓은 tool은 피합니다.

run_any_command(command)
query_any_database(sql)
send_any_email(to, subject, body)

넓은 tool은 policy를 model에게 너무 많이 맡깁니다. 좁은 tool은 code에서 rule을 강제할 수 있습니다.

현실적인 Workflow 예시

Article brief 생성 기능을 안전하게 만든다면 아래처럼 나눕니다.

1. 사용자가 topic을 입력한다.
2. App이 instructions, topic, target audience를 보낸다.
3. Model이 structured brief를 반환한다.
4. App이 required fields를 검증한다.
5. App이 duplicate slug를 확인한다.
6. 사람이 brief를 승인한다.
7. 그다음에만 file을 생성한다.

한 번의 prompt보다 느려 보입니다. 하지만 각 단계에 test가 있기 때문에 더 안정적입니다.

Multi-Turn State

Follow-up interaction이 필요하면 state를 명시적으로 다룹니다. Responses API는 이전 response를 이어가는 흐름을 지원합니다. Chat-like workflow나 agent workflow에 유용합니다.

대화 맥락이 실제로 필요할 때만 state를 씁니다. 요청이 독립적으로 재현되어야 한다면 stateless가 더 낫습니다.

좋은 state:

  • 사용자가 option A를 선택했습니다.
  • 이전 답변에 outline 후보 3개가 있었습니다.
  • app이 outline 2번만 수정해야 합니다.

나쁜 state:

  • 이후 동작을 바꾸는 숨은 과거 instructions
  • 이전 작업의 오래된 사실
  • 더 이상 context에 있을 필요가 없는 private data

Streaming과 Background Work

사용자가 진행 상황을 빨리 봐야 한다면 streaming을 사용합니다. 작업이 오래 걸리고 나중에 완료되어도 된다면 background mode를 고려합니다.

예시:

  • streaming: 눈앞에서 draft 작성, 긴 text 요약
  • background: 긴 research, file-heavy 작업, 여러 단계 generation

모든 option을 처음부터 켜지 않습니다. Plain response에서 시작한 뒤 사용자 경험에 필요할 때 streaming이나 background processing을 추가합니다.

흔한 실수

  • 기본 request가 동작하기 전에 tool을 붙입니다.
  • Application policy를 user input에만 넣습니다.
  • JSON을 요청하고 validation은 하지 않습니다.
  • Production data를 바꾸는 tool에 review gate가 없습니다.
  • 독립적이어야 할 작업에 conversation state를 유지합니다.
  • Launch 직전까지 token, latency, retry behavior를 보지 않습니다.

Production Checklist

[ ] Model ID가 한 곳에서 설정되는가?
[ ] Instructions가 versioning되는가?
[ ] Structured output이 validation되는가?
[ ] Tool arguments를 code가 검증하는가?
[ ] 외부 side effect에 approval 또는 엄격한 rule이 있는가?
[ ] Secret 없이 error가 logging되는가?
[ ] Retry와 fallback이 있는가?
[ ] Cost와 latency를 측정하는가?

Agent workflow를 만든다면 아래 글과 함께 보는 것이 좋습니다.

함께 보면 좋은 글

자주 묻는 질문

이 글은 언제 먼저 적용하면 좋나요?

새 도구를 바로 도입하기 전, 반복 업무와 검증 기준이 이미 있는지 확인할 때 먼저 적용하면 좋습니다.

초보자가 가장 먼저 확인할 부분은 무엇인가요?

처음에는 모델 성능보다 입력 데이터, 검증 기준, 실패 시 복구 방법을 먼저 정하세요. AI workflow는 자동화보다 검증 설계가 먼저입니다.

더 찾아볼 때 어떤 키워드를 쓰면 좋나요?

추가 검색할 때는 “OpenAI Responses API 사용 흐름: input, tools, structured output 정리” 같은 핵심 문구와 evaluation, workflow, guardrail, structured output, agent 같은 실무 키워드를 조합해 보세요.

참고 자료

  • OpenAI Responses API reference: https://platform.openai.com/docs/api-reference/responses
  • OpenAI tools guide: https://developers.openai.com/api/docs/guides/tools
  • OpenAI function calling guide: https://platform.openai.com/docs/guides/function-calling
  • OpenAI structured outputs guide: https://platform.openai.com/docs/guides/structured-outputs

Leave a comment

You may also enjoy