OpenAI Decisions API의 typed answers는 분류·라우팅 질문의 답 형식을 고정하지만, 실제 API 응답과 계정 없는 로컬 실습은 분리해 검증해야 합니다.
이 글은 2026년 10월 12일 기준으로 OpenAI 공식 Decisions 가이드와 API 레퍼런스를 읽고, 로그인·API 키·외부 네트워크 요청이 없는 HTML fixture에서 predicate·choice·score 세 질문 유형의 입력과 라우팅 경계를 확인한 기록입니다. 로컬 실습은 OpenAI 모델을 호출하지 않았고 실제 Decisions 응답의 정확도나 지연 시간을 측정하지 않았습니다. 대신 어떤 질문을 typed answer로 표현하고, 어떤 결과에서 사람 검토를 멈춤선으로 둘지에 집중했습니다.
먼저 답: typed answers를 어디에 쓰는가
typed answers는 “이 요청이 긴급한가”, “어느 팀으로 보낼 것인가”, “검토 우선순위 점수는 얼마인가”처럼 응답의 모양을 사전에 정할 수 있는 판단에 적합합니다. 자유로운 설명문을 받은 뒤 문자열을 다시 파싱하는 대신 질문마다 이름과 타입을 부여하면, 애플리케이션은 predicate·choice·score 같은 답을 구분해 다음 분기로 넘길 수 있습니다. 다만 타입이 맞는다는 사실은 판단이 옳다는 뜻이 아니므로 신뢰도, 허용 선택지, 사람 검토 조건을 별도로 저장해야 합니다.
공식 Decisions 가이드는 텍스트와 이미지를 입력으로 받고 질문마다 고유한 이름을 붙여 typed answer를 반환하는 흐름을 설명합니다. API 레퍼런스는 반환 답의 종류와 필드 형태를 더 구체적으로 보여 줍니다. 이 두 문서는 기능의 계약을 설명하는 1차 출처이고, 아래 캡처는 그 계약을 로컬 규칙표로 옮겨 본 교육용 실습의 증거입니다. 캡처의 결과를 실제 OpenAI API 응답이라고 읽어서는 안 됩니다.
predicate·choice·score를 같은 질문으로 섞지 않기
세 타입은 비슷해 보여도 운영 목적이 다릅니다. predicate는 조건의 참·거짓을 빠르게 분기할 때 사용합니다. “긴급 문의인가?”처럼 다음 단계가 두 갈래로 나뉘는 질문에 맞습니다. choice는 미리 허용한 목록에서 담당 팀이나 처리 경로를 고르는 질문입니다. 목록 밖의 새로운 팀명을 받아도 되는지, 복수 선택이 가능한지부터 정해야 합니다. score는 연속적인 우선순위 또는 클래스별 확률을 비교할 때 유용하지만, 점수 0.82를 승인으로 번역하는 기준은 제품 계약이 아니라 운영자가 정해야 할 정책입니다.
| 질문 타입 | 예시 | 애플리케이션의 다음 확인 |
|---|---|---|
| predicate | 긴급한가? | true여도 근거와 사람 검토 조건 확인 |
| choice | 담당 팀은? | 허용 목록·누락값·복수 선택 정책 확인 |
| score | 우선순위는? | 임계값·확률 해석·재검토 기준 확인 |
이 구분은 JSON 스키마의 문법 검사가 아니라 질문 설계의 문제입니다. choice에 자유 텍스트를 넣거나 score를 곧바로 결재 승인으로 사용하는 것은 타입을 지켜도 위험합니다. 실무에서는 원문 입력, 질문 버전, 답의 이름, 모델·정책 버전, 사람 검토 결과를 함께 보관해야 나중에 잘못된 라우팅을 추적할 수 있습니다.
Responses API와의 경계 읽기
Decisions와 Responses는 모두 모델 호출과 연결될 수 있지만, 같은 작업을 다른 이름으로 부르는 것이 아닙니다. Decisions 문서는 특정 질문에 대한 typed answer를 얻어 분류·라우팅·우선순위화 같은 판단에 쓰는 흐름을 제시합니다. Responses API 레퍼런스는 텍스트 또는 JSON Schema 형식 등 더 넓은 응답 구성을 설명합니다. 자유로운 답변, 도구 호출, 여러 단계의 결과가 필요한지, 아니면 고정된 질문의 판단값이 필요한지를 먼저 구분해야 합니다.
Structured Outputs 문서와도 혼동하지 않아야 합니다. JSON Schema에 맞는 출력을 요구하는 기능은 애플리케이션이 읽을 수 있는 구조를 보장하는 데 도움을 주지만, 구조적으로 유효한 값이 사실인지, 안전한지, 업무 정책에 맞는지는 별도의 검증 대상입니다. “JSON 파싱 성공”과 “라우팅 결정 승인”을 하나의 성공 상태로 합치지 말고, 입력 검증·답 타입 검증·정책 검토를 단계로 나누세요.
직접 실행: 계정 없는 로컬 라우팅 fixture
실제 API를 호출하지 않고 자체 HTML fixture를 만들었습니다. 고정 입력은 환불 조건을 묻는 고객 문의이고, 질문 계약은 긴급 여부(predicate), 담당 팀(choice), 검토 우선순위(score) 세 가지입니다. 화면에는 계정 없음·API 키 없음·읽기 전용이라는 범위를 명시했습니다. 버튼을 누르기 전에는 결과가 비어 있고, 클릭 뒤에는 로컬 규칙이 세 답과 “사람 검토 대기·외부 변경 없음”을 표시하도록 했습니다.
이 실습에서 확인한 것은 입력 화면과 결과 화면이 실제로 바뀌는지, 세 타입의 라벨과 값이 함께 보이는지, 외부 변경 없이 사람 검토 경계가 남는지입니다. 실행한 것은 브라우저의 로컬 JavaScript뿐이며 OpenAI 서버·모델·계정·저장소에 연결하지 않았습니다. 따라서 캡처와 영상은 제품의 성능 또는 API 반환값 증거가 아니라, 공식 문서의 질문 계약을 안전하게 연습하는 재현 자료입니다.
운영에 넣기 전 실패 조건
첫째, 질문의 선택지가 실제 업무의 책임 범위와 맞는지 확인해야 합니다. “환불 지원”을 반환했다고 바로 티켓을 변경하거나 고객에게 답장을 보내지 말고, 팀 목록의 유효성·담당자 존재·영업시간·금액 임계값을 다시 검사하세요. 둘째, score의 의미를 문서화해야 합니다. 0.82가 확률인지 우선순위 정규화 값인지 다르면 같은 숫자도 전혀 다른 결정을 뜻합니다.
셋째, 모델의 거절·불완전 응답·질문 누락을 정상적인 실패 경로로 다뤄야 합니다. 결과에 답이 없을 때 빈 문자열을 담당 팀으로 저장하면 안 됩니다. 넷째, 원문에 개인정보가 포함될 수 있다면 전송 전 마스킹과 보존 기간을 정해야 합니다. 이번 로컬 fixture에는 실제 고객 정보가 없고, 운영 데이터에 대한 안전성을 검증하지 않았습니다.
다섯째, 외부 상태 변경은 별도 승인으로 묶어야 합니다. 분류 결과를 계산하는 일과 CRM 티켓을 닫거나 환불을 실행하는 일은 같은 호출에 넣지 않는 편이 안전합니다. 먼저 읽기 전용 결과를 저장하고, 사람이 확인할 수 있는 화면과 로그를 남긴 뒤, 허용된 작업만 다음 단계에서 실행하세요. 자동화의 성공 메시지가 곧 업무 완료를 의미하지 않도록 상태를 `계산됨`, `검토 필요`, `승인됨`, `실행됨`으로 나누는 것이 좋습니다.
재현 절차와 최소 로그
안전한 도입 순서는 작게 시작합니다. 먼저 공식 가이드에서 질문 타입과 반환 계약을 읽고, 실제 업무 데이터가 아닌 고정 fixture로 질문 이름과 허용값을 정합니다. 다음으로 입력→답→정책 판정의 세 단계를 로컬에서 테스트합니다. 그 뒤 읽기 전용 샌드박스에서 소량의 비민감 데이터로 호출하며, 실제 계정에서 보이는 기능·플랜·지역·모델 지원 범위를 별도로 확인합니다. 마지막에만 사람 승인 뒤 외부 변경을 연결합니다.
한 번의 실행에는 검증일과 시간대, 입력 식별자(원문 자체가 아닌 해시도 가능), 질문 스키마 버전, 결과 타입, 신뢰도 또는 확률, 정책 판정, 사람 검토자, 외부 변경 여부를 남기세요. API 응답이 성공해도 질문 이름이 바뀌었거나 선택지가 폐기됐다면 이전 결과와 직접 비교할 수 없습니다. 버전과 실패 사유를 함께 보존해야 운영 중인 라우터를 되돌릴 수 있습니다.
이 글에서 이어서 읽을 수 있는 입력 고정과 회귀 테스트 점검 글도 같은 원칙을 다룹니다. 제품 결과를 과장하지 않고, 입력과 관찰 결과를 분리해 기록하는 방식입니다.
이번 검증의 범위와 한계
공식 문서에서 확인한 내용은 Decisions API가 typed answers를 위한 질문과 답 형태를 제공한다는 점, API 레퍼런스에 predicate·choice·score 답의 구조가 있다는 점, Responses와 Structured Outputs가 더 넓은 응답·스키마 계약을 제공한다는 점입니다. 로컬에서 확인한 내용은 버튼 클릭 전후의 화면 전환과 세 질문 결과 표시뿐입니다.
- 확인한 사실: 공식 문서의 질문 타입과 답 형태를 읽고 비교했다.
- 확인한 사실: 계정·API 키·네트워크 없이 자체 fixture의 로컬 규칙이 결과 화면으로 전환됐다.
- 확인하지 않은 것: OpenAI 모델의 실제 답변 정확도, 지연 시간, 비용, 계정별 Decisions 가용성.
- 확인하지 않은 것: 운영 데이터 전송, 개인정보 보호 설정, CRM·티켓·결제 시스템의 외부 변경.
특히 로컬 결과의 “긴급 여부: true”와 “우선순위: 0.82”는 교육용으로 고정한 값입니다. 이 값을 OpenAI API의 판단이나 실제 고객 문의의 정답으로 해석하면 안 됩니다. 실제 도입에서는 공식 지원 범위, 모델·플랜 조건, 데이터 정책, 실패 응답, 사람 승인 절차를 현재 계정과 조직 정책에서 다시 확인해야 합니다.
공식 출처와 검증일
2026년 10월 12일 다음 공식 1차 자료를 대조했습니다. Decisions 가이드는 기능의 용도와 질문 방식, TypeScript API 레퍼런스는 반환 타입과 답 구조, Structured Outputs 가이드는 스키마 준수와 거절·불완전 결과의 처리 관점을 제공합니다.