워크플로우 노트

wn121-n8n-cloud-memory-gate-summary-public.md

wn121-n8n-cloud-memory-gate-public.py

wn120-n8n-email-ai-agent-failure-gate-public.json

n8n 이메일 AI Agent 장애 진단: 50k 프롬프트보다 메일 원문·메모리 창·도구 출력을 먼저 잘라야 한다

이천재 — Mon, 4 May 2026 17:57:27 +0900

n8n 이메일 AI Agent가 몇 주 동안 잘 돌다가 갑자기 parser error나 invalid syntax로 멈추면, 첫 질문을 모델 변경으로 잡기 쉽다. 실제 진단은 더 작게 시작하는 편이 낫다. 실패한 메일 한 건을 고정해서 다시 실행할 수 있는가. 그 메일 원문과 첨부를 그대로 agent에 넣고 있지 않은가. 메모리가 계정별로 계속 쌓이고 있지 않은가. Google Sheets 같은 도구 출력이 너무 넓게 붙고 있지 않은가.

2026-05-04에 Reddit 공개 신호를 먼저 봤다. r/n8n에는 6개 메일함을 돌리는 email management agent가 6주 뒤 AI Agent/LangChain node에서 invalid syntax를 내며 흔들린다는 진단 요청이 올라왔다. 긴 system prompt, 다국어 분류, Google Sheets 제품 조회, Telegram 승인 버튼, 일정 처리, retry worker, error handler가 한 workflow에 붙어 있었다. 댓글 흐름도 payload size, memory, failed execution replay, tool output shape를 먼저 보라는 쪽이었다.

커뮤니티 글은 수요 신호로만 쓴다. n8n 동작과 기능 설명은 n8n 공식 문서로 확인했다. 직접 실험은 live n8n 계정 없이 deterministic local harness로만 했다.

짧게 정리하면 이렇다.

긴 prompt를 줄이기 전에 실패한 execution fixture를 먼저 고정한다.
Email Trigger에서 원문 format과 attachment download가 agent 입력을 키우는지 본다.
계정별 memory는 무제한 history가 아니라 window나 summary로 끊는다.
Google Sheets/Product lookup 결과는 전체 rows가 아니라 top matches만 넘긴다.
Structured Output Parser는 schema guard다. oversized email envelope를 대신 줄여주지 않는다.
실패 재시도는 같은 큰 input을 세 번 더 보내는 방식이면 진단이 늦어진다.

커뮤니티 신호는 장애 모양을 고르는 데만 쓴다

선택한 demand signal은 n8n 이메일 에이전트 장애였다. 공개 글의 핵심은 "AI Agent가 나쁘다"가 아니다. scope가 큰 email workflow에서 어느 순간부터 실패 입력이 너무 커졌고, 어떤 mailbox, 어떤 sender, 어떤 tool call에서 깨지는지 좁히기 어렵다는 점이다.

이 신호가 좋은 WN 주제인 이유는 실험이 가능하기 때문이다. 실제 고객 메일이나 계정이 없어도 아래 조건은 local harness로 재현할 수 있다.

장애 재료	이메일 agent에서 흔한 형태
긴 system prompt	분류표, 말투, 금지 규칙, 상품 추천 규칙이 계속 붙음
메일 원문	HTML, forwarding history, 서명, quoted reply가 함께 들어옴
첨부	PDF, 이미지, inline attachment 요약이 agent 입력 앞에 붙음
memory	계정별 이전 대화가 session history로 계속 남음
tool output	Google Sheets 제품 목록이나 sender memory가 넓게 반환됨
retry	같은 oversized input을 다시 보내며 실패만 반복함

커뮤니티 글은 "왜 이 문제를 지금 다루는가"를 설명한다. "n8n이 실제로 이렇게 동작한다"는 근거는 아니다. 그 경계가 흐려지면 글이 장애 분석이 아니라 댓글 요약이 된다.

n8n 공식 문서로 확인한 줄일 수 있는 지점

n8n Email Trigger (IMAP) docs는 IMAP Email node가 email server에서 email을 받는 trigger node라고 설명한다. 이 node에는 attachment download option이 있고, docs는 필요할 때만 켜라고 적는다. processing이 늘기 때문이다. format option도 RAW, Resolved, Simple로 나뉜다. Resolved는 attachments를 binary data로 저장하고, RAW는 raw field에 base64url body를 넣는다.

이 말은 이메일 agent에서 꽤 중요하다. "메일을 받았다"가 곧 "agent에 full email을 다 넣어도 된다"는 뜻은 아니다. 자동 답장 초안에는 보통 본문 일부, 주문번호, 고객 의도, 필요한 attachment summary면 충분하다. forwarding history와 binary payload까지 매번 넣으면 실패 envelope가 커진다.

AI Agent 쪽에서도 줄일 지점이 보인다. n8n Tools AI Agent docs는 prompt를 previous node의 chatInput에서 자동으로 받거나 직접 정의할 수 있다고 설명한다. Require Specific Output Format을 켜면 Auto-fixing Output Parser, Item List Output Parser, Structured Output Parser를 연결한다. options에는 System Message, Max Iterations, Return Intermediate Steps, Tracing Metadata가 있다.

Memory docs도 이 글의 핵심 근거다. Simple Memory는 current session의 customizable chat history length를 저장한다. Redis, Postgres, Zep 같은 memory service node도 있다. 더 복잡한 memory 관리는 Chat Memory Manager로 처리할 수 있고, docs는 agent response memory size를 확인하고 줄이는 예를 든다.

Parser와 debug surface도 따로 봐야 한다. Structured Output Parser는 JSON Schema 기반 field 반환을 돕지만, generated schema는 field를 mandatory로 취급하고 $ref는 지원하지 않는다. Error handling docs는 failed execution을 Executions에서 보고 previous execution data를 load할 수 있다고 설명한다. Debug executions docs는 failed execution을 Debug in editor로 가져와 first node에 data를 pin할 수 있다고 한다. 단, 기능 availability는 n8n Cloud와 registered Community plans라는 caveat가 있다.

로컬 실험: 42개 메일을 두 route로 돌렸다

실제 n8n Cloud, self-hosted n8n, IMAP, Google Sheets, Postgres, LLM API는 호출하지 않았다. 대신 n8n-like failure shape를 Python으로 만들었다. 입력은 6개 mailbox와 42개 synthetic message다. 일부 message에는 긴 forwarding history, attachment payload, 제품 추천 요청, ambiguous mixed-language request를 넣었다.

비교한 route는 두 가지다.

route	방식	위험
naive long prompt	50k system prompt, 계정별 전체 memory, raw email payload, 넓은 product-sheet output을 agent envelope에 붙임	parser error 뒤 같은 큰 입력을 반복 retry
bounded replay gate	plain-text sanitizer, body budget, attachment summary, 6-message memory window, top 8 tool rows, replay ID를 먼저 적용	위험하거나 애매한 메일은 write 대신 manual review

결과는 크게 갈렸다.

metric	naive long prompt	bounded replay gate
processed messages	42	42
failed executions	17	0
manual review routes	0	3
retry attempts	51	0
max envelope chars	197545	19970
max memory items seen	6	6
tool rows per message	45 또는 637	8

naive route의 첫 failure는 cycle 3의 product thread였다. message body 자체도 길었지만, 계정별 이전 history와 637개 product row surface가 같이 붙으면서 synthetic parser threshold를 넘었다. 실패 뒤에는 같은 envelope를 3회 retry했다. 진단에는 별 도움이 없고 task만 태우는 흐름이다.

bounded route는 실패를 만들지 않았다. 대신 3개 message를 manual_review로 보냈다. certified mail with forwarded history, ambiguous cancellation 같은 입력은 자동 초안보다 사람이 먼저 보는 쪽이 맞다. 이 route에서 중요한 값은 failed_executions 0보다 max_envelope_chars 19970이다. agent가 보는 봉투를 작게 만들었기 때문에 실패한 입력을 다시 잡기 쉬워졌다.

장애 진단 순서

첫 단계는 prompt rewrite가 아니다. failed execution을 하나 고정한다. n8n Debug executions가 가능한 환경이라면 failed execution을 editor로 가져오고 첫 node data를 pin한다. 기능을 쓸 수 없는 환경이면 execution id, mailbox, message id, subject hash, attachment count, body char estimate를 따로 남긴다.

그 다음 Email Trigger 바로 뒤에서 payload를 줄인다.

HTML body를 plain text로 바꾼다.
quoted reply와 forwarding history를 일정 길이 뒤에서 자른다.
attachment는 원본 대신 filename, type, size, extracted summary만 넘긴다.
inline image와 base64 raw body는 agent 입력에서 빼고, 필요한 경우 별도 parser route로 보낸다.
본문 길이가 기준을 넘으면 자동 답장 대신 manual review로 보낸다.

Memory는 mailbox별로 끊는다. 고객 support agent라면 모든 이전 메일이 매번 필요하지 않다. 최근 5-10개 message, sender preference summary, unresolved ticket state 정도로 나눈다. n8n memory docs의 Simple Memory나 memory service node를 쓸 수 있더라도, "저장할 수 있다"와 "agent call마다 다 넣어야 한다"는 다른 판단이다.

Tool output도 줄인다. Google Sheets를 product catalog처럼 쓰면 row 전체를 agent에게 주고 싶어진다. 하지만 agent에게 필요한 것은 보통 top N candidate, price, link, availability, category 정도다. 전체 637 rows를 매번 붙이면 retrieval이 아니라 dump가 된다.

Parser error는 마지막에 본다. Structured Output Parser와 JSON Schema는 output 모양을 잡는 데 필요하다. 그러나 input envelope가 이미 너무 크면 parser를 더 엄격하게 만들어도 같은 실패가 남는다. schema에는 category enum, allowed action, confidence type, needs_human_review 같은 field를 두되, 큰 메일은 schema 이전 단계에서 줄인다.

실제 workflow에 넣을 gate

운영 workflow에는 아래 순서가 낫다.

위치	gate	실패 route
Email Trigger 직후	mailbox, message id, sender, subject, body length, attachment count 기록	missing id면 stop/error
sanitizer	plain text 변환, quoted history cutoff, attachment summary	body/attachment 과대면 manual review
memory	mailbox별 window, sender summary, unresolved state만 유지	memory overflow면 Chat Memory Manager 또는 review
tool lookup	query를 먼저 좁히고 top rows만 반환	너무 많은 rows면 clarification 또는 review
agent output	category enum, allowed action, object consistency 검사	unsafe action이면 manual review
retry	transient error만 node-level retry	parser/input/schema 문제는 같은 envelope retry 금지
logging	replay id, execution id/url, route, failure kind 저장	public artifact는 마스킹 후 하단 첨부

이 순서의 목표는 agent를 덜 쓰는 것이 아니다. agent에게 줄 수 있는 입력만 남기는 것이다. 이메일 원문 정리, memory 자르기, tool output cap, replay id는 창의적 판단이 아니라 운영 gate다.

어디까지 이 실험을 믿어도 되는가

이 실험은 live n8n 장애 재현이 아니다. 특정 n8n 버전, LangChain node, OpenAI model, Google Sheets credential, Postgres pool을 검증하지 않았다. 그래서 "n8n 이메일 agent는 42건 중 17건 실패한다" 같은 benchmark로 읽으면 안 된다.

대신 실패 구조를 작게 보여준다. 긴 system prompt만 문제가 아니라, raw email payload, attachment, growing memory, broad tool output이 같은 envelope에 들어갈 때 실패가 커진다. 같은 큰 입력을 재시도하면 원인을 좁히지 못한다. 반대로 sanitizer, memory window, tool row cap, replay ID를 앞에 두면 자동 처리할 메일과 사람이 봐야 할 메일이 갈린다.

n8n 이메일 AI Agent를 운영에 놓는다면 첫 48시간은 자동 전송보다 draft/review mode가 낫다. 실패한 메일 하나를 다시 재현할 수 있을 때 자동화 범위를 넓혀도 늦지 않다.

같이 보면 좋은 글

참고 자료

실행 로그 첨부

민감 경로와 이메일 주소를 마스킹한 공개용 로그와 실험 스크립트만 아래에 첨부한다.

wn120-n8n-email-ai-agent-failure-gate-public.json
wn120-n8n-email-ai-agent-failure-gate-summary-public.md
wn120-n8n-email-ai-agent-failure-gate-public.py

0.04MB

wn120-n8n-email-ai-agent-failure-gate-summary-public.md

wn120-n8n-email-ai-agent-failure-gate-public.py

wn119-n8n-agent-workflow-gate-public.json

n8n AI Agent 운영 기준: 멋진 노드보다 데이터 계약·중복 방지·재시도 로그가 먼저다

이천재 — Sun, 3 May 2026 20:49:07 +0900

n8n AI Agent workflow가 흔들리는 지점은 agent가 말을 못 해서가 아니다. 보통은 쓰기 전에 멈추지 못해서 흔들린다. Webhook payload key가 바뀌었는데 그대로 CRM에 쓰고, 같은 trigger가 두 번 들어왔는데 메일을 두 번 보내고, 429와 403을 같은 재시도로 묶으면 agent prompt를 고쳐도 운영 문제는 남는다.

2026-05-03에 Reddit 흐름을 먼저 봤다. r/n8n, r/AI_Agents, r/automation에서 반복된 신호는 비슷했다. "더 많은 agent node"보다 data contract, dedupe key, retry route, execution log가 먼저라는 쪽이다. 이 글에서 Reddit은 수요 신호로만 쓴다. n8n 동작과 기능 설명은 n8n 공식 문서로 확인했다.

짧게 정리하면 이렇다.

n8n AI Agent 앞에는 payload contract gate를 둔다.
중복 trigger는 write action 전에 event key나 idempotency key로 막는다.
agent output은 "JSON처럼 보인다"가 아니라 allowed action, ticket/order ID, confidence, business rule을 따로 검증한다.
429 같은 transient failure와 403 같은 auth failure는 같은 retry route로 보내지 않는다.
운영자가 나중에 찾을 수 있도록 execution metadata나 trace ID를 남긴다.
Structured Output Parser는 도움이 되지만, n8n docs도 agent parsing caveat를 따로 둔다. parser가 business validation을 대신하지 않는다.

커뮤니티 신호는 문제를 고르는 데만 쓴다

이번 radar에서 가장 강한 신호는 r/n8n 글이었다. 글과 댓글은 agent workflow가 production에서 버티려면 data contracts, retries, idempotency, observability가 먼저라고 반복했다. r/automation에서는 duplicate data를 어떻게 막느냐는 질문이 올라왔고, 답변은 unique ID, hash, early dedupe, insert 전 검증 쪽으로 모였다. r/AI_Agents 쪽도 messy input, confirmation step, 좁은 scope, eval set 같은 운영 지점을 강조했다.

이런 글은 공식 근거가 아니다. 다만 독자가 실제로 막히는 질문을 보여준다. 그래서 주제를 "n8n AI Agent가 좋은가"가 아니라 "AI Agent workflow가 쓰기 전에 무엇을 잠가야 하는가"로 좁혔다.

n8n 공식 문서로 확인한 안전장치

n8n Tools AI Agent docs는 Tools Agent가 external tools와 APIs를 사용해 action을 수행하거나 정보를 가져오는 node라고 설명한다. 같은 문서에는 Require Specific Output Format 설정이 있고, 이 설정을 켜면 Auto-fixing Output Parser, Item List Output Parser, Structured Output Parser 같은 output parser를 붙이게 된다.

그런데 Structured Output Parser common issues 문서는 agent workflow에서 structured parsing이 자주 안정적이지 않다고 따로 적고 있다. n8n은 agent output을 별도 LLM-chain으로 받아 parse하는 방식을 더 일관된 결과로 권한다. 이 말은 중요하다. "parser를 붙였으니 안전하다"가 아니라 "agent output과 parser를 분리해도 business validation은 남는다"로 읽어야 한다.

운영 gate로 쓸 수 있는 공식 surface도 있다.

지점	n8n에서 볼 기능	운영상 역할
입력 중복	Remove Duplicates	current input 또는 previous executions 기준으로 중복 item 제거
node 실패	Retry On Fail	실패한 node 재시도. 429처럼 transient failure에 맞다
오류 분기	On Error, Error Trigger	stop, continue, error output, error workflow route 분리
실행 추적	Execution Data	execution list에서 찾을 metadata 저장
rate limit	Retry On Fail, Loop Over Items, Wait	request 간격과 재시도 간격을 명시

이 표가 agent 설계를 대신하지는 않는다. 다만 "AI가 알아서 판단"하기 전에 workflow가 먼저 막을 수 있는 지점이다.

로컬 실험: agent-first와 contract-first 차이

실제 n8n Cloud나 Zapier 계정은 쓰지 않았다. 대신 n8n-like workflow failure를 deterministic Python harness로 만들었다. 입력은 support ticket webhook 7개다. scenario는 정상 입력, duplicate webhook, field rename, 잘못된 agent action, rate limit, auth failure, missing trace로 나눴다.

비교한 route는 두 가지다.

route	방식	기대 위험
naive agent-first	payload와 agent output을 거의 그대로 write action에 넘김	duplicate write, invalid action, generic retry
contract-first workflow gate	payload contract, dedupe key, agent output gate, retry route, trace ID를 먼저 봄	일부 run은 write 전에 block/review

결과는 아래처럼 갈렸다.

metric	naive agent-first	contract-first gate
total write	7	1
duplicate write	2	0
invalid action write	1	0
explicit route decision	3 failures after write	7 decisions before or at write gate

contract-first route의 decision 분포는 block_before_agent 1, dedupe_skip 1, manual_review 2, retry_node_only_with_idempotency_key 1, stop_and_alert 1, write_once 1이었다.

여기서 중요한 수치는 write가 줄었다는 점이다. 좋은 자동화는 많이 쓰는 workflow가 아니다. 써도 되는 것만 쓰고, 애매한 것은 작게 멈추는 workflow다.

Gate 1: Webhook 바로 뒤에서 payload contract를 본다

Webhook이 들어오면 바로 AI Agent로 넘기지 않는다. 먼저 event ID, business object ID, recipient, priority, message 같은 최소 key를 본다. 이번 실험에서는 customer_email이 email로 바뀐 scenario가 있었다. 사람이 보면 같은 뜻 같지만 workflow contract에서는 다른 payload다.

이 단계에서 할 일은 거창하지 않다.

필수 key가 있는지 본다.
값 type과 빈 값 여부를 본다.
action에 필요한 business object ID가 있는지 본다.
빠진 key가 있으면 Stop And Error 또는 manual review route로 보낸다.
이 실패를 error workflow가 받을 수 있게 message를 남긴다.

n8n에서는 Code node, IF node, Stop And Error node, Error Trigger를 조합할 수 있다. 중요한 것은 AI Agent가 "없는 값을 추측"하지 못하게 하는 것이다.

Gate 2: 중복은 write action 전에 막는다

duplicate webhook은 실무에서 이상한 사건이 아니다. upstream retry, browser double-submit, polling overlap, replay가 모두 같은 결과를 만든다. 이때 "agent가 같은 답을 했으니 괜찮다"는 판단은 위험하다. CRM update, email send, invoice create 같은 side effect는 두 번 실행되면 비용이 생긴다.

n8n Remove Duplicates docs는 current input 안의 duplicate 제거와 previous executions 기준 duplicate 제거를 설명한다. Value Is New에서는 unique ID나 field combination이 dedupe 기준이 된다. 이 기능만으로 모든 idempotency가 해결되지는 않지만, write action 앞에서 첫 번째 guard로 쓰기 좋다.

실무에서는 다음 순서가 낫다.

upstream event ID가 있으면 그 값을 dedupe key로 쓴다.
event ID가 없으면 source + object_id + action + timestamp bucket처럼 조합 key를 만든다.
Remove Duplicates나 DB unique constraint로 write 전에 막는다.
skip된 run도 trace에 남긴다.
replay를 해야 한다면 새 run인지 retry인지 구분한다.

이번 실험에서 naive route는 같은 ticket/action 조합이 두 번 쓰였다. contract-first route는 duplicate event를 dedupe_skip으로 끝냈다.

Gate 3: agent output은 parser 뒤에서도 한 번 더 본다

n8n AI Agent에 Structured Output Parser를 붙이면 output 모양은 나아질 수 있다. 하지만 n8n docs는 agent structured parsing caveat를 따로 둔다. 그래서 parser 통과와 업무 허용은 분리해야 한다.

이번 실험의 S4-GREEN-200-BAD-ACTION은 syntactically valid object를 반환했다. 문제는 action이 refund_now였다는 점이다. support reply workflow에서 환불 실행은 허용 action이 아니었다. naive route는 이 action을 write 대상으로 받아들였고, gated route는 manual_review로 보냈다.

agent output gate는 최소한 아래를 본다.

검사	예시
allowed action	`draft_reply`, `route_to_human`, `classify_ticket`처럼 whitelist
object consistency	output의 ticket/order ID가 input과 같은지
confidence/type	숫자 type인지, 최소 기준 이상인지
side effect class	email draft인지, 실제 전송인지, 결제/환불인지
human review 필요 여부	긴급, 금액, 권한 변경, 고객 영향 action

이 gate를 prompt에만 맡기면 안 된다. prompt는 agent에게 방향을 준다. gate는 workflow가 실제 action을 막는 장치다.

Gate 4: 429와 403은 같은 재시도가 아니다

n8n node settings에는 Retry On Fail이 있고, rate-limit docs는 429 상황에서 Retry On Fail 또는 Loop Over Items + Wait를 쓸 수 있다고 설명한다. 이 기능은 transient failure에 맞다. 잠깐 기다렸다가 같은 node를 다시 시도하면 되는 경우다.

반대로 403 auth failure는 재시도로 풀리는 문제가 아니다. credential, scope, account 권한을 봐야 한다. 이것을 full workflow retry로 태우면 같은 side effect를 반복하거나, task만 소모하고, 운영자는 실패 원인을 늦게 본다.

분기 기준은 단순하게 둔다.

failure	route
429, timeout	node-level retry with backoff
400 bad request	payload/schema review
401/403	stop and alert, credential/scope check
parser/business validation fail	manual review or fail-closed
duplicate event	skip and log

이번 실험에서 rate-limit scenario는 retry_node_only_with_idempotency_key로 갔다. auth failure는 stop_and_alert였다. 둘을 같은 retry로 묶지 않은 것이 핵심이다.

Gate 5: 나중에 찾을 수 있는 execution metadata를 남긴다

Zapier 커뮤니티 글에서도 run ID를 어떻게 operations에게 넘길지 묻는 신호가 있었다. n8n에서도 같은 문제가 생긴다. 실패했을 때 "어떤 run이 무엇을 썼는지"를 30초 안에 못 찾으면, 자동화가 아니라 수동 수사에 가깝다.

n8n Error handling docs의 error data에는 execution id, url, retryOf, lastNodeExecuted 같은 정보가 포함될 수 있다. 단, execution id와 url은 execution이 database에 저장되어야 한다는 caveat가 있다. Execution Data node는 workflow execution metadata를 저장해 execution list에서 검색할 수 있게 한다.

운영용 metadata는 길게 쓰지 않는 편이 낫다. n8n Execution Data docs에는 key/value length 제한도 있다. 예를 들어 아래 정도면 충분하다.

key	value 예시
`trace_id`	`sha256(event_id + action)`의 짧은 값
`object_id`	ticket/order/customer ID
`route`	`write_once`, `dedupe_skip`, `manual_review`
`failure_kind`	`payload_contract_missing`, `auth_403`, `rate_limit_429`
`idempotency_key`	write action dedupe에 쓴 key

로그는 장식이 아니다. 재시도, 고객 문의, 내부 승인, 장애 회고에서 같은 사건을 다시 찾는 색인이다.

실제 n8n workflow에 넣는 순서

AI Agent workflow를 만들 때는 아래 순서로 시작한다.

Webhook 또는 trigger 바로 뒤에 payload contract gate를 둔다.
event ID 또는 business object ID로 dedupe key를 만든다.
Remove Duplicates 또는 DB unique constraint를 write action 앞에 둔다.
AI Agent output은 parser 이후 allowed action과 object consistency를 다시 본다.
side effect가 있는 action은 draft, preview, approval, execute를 나눈다.
429/timeout은 node-level retry로 보내고, 401/403/400은 다른 route로 보낸다.
Error Trigger workflow를 별도로 두고 Slack/email alert에는 trace ID와 execution URL을 넣는다.
Execution Data에는 운영자가 검색할 metadata만 짧게 저장한다.
처음 48시간은 자동 execute보다 draft/review mode로 둔다.

이 순서는 agent를 덜 쓰자는 뜻이 아니다. agent가 판단해야 할 부분만 남기자는 뜻이다. payload shape, duplicate trigger, credential failure, trace lookup은 agent가 창의적으로 해결할 문제가 아니다.

어디까지 이 실험을 믿어도 되는가

이 run은 live n8n Cloud, Zapier, LLM API를 호출하지 않았다. 특정 n8n 버전이나 paid plan의 실제 UI를 검증한 것도 아니다. 그래서 이 글은 "n8n에서 정확히 몇 퍼센트 실패한다"는 benchmark가 아니다.

대신 운영 실패를 작게 재현했다. duplicate event가 있으면 write 전에 key로 막는가. payload key가 바뀌면 agent 전에 멈추는가. agent가 valid-looking but unsafe action을 내면 manual review로 보내는가. 429와 403을 구분하는가. 나중에 execution을 찾을 trace를 남기는가.

이 다섯 질문에 답하지 못하면 agent prompt를 고쳐도 workflow는 계속 흔들린다.

같이 보면 좋은 글

참고 자료

실행 로그 첨부

민감 경로와 이메일 주소를 마스킹한 공개용 로그와 실험 스크립트만 아래에 첨부한다.

wn119-n8n-agent-workflow-gate-public.json
wn119-n8n-agent-workflow-gate-summary-public.md
wn119-n8n-agent-workflow-gate-public.py

wn119-n8n-agent-workflow-gate-summary-public.md

wn119-n8n-agent-workflow-gate-public.py

SCM SAP split-expedite approval evaluation: PO000318 승인 callback과 REBEC shadow ledger를 닫은 SCM-047

이천재 — Sun, 3 May 2026 20:37:20 +0900

PO000318은 이제 단순 경보가 아니라 승인 callback이 들어온 주문이다. 해야 할 일은 queue 숫자를 보는 것이 아니라, 84개 critical kit를 지금 예약할지 결정하는 것이다.

1. 운영자가 먼저 보는 주문 case file

주문 번호	lane	현재 shipping status	original due date	외부 신호	영향 이유	아무것도 안 했을 때 결과	추천 액션	tradeoff
PO000318	LANE-KR-US-AI-SEA	operator approved split expedite for 84 critical kits; expedited split is in capacity reservation simulation, remaining 336 kits stay on ocean ETA 2026-05-15, terminal appointment still pending	2026-05-16	UNCTAD 2026-04-07, WTO 2026-03-19, IMF 2026-04-14 official signals were rechecked at 2026-05-03T01:02:07+09:00; mapped as capacity and transport-cost pressure, not as a direct lane shutdown.	The AI server control board is critical, the ocean ETA is still one day before due date, and the approved split must be reserved before the decision window closes.	If the callback is left as a queue item, no-action remains at 38% residual stockout risk and the modeled line-stop risk cost stays at USD 155800.	Accept the approval callback into the shadow ledger, reserve 84 critical kits under ALT-PO000318-SPLIT-EXPEDITE-20PCT, and keep external SAP write false until human execution.	Pay USD 18400 premium freight and handle partial-kit complexity, but reduce modeled stockout risk to 10% and save USD 96400.0 versus no action.

첫 화면의 결론은 이렇다. PO000318은 전체 air 전환 대상이 아니다. 승인 callback을 받아 84개 critical kit만 split expedite로 예약하고, 나머지 336개는 기존 ocean shipment에 둔다.

2. 이번에 만든 것

scm_sap_split_expedite_approval_evaluation.py를 추가했다. 전 단계 SCM-046 action ticket을 받아 operator approval callback, no-action 대비 평가 보드, REBEC shadow ledger, order casefile을 한 번에 만든다.

외부 SAP write는 여전히 false다. 이번 단계는 실제 SAP 변경이 아니라 승인된 액션을 실행 전에 shadow ledger로 닫고 비용과 리스크를 비교하는 evaluation harness다.

3. callback을 어떻게 처리했나

callback id는 CB-PO000318-APPROVE-SPLIT-20260503-0104이고 decision은 approved_with_guardrails이다. premium freight cap은 USD 20000이고 전체 air 전환은 금지했다.

4. no-action 대비 평가

평가식은 expected_total_cost = incremental_cost + stockout_probability * line_stop_cost다. line-stop cost는 synthetic 값 USD 410000으로 두었다.

SCN-PO000318-NO-ACTION: reject, 잔여 stockout 38%, 예상 late 1.8일, 추가 비용 $0, 기대 총비용 $155800.0. 승인 packet을 실행하지 않고 기존 ocean monitoring만 유지한다.
SCN-PO000318-SPLIT-EXPEDITE-20PCT: selected, 잔여 stockout 10%, 예상 late 0.2일, 추가 비용 $18400, 기대 총비용 $59400.0. 84 critical kits를 split expedite로 예약하고 336 kits는 ocean에 둔다.
SCN-PO000318-FULL-AIR: reserve_only, 잔여 stockout 4%, 예상 late 0.0일, 추가 비용 $76500, 기대 총비용 $92900.0. 420 kits 전체를 air expedite로 전환한다.
SCN-PO000318-PLANT-REBALANCE: fallback, 잔여 stockout 19%, 예상 late 0.7일, 추가 비용 $9200, 기대 총비용 $87100.0. Plant-MX-01 buffer를 Plant-US-02로 임시 재배정한다.

선택된 시나리오는 SCN-PO000318-SPLIT-EXPEDITE-20PCT다. 모델상 절감액은 USD 96400.0다.

5. REBEC shadow ledger

operator_callback_consumer: approval_decision_received - approved_with_guardrails
action_simulator: simulate_post_approval_execution - capacity reservation simulated for 84 critical kits
evaluation_board: outcome_candidates_scored - net expected savings USD 96400.0
sap_shadow_ledger: shadow_event_appended - no external SAP write; human execution packet remains required

ledger가 실행 결과가 아니라 실행 전 안전장치라는 점이 핵심이다. 외부 SAP write는 하지 않았다.

6. 실패한 것과 조심할 점

실제 TMS booking confirmation은 아직 없다. 그래서 2026-05-14T10:00:00-07:00 split ETA는 실행 결과가 아니라 simulation이다.

UNCTAD, WTO, IMF 신호는 macro pressure다. 이 신호만으로 lane closure를 판정하지 않았고 승인 평가의 배경 신호로만 썼다.

7. 다음에 붙일 것

다음 단계는 human execution handoff packet을 만들거나, booking confirmation이 들어온 뒤 simulated ETA와 실제 ETA를 비교해 evaluation score를 갱신하는 것이다.

실행 로그 첨부

민감 경로와 내부 식별자는 마스킹한 공개용 아티팩트만 아래에 첨부한다.

scm-047-run-public.json
scm-047-publish-check-public.json
scm-047-official-signal-boundary-public.json
scm-047-approval-callback-event-public.json
scm-047-split-expedite-evaluation-board-public.json
scm-047-shadow-action-ledger-public.json
scm-047-order-casefile-public.json
scm-047-summary-public.json
scm-047-official-signal-verification-public.md
scm-047-split-expedite-approval-evaluation-spec-public.md
scm-sap-split-expedite-approval-evaluation-public.py

scm-047-run-public.json

scm-047-publish-check-public.json

scm-047-official-signal-boundary-public.json

scm-047-approval-callback-event-public.json

scm-047-split-expedite-evaluation-board-public.json

scm-047-shadow-action-ledger-public.json

scm-047-order-casefile-public.json

scm-047-summary-public.json

scm-047-official-signal-verification-public.md

scm-047-split-expedite-approval-evaluation-spec-public.md

scm-sap-split-expedite-approval-evaluation-public.py

0.04MB

OpenAI Structured Outputs 사용 기준: JSON 모드보다 strict schema·refusal·검증 실패 처리를 먼저 잠가야 한다

이천재 — Sat, 2 May 2026 18:15:35 +0900

OpenAI API 응답을 서비스 코드에 바로 넣을 계획이라면 첫 질문은 "JSON으로 받을 수 있나"가 아니다. 코드가 기대하는 key, type, enum, 실패 branch가 고정되어 있는지가 먼저다. JSON mode는 JSON 파싱 문제를 줄여 주지만, 원하는 schema와 맞는다는 뜻은 아니다.

2026-05-02 기준 OpenAI 공식 문서로 보면 기본 선택지는 분명하다. 사용자가 보는 답변 자체를 구조화해야 하면 Structured Outputs를 보고, 외부 시스템에서 환불, 검색, 업데이트 같은 action을 실행해야 하면 function calling으로 분리한다. Responses API에서는 Structured Outputs를 text.format으로 정의한다.

짧게 정리하면 이렇다.

특정 schema가 필요한 추출, 분류, UI payload는 JSON mode보다 Structured Outputs를 먼저 본다.
JSON mode를 써야 하는 경우에도 local validation, retry, fail-closed branch를 둔다.
모든 field는 required로 두고, optional은 ["string", "null"] 같은 nullable union으로 표현한다.
모든 object에 additionalProperties: false를 넣는다.
root schema는 object여야 하며 root anyOf를 피한다.
refusal, incomplete output, content filter는 schema parser 앞에서 먼저 분기한다.
외부 action은 Structured Outputs answer payload가 아니라 function calling contract로 분리한다.

JSON 파싱과 schema 계약은 다르다

OpenAI Structured Outputs guide는 Structured Outputs를 supplied JSON Schema에 맞는 model response를 만들기 위한 기능으로 설명한다. 이 기능의 쟁점은 "중괄호가 닫혔는가"가 아니라 "내 코드가 기대하는 구조를 지키는가"다.

JSON mode는 더 기본적인 기능이다. OpenAI docs는 JSON mode가 valid JSON을 보장하지만 특정 schema와 맞는지는 보장하지 않는다고 설명한다. 따라서 invoice 추출에서 invoice_id, total, currency를 기대했는데 unexpected_note가 붙거나 currency가 빠져도, JSON mode 관점에서는 여전히 valid JSON일 수 있다.

production parser 앞에서는 이 차이가 크다.

선택지	맞는 상황	남는 일
JSON mode	단순 JSON 형태만 필요하거나 Structured Outputs를 못 쓰는 경우	schema validation, retry, incomplete/refusal 처리
Structured Outputs	응답 key와 type을 고정해야 하는 추출, 분류, UI payload	schema preflight, refusal branch, business validation
Function calling	외부 tool, DB, 결제, 환불, 검색 action이 필요한 경우	tool output과 `call_id` correlation, side effect 제어

즉 "JSON으로 줘"라는 prompt는 계약이 아니다. 계약은 schema와 실패 처리에서 만들어진다.

Responses API에서는 text.format을 본다

기존 Chat Completions 예제를 보면 response_format을 기억하는 사람이 많다. 하지만 OpenAI migration guide는 Responses API에서 Structured Outputs 정의가 response_format에서 text.format으로 이동했다고 설명한다.

새 프로젝트라면 이 경계를 먼저 맞춰 두는 편이 낫다. Responses API는 tool call, reasoning item, message item처럼 output을 여러 item으로 다룬다. 여기에 structured answer를 붙일 때는 text.format 쪽으로 schema를 넣는다.

반대로 외부 action은 다른 문제다. OpenAI docs는 tool, function, application data에 모델을 연결하려면 function calling을 쓰고, 사용자에게 줄 답변 자체를 구조화하려면 structured output을 쓰는 식으로 나눈다. 환불 실행, 계정 조회, 내부 문서 검색 같은 작업을 단순 structured answer로 처리하면 side effect와 audit trail이 흐려진다.

schema는 API 호출 전에 막아야 한다

이번 local gate에서 10개 scenario를 만들었다. OpenAI API는 호출하지 않았다. 공식 문서의 Structured Outputs 제한을 preflight rule로 바꾸고, 각 schema가 parser 앞까지 갈 수 있는지 확인했다.

가장 흔한 실패는 optional field였다. Structured Outputs에서는 모든 field 또는 function parameter가 required여야 한다. optional 값을 표현하려면 field를 빼는 것이 아니라 null을 허용하는 union으로 설계해야 한다.

예를 들어 아래처럼 due_date를 properties에는 넣고 required에서 빼면 gate가 막는다.

{
  "type": "object",
  "properties": {
    "title": { "type": "string" },
    "owner": { "type": "string" },
    "due_date": { "type": ["string", "null"] }
  },
  "required": ["title", "owner"],
  "additionalProperties": false
}

수정 방향은 단순하다. due_date도 required에 넣고 값이 없을 때 null을 받는다.

root anyOf와 additionalProperties를 먼저 확인한다

Zod나 Pydantic을 쓰더라도 generated schema가 OpenAI subset에 맞는지는 따로 봐야 한다. OpenAI docs는 root schema가 object여야 하며 root anyOf는 사용할 수 없다고 설명한다. Zod discriminated union을 그대로 response format으로 변환하면 top-level anyOf가 나오는 경우가 있어 preflight에서 막아야 한다.

또 하나는 additionalProperties: false다. OpenAI docs는 Structured Outputs가 지정된 key/value만 생성하는 방식을 지원하므로 object에 이 설정을 요구한다고 설명한다. 이 설정이 없으면 "모델이 extra key를 만들었을 때 어떻게 할지"가 모호해진다.

이번 gate에서는 missing-additional-properties scenario가 API 호출 전 blocked됐다. schema가 간단해도 이 설정이 빠지면 production parser 앞에서 실패하는 편이 맞다. API까지 보내고 에러를 받는 것보다 CI나 local preflight에서 막는 쪽이 운영하기 쉽다.

schema 크기와 enum은 실제 장애가 된다

Structured Outputs는 많은 JSON Schema 기능을 지원하지만 무제한은 아니다. OpenAI docs는 schema에 총 5,000 object properties, 10 levels nesting, 120,000 characters string budget, 1,000 enum values 제한이 있다고 설명한다. 단일 string enum이 250개를 넘으면 enum values 전체 string length 15,000 characters 제한도 붙는다.

이번 gate에서 두 가지가 걸렸다.

scenario	막힌 이유	먼저 할 일
`deep-analytics-payload`	12단계 nested object	payload를 단계별 schema로 쪼개거나 UI state를 별도 object로 분리
`large-enum-catalog`	SKU enum 1,100개	enum을 줄이거나 tool lookup, 검색, 후처리 검증으로 분리

큰 schema는 모델보다 운영 코드에서 먼저 무너진다. 타입 정의와 JSON Schema가 어긋나고, enum이 제품 catalog 변경을 따라가지 못하고, UI payload가 한 번에 너무 많은 일을 하게 된다. OpenAI docs도 schema와 programming language type divergence를 막기 위해 Pydantic/Zod SDK support나 CI rule을 권장한다.

fine-tuned model에는 keyword 제한이 더 붙는다

Structured Outputs guide에는 supported keyword와 unsupported keyword가 나뉘어 있다. composition 쪽에서는 allOf, not, dependentRequired, dependentSchemas, if, then, else가 지원되지 않는다고 설명한다.

fine-tuned model에서는 제한이 더 늘어난다. docs는 strings의 minLength, maxLength, pattern, format, numbers의 minimum, maximum, multipleOf, objects의 patternProperties, arrays의 minItems, maxItems 등을 추가로 지원하지 않는다고 설명한다.

이번 gate의 fine-tuned-regex-user scenario는 username에 pattern, minLength, email에 format을 둔 schema였다. base model 기준 예시에서는 이런 keyword를 볼 수 있지만, fine-tuned model 조건에서는 blocked로 처리했다.

여기서 결론은 "정규식을 쓰지 말라"가 아니다. 모델 출력 schema에 모든 검증을 맡기지 말라는 쪽에 가깝다. 계정명, 이메일, SKU, 금액 범위 같은 business validation은 Structured Outputs 뒤의 application validator에도 남겨야 한다.

refusal은 schema parser 앞에서 분기한다

Structured Outputs를 켜도 모든 응답이 supplied schema 그대로 오는 것은 아니다. OpenAI docs는 user-generated input에서 safety refusal이 생길 수 있고, refusal은 supplied response_format schema를 따르지 않을 수 있다고 설명한다. Responses API JSON mode 예시도 refusal content type과 incomplete output을 별도로 확인한다.

이 branch를 parser 뒤에 두면 장애가 난다. parser는 category, priority, summary를 기다리는데 실제 content가 refusal이면, 사용자는 안전 거절을 받은 것이 아니라 "응답 파싱 실패"를 보게 된다.

처리 순서는 이렇다.

API response status가 incomplete인지 본다.
content type이 refusal인지 본다.
content filter나 max output token으로 잘렸는지 본다.
그 다음에 structured JSON을 parse한다.
business rule validation을 별도로 통과시킨다.

이번 gate의 refusal-sensitive-request는 schema 자체는 valid였지만 route가 ready_but_needs_refusal_branch로 잡혔다. schema가 맞아도 parser 앞 branch가 없으면 아직 production-ready가 아니다.

user input이 schema와 안 맞을 때도 정해야 한다

OpenAI docs는 user-generated input이 schema와 호환되지 않을 때 모델이 schema를 맞추려다 hallucination할 수 있다고 설명한다. 예를 들어 "이 글에서 환불 사유를 뽑아줘"라고 했는데 글 안에 환불 정보가 없으면, 모델이 빈 값을 넣을지, null을 넣을지, "정보 없음"을 넣을지 정해야 한다.

이 부분은 schema만으로 해결되지 않는다. prompt에 incompatible input 처리 규칙을 넣고, schema에도 null, empty array, unknown enum처럼 실패를 표현할 자리를 만들어야 한다. 그래도 최종 business validation은 남긴다.

Structured Outputs는 parser를 덜 흔들리게 해준다. 하지만 입력이 작업과 맞지 않는 문제, safety refusal, partial output, 업무 규칙 위반까지 없애지는 않는다.

로컬 gate 결과

이번 run은 OpenAI API를 호출하지 않았다. live model reliability를 측정한 것도 아니다. 공식 문서의 schema subset과 response handling 조건을 deterministic planning gate로 바꿔 10개 scenario를 평가했다.

scenario	score	route	primary action
`support-ticket-strict`	100	`ready_strict_structured_output`	`use_structured_outputs_with_strict_schema`
`json-mode-invoice`	72	`json_mode_requires_validator_retry`	`prefer_structured_outputs_or_add_local_validation_and_retry`
`optional-field-not-required`	62	`blocked_schema_before_api`	`fix_schema_subset_before_calling_api`
`root-discriminated-union`	62	`blocked_schema_before_api`	`fix_schema_subset_before_calling_api`
`missing-additional-properties`	62	`blocked_schema_before_api`	`fix_schema_subset_before_calling_api`
`deep-analytics-payload`	54	`blocked_schema_before_api`	`fix_schema_subset_before_calling_api`
`large-enum-catalog`	52	`blocked_schema_before_api`	`fix_schema_subset_before_calling_api`
`fine-tuned-regex-user`	56	`blocked_schema_before_api`	`fix_schema_subset_before_calling_api`
`refusal-sensitive-request`	88	`ready_but_needs_refusal_branch`	`branch_refusal_before_schema_parser`
`refund-action-tool`	100	`function_calling_tool_contract`	`use_function_calling_for_external_action`

결과는 단순했다. schema가 valid인지, JSON이 parse되는지, refusal을 처리하는지, 외부 action인지가 모두 다른 gate였다. 이 네 가지를 한 parser 함수에 몰아넣으면 장애 원인을 구분하기 어렵다.

구현 전 체크리스트

OpenAI Structured Outputs를 붙이기 전에 아래를 먼저 본다.

결과가 사용자에게 보여줄 structured answer인가, 외부 action을 실행할 tool call인가.
Responses API라면 text.format으로 Structured Outputs를 정의했는가.
JSON mode를 쓰는 이유가 명확한가. Structured Outputs를 쓸 수 있다면 그쪽이 먼저인가.
root schema가 object이고 root anyOf가 없는가.
모든 field가 required인가.
optional 값은 nullable union으로 표현했는가.
모든 object에 additionalProperties: false가 있는가.
schema가 5,000 properties, 10 depth, 120,000 string budget, enum limit 안에 있는가.
fine-tuned model에서 지원하지 않는 keyword를 schema에 넣지 않았는가.
refusal과 incomplete output을 parser 전에 분기하는가.
user input이 schema와 맞지 않을 때 null, empty array, unknown enum, refusal 중 어떤 경로로 처리할지 정했는가.
schema와 app type이 갈라지지 않도록 Pydantic/Zod helper, code generation, CI check 중 하나를 쓰는가.
Structured Outputs 뒤에도 business validation을 남겨 두었는가.

이 중 4번부터 9번은 API 호출 전 gate로 막을 수 있다. 10번부터 13번은 runtime branch다. 둘을 나눠 두면 실패가 훨씬 빨리 보인다.

같이 보면 좋은 글

참고 자료

실행 로그 첨부

민감정보를 제거한 공개용 로그와 실험 스크립트만 아래에 첨부한다.

wn118-structured-outputs-schema-gate-public.json
wn118-structured-outputs-schema-gate-summary-public.md
wn118-structured-outputs-schema-gate-public.py

wn118-structured-outputs-schema-gate-public.json

0.05MB

wn118-structured-outputs-schema-gate-summary-public.md

wn118-structured-outputs-schema-gate-public.py

wn117-file-search-vector-store-gate-public.json

OpenAI File Search 사용 기준: Vector Store 비용·만료·청킹을 먼저 잠가야 RAG 운영이 덜 흔들린다

이천재 — Fri, 1 May 2026 21:32:16 +0900

OpenAI File Search를 붙일 때 첫 질문은 "RAG를 직접 만들까, API tool을 쓸까"가 아니다. 같은 문서를 반복해서 검색할 것인지, 그 문서를 며칠 보관할 것인지, 파일이 제한 안에 들어오는지, 검색 결과를 나중에 감사할 수 있어야 하는지가 먼저다.

2026-05-01 기준 OpenAI 공식 문서로 보면 경계는 꽤 분명하다. File Search는 Responses API에서 쓰는 hosted tool이다. Vector Store는 그 tool이 검색할 수 있도록 파일을 chunking, embedding, indexing해 두는 저장/index layer다. 반복 질의가 있는 문서 지식베이스라면 Vector Store가 맞다. 반대로 회의록 파일 하나를 두 번 요약하는 작업이라면 persistent Vector Store를 만드는 게 오히려 운영 부담이 될 수 있다.

짧게 정리하면 이렇다.

자주 검색할 제품 문서, FAQ, 정책 문서는 File Search + Vector Store부터 본다.
한두 번 읽고 끝나는 파일은 prompt context, file input, 별도 임시 처리로 충분한지 먼저 본다.
Vector Store를 만들기 전에 storage 비용, tool call 비용, model token 비용을 분리해서 계산한다.
임시 store는 expires_after를 잡고, 오래 사는 store는 stale file review와 cost owner를 둔다.
업로드 전 파일당 512 MB, 5,000,000 tokens, batch 500 files, chunk overlap 제한을 확인한다.
검색 품질을 확인해야 하면 include=["file_search_call.results"]와 작은 max_num_results부터 쓴다.
테넌트, 지역, 문서 종류를 나눠야 하면 ingestion 단계에서 attributes와 filter key를 먼저 설계한다.

File Search는 tool이고 Vector Store는 저장소다

OpenAI File Search guide는 File Search를 Responses API에서 사용할 수 있는 tool로 설명한다. model이 답변을 만들기 전에 vector store에 있는 파일을 semantic search와 keyword search로 찾아볼 수 있게 해준다. 직접 검색 executor를 구현하지 않아도 되는 hosted tool이라는 점이 장점이다.

다만 File Search만 켠다고 문서 검색 시스템이 완성되는 것은 아니다. Retrieval guide는 vector store를 semantic search index로 설명한다. 파일을 vector store에 추가하면 OpenAI 쪽에서 chunking, embedding, indexing을 처리한다. 이 말은 곧 저장 수명, 파일 크기, chunk 설정, metadata, 비용을 운영자가 먼저 정해야 한다는 뜻이다.

간단히 나누면 이렇다.

구분	역할	먼저 볼 질문
File Search	Responses API에서 모델이 호출하는 검색 tool	답변 전에 파일 검색이 필요한가
Vector Store	검색 가능한 파일 index와 storage	어떤 파일을 얼마나 오래 저장할 것인가
Vector store file	원본 file을 store에 붙인 indexed wrapper	metadata, chunking, batch 상태가 맞는가
Direct file/prompt 처리	persistent index 없이 한 번 처리	반복 검색 없이 끝나는가

그래서 "문서가 있다"는 이유만으로 Vector Store를 만들면 안 된다. 문서를 반복해서 검색하고, 결과를 citation과 함께 답변에 넣고, 나중에 같은 store를 재사용할 때 가치가 커진다.

한 번 볼 파일이면 Vector Store가 과할 수 있다

이번 local gate에서 one-off-board-minutes scenario는 persistent Vector Store가 아니라 direct_file_or_prompt_context route로 분리했다. 0.02 GB 파일 하나를 하루 동안 두 번만 볼 예정이었기 때문이다. 비용 estimate 자체는 작았지만, index를 만들고 만료를 관리하고 결과 품질을 확인하는 운영 비용이 더 크다고 봤다.

반대로 temporary-support-faq는 7일짜리 FAQ 초안이었지만 File Search + Vector Store route로 갔다. 42개 파일을 일주일 동안 280회 검색할 예정이었고, 답변 근거를 확인해야 했기 때문이다. 이런 경우는 storage free tier 안에 들어가더라도 tool call cost와 결과 inspection을 같이 봐야 한다.

이 차이는 실제 구현에서 자주 놓친다. "RAG니까 vector store"가 아니라 "같은 지식을 여러 번 검색하고 관리할 필요가 있는가"가 기준이다.

비용은 storage와 tool call을 나눠서 본다

OpenAI pricing page는 File Search storage를 $0.10 / GB per day (1 GB free), tool call을 $2.50 / 1k calls로 설명한다. 또 built-in tools에 쓰인 token은 선택한 model의 token rate로 과금된다는 note가 있다.

즉 비용은 적어도 세 갈래로 봐야 한다.

항목	무엇을 뜻하나	운영자가 할 일
storage	vector store에 저장된 parsed chunks와 embeddings	보관 기간과 삭제 정책을 정한다
tool call	File Search tool 호출 횟수	기능별 호출량을 로그로 남긴다
model token	검색 결과가 model context에 들어가 답변을 만들 때의 token	`max_num_results`와 응답 길이를 조절한다

이번 gate의 evergreen-product-docs scenario는 8.0 GB corpus, 350 calls/day, 30일 retention으로 estimate했다. storage estimate는 $21.00, tool call estimate는 $26.25, 합계는 $47.25였다. 이 숫자는 실제 청구서가 아니다. OpenAI 문서도 storage가 parsed chunks와 embeddings 기준이라고 설명하므로, local gate는 운영자가 사전 budget을 잡기 위한 planning approximation이다.

작은 store도 공짜라고 보면 안 된다. temporary-support-faq는 0.35 GB라 storage는 free tier 안에 있었지만 7일 동안 280번 호출되면 tool call estimate가 $0.70으로 남았다. 규모가 작을 때는 큰돈이 아니어도, 기능이 여러 개로 늘어나면 call 수가 먼저 튄다.

임시 store는 expires_after를 먼저 넣는다

Retrieval guide는 vector store에 expires_after expiration policy를 설정할 수 있다고 설명한다. vector store가 expire되면 associated vector_store.file objects가 삭제되고 더 이상 charge되지 않는다.

이 옵션은 "나중에 정리하자"로 미루면 잘 안 된다. 실험용 문서, 고객사 PoC 문서, 캠페인 FAQ처럼 수명이 짧은 corpus는 만들 때부터 만료를 넣어야 한다. 이번 gate에서도 short-lived scenario는 checklist에 set expires_after last_active_at N days를 넣었다.

오래 사는 제품 문서 store는 다르게 봐야 한다. 자동 만료를 짧게 잡으면 필요한 문서가 사라질 수 있다. 대신 stale file review, owner, budget threshold, 재색인 주기를 따로 둔다. File Search가 hosted tool이어도 지식베이스 운영 책임까지 사라지는 것은 아니다.

업로드 전 파일과 batch 제한을 막아야 한다

Retrieval guide는 파일당 최대 512 MB, 5,000,000 tokens 제한을 설명한다. 또한 vector store file batches는 최대 500개 파일을 한 요청에 넣을 수 있다.

이번 gate에서 세 가지 scenario가 ingestion 전에 막혔다.

scenario	막힌 이유	먼저 할 일
`oversized-pdf`	640 MB PDF가 512 MB file limit을 넘음	파일 분할, 원본 압축, 필요한 장만 추출
`huge-token-contract`	한 파일이 6,000,000 tokens로 5M token limit을 넘음	문서 단위 분리, appendix 분리, ingestion 전 token estimate
`bad-static-chunking`	300 token chunk에 200 token overlap 지정	overlap을 chunk size의 절반 이하로 낮춤

bulk-600-file-ingest는 blocked는 아니었지만 warning을 받았다. 한 batch에 600개 파일을 넣으려 했기 때문이다. 이 경우 최소 두 batch로 나누고, 각 batch 상태를 polling하거나 실패 파일을 따로 재시도해야 한다.

이 gate는 단순하지만 중요하다. upload를 먼저 시도한 뒤 에러를 읽는 방식은 자동화에서 비싸다. 파일 크기, token estimate, batch size, chunk setting은 upload 전 validator로 막는 편이 낫다.

청킹은 품질 knob이면서 비용 knob이다

Retrieval guide의 default chunking은 max_chunk_size_tokens=800, chunk_overlap_tokens=400이다. chunking_strategy로 조정할 수 있지만 max chunk size는 100~4096 사이여야 하고, overlap은 non-negative이며 chunk size의 절반을 넘지 않아야 한다.

chunk를 작게 만들면 검색 단위가 촘촘해질 수 있다. 대신 chunk 수가 늘고, overlap이 크면 같은 내용이 여러 chunk에 반복된다. 반대로 chunk를 너무 크게 만들면 문맥은 넓어지지만 필요한 문장만 정확히 뽑기 어려울 수 있다.

이번 gate는 largest file 기준 chunk estimate도 남겼다. evergreen-product-docs의 largest file은 650,000 tokens였고 default 800/400 설정에서 1,624 chunks로 추정됐다. 이 역시 OpenAI 내부 처리 결과가 아니라 planning estimate다. 하지만 "문서 하나가 대략 몇 검색 단위로 쪼개질지"를 업로드 전에 보는 데에는 충분하다.

metadata filter는 ingestion 전에 설계한다

File Search guide는 metadata filtering 예시를 제공하고, Retrieval guide는 vector store file에 attributes를 붙여 semantic search filtering에 사용할 수 있다고 설명한다. 이 기능은 테넌트, 국가, 문서 종류, 제품 버전이 섞이는 순간 중요해진다.

예를 들어 같은 store에 한국 정책, 미국 정책, 일본 정책 문서가 같이 들어가는데 filter key가 없다면, 질문은 한국어여도 검색 결과가 다른 지역 문서로 섞일 수 있다. 나중에 파일명 parsing으로 때우는 것보다 ingestion 때 attributes를 붙이는 편이 낫다.

이번 gate의 tenant-policy-kb scenario는 2.2 GB corpus, 180 calls/day, 14일 retention이었다. route는 File Search + Vector Store였지만 checklist에는 attach attributes for filter keys before ingestion을 넣었다. 이 scenario의 핵심은 storage보다 filter였다.

검색 결과를 보려면 include를 켜야 한다

File Search guide는 output text의 annotation으로 file reference를 볼 수 있지만, file search call은 search results를 기본으로 반환하지 않는다고 설명한다. 검색 결과 자체를 response에 포함하려면 include=["file_search_call.results"]를 사용해야 한다.

이 옵션은 초기에 꼭 켜 보는 편이 좋다. 답변이 맞아 보여도 실제로 어떤 chunk가 들어왔는지 모르면, hallucination인지 retrieval miss인지 prompt 문제인지 구분하기 어렵다. 다만 운영 트래픽에서 항상 full result를 저장할지는 별도 결정이다. privacy, log volume, token/cost 경계를 같이 봐야 한다.

max_num_results도 같은 맥락이다. File Search guide는 결과 수 제한이 token usage와 latency를 줄일 수 있지만 answer quality와 tradeoff가 있다고 설명한다. 처음부터 많이 가져오는 것보다 작은 값으로 시작하고, 실패 case를 보며 올리는 방식이 안전하다.

로컬 gate 결과

이번 run에서는 OpenAI API를 호출하지 않았다. 파일도 업로드하지 않았고 retrieval 품질도 측정하지 않았다. 공식 문서의 제한과 가격 조건을 deterministic planning gate로 바꿔 8개 scenario를 평가했다.

scenario	score	route	cost window USD	primary action
`temporary-support-faq`	100	`file_search_vector_store`	0.7000	`use_file_search_with_vector_store`
`evergreen-product-docs`	86	`file_search_vector_store`	47.2500	`use_file_search_with_vector_store`
`one-off-board-minutes`	88	`direct_file_or_prompt_context`	0.0050	`avoid_persistent_vector_store_for_one_off_low_reuse_task`
`tenant-policy-kb`	100	`file_search_vector_store`	7.9800	`use_file_search_with_vector_store`
`bulk-600-file-ingest`	92	`file_search_vector_store`	1.0500	`use_file_search_with_vector_store`
`oversized-pdf`	55	`blocked_before_ingestion`	0.4375	`fix_file_or_chunking_limits_before_vector_store_ingestion`
`huge-token-contract`	55	`blocked_before_ingestion`	0.5000	`fix_file_or_chunking_limits_before_vector_store_ingestion`
`bad-static-chunking`	70	`blocked_before_ingestion`	0.1125	`fix_file_or_chunking_limits_before_vector_store_ingestion`

핵심 결과는 두 가지였다. 첫째, 반복 검색과 evidence inspection이 필요한 문서는 File Search + Vector Store가 맞았다. 둘째, File Search를 쓰기로 한 뒤에도 upload 전 gate가 필요했다. 파일 크기, token 수, batch size, chunk overlap이 틀리면 retrieval 품질을 보기 전에 막힌다.

구현 전 체크리스트

OpenAI File Search를 붙이기 전에 아래 질문을 먼저 본다.

이 문서를 같은 기능에서 반복 검색하는가.
한두 번 처리하고 끝나는 파일이라면 persistent Vector Store 없이 해결할 수 있는가.
corpus size와 예상 retention으로 storage budget을 계산했는가.
예상 query call 수로 File Search tool call cost를 따로 계산했는가.
model token cost가 max_num_results와 응답 길이에 따라 늘어나는 구조를 이해했는가.
임시 corpus라면 expires_after를 만들 때 넣었는가.
오래 사는 store라면 stale file review, owner, budget threshold가 있는가.
파일당 512 MB와 5,000,000 tokens 제한을 upload 전에 확인했는가.
500개가 넘는 파일은 batch를 나눌 계획이 있는가.
static chunking을 쓴다면 chunk size와 overlap이 허용 범위 안에 있는가.
테넌트, 지역, 제품 버전, 문서 종류 filter가 필요하면 attributes를 ingestion 전에 붙였는가.
품질 점검 때 include=["file_search_call.results"]로 실제 검색 결과를 확인했는가.
운영 기본값은 작은 max_num_results에서 시작하고 실패 case를 보며 올릴 계획인가.

이 중 1번이 비어 있으면 Vector Store를 만들 이유가 약하다. 6번과 7번이 비어 있으면 비용이 새기 쉽다. 8번부터 10번이 비어 있으면 업로드 자동화가 중간에 깨질 가능성이 높다.

같이 보면 좋은 글

참고 자료

실행 로그 첨부

민감정보를 제거한 공개용 로그와 실험 스크립트만 아래에 첨부한다.

wn117-file-search-vector-store-gate-public.json
wn117-file-search-vector-store-gate-summary-public.md
wn117-file-search-vector-store-gate-public.py

wn117-file-search-vector-store-gate-summary-public.md

wn117-file-search-vector-store-gate-public.py

SCM PDF identity watch executor: PO000225 WEO PDF hash가 baseline과 일치해 watch를 clean으로 닫은 SCM-045

이천재 — Fri, 1 May 2026 16:21:38 +0900

PO000225의 WEO PDF watch는 이제 닫아도 된다. 이번에는 웹 표면만 본 것이 아니라 PDF binary까지 다시 받아 SCM-042 baseline과 맞췄다.

1. 운영자가 먼저 보는 문서 case file

문서 엔티티	연결 주문	lane	현재 문서 상태	원래 due date	외부 신호	영향 이유	아무것도 안 했을 때 결과	추천 액션	tradeoff
`DOC-WEO-2026APR-COMPILED-PDF`	`PO000225`	`PO000225 docs branch -> IMF WEO compiled PDF`	`closed_by_direct_asset_capture`; scheduled watch result `identity_match_clean`	`2026-04-30`	`2026-05-01T16:17:44+09:00` 기준 IMF direct PDF를 다시 받아 SHA-256 `5c281721761f2ac8f8ae313ea977a0039539aa760039ea3717cf54002d82432a`, byte size `8298182`, PDF magic `%PDF-1.6`, page count `180`이 `SCM-042` baseline과 모두 일치함을 확인했다	`SCM-042` baseline은 URL/date만이 아니라 binary identity까지 요구한다. 이번 비교로 same-URL silent republish 의심을 닫을 수 있다	watch verdict를 반영하지 않으면 `PO000225` docs branch가 이미 검증된 PDF를 계속 open risk로 들고 간다	`ALT-KEEP-CLOSED-AFTER-IDENTITY-MATCH`를 선택한다. watch queue를 닫고 `PO000225` 문서 branch를 닫힌 상태로 유지한다	빠르게 닫을 수 있지만, 이번 판단은 현재 PDF hash가 baseline과 같다는 범위 안에서만 유효하다. 이후 errata나 PDF 재배포가 생기면 새 watch가 필요하다

첫 화면의 결론은 분명하다. PO000225는 다시 열 일이 아니라, watch queue를 닫을 일이다.

2. 이번에 만든 것

새 실행기 scm_sap_pdf_identity_watch_executor.py를 추가했다. 이 스크립트는 SCM-042의 PDF identity baseline queue를 읽고 scheduled window 이후 현재 PDF를 다시 확인한다.

비교 항목은 아래와 같다.

direct URL
content type
PDF magic
page count
byte size
SHA-256
errata update date

처음 실행에서는 로컬 DNS 실패로 ALT-MANUAL-PDF-EVIDENCE-HOLD가 나왔다. 이번 재시도에서는 PDF binary capture가 성공했고, hash와 byte size가 baseline과 일치했다.

3. 공식 근거는 어디까지 잠갔나

공식 IMF 표면은 2026-05-01T16:17:44+09:00 기준으로 다시 확인했다.

IMF WEO issue page: 2026-04-14 URL의 April 2026 WEO page
IMF direct PDF: application/pdf, PDF version 1.6, page count 180
IMF Data WEO dataset: April 2026
IMF WEO press briefing transcript: 2026-04-14

PDF metadata도 baseline과 맞았다.

SHA-256: 5c281721761f2ac8f8ae313ea977a0039539aa760039ea3717cf54002d82432a
byte size: 8298182
PDF magic: %PDF-1.6
pdfinfo page count: 180
PDF modified date: 2026-04-22 02:49:30 KST

공식 PDF 원문은 저장하거나 첨부하지 않았다. identity metadata만 run log에 남겼다.

4. 선택한 대안

선택한 대안은 ALT-KEEP-CLOSED-AFTER-IDENTITY-MATCH다.

이 대안은 세 가지를 동시에 한다.

PO000225 docs branch를 닫힌 상태로 유지한다.
WATCH-PO000225-WEO-PDF-IDENTITY-20260430 queue를 clean verdict로 닫는다.
외부 SAP write는 하지 않고 내부 action workflow에만 결과를 기록한다.

ALT-BINARY-DELTA-REVIEW와 ALT-REOPEN-ON-ERRATA-DELTA는 이번에는 열지 않았다. SHA-256, byte size, page count, visible errata date가 baseline과 모두 같았기 때문이다.

5. REBEC 흐름

watch_scheduler -> pdf_identity_watch_executor: 2026-04-30 09:00 KST 이후 watch window가 열렸다고 전달
pdf_identity_watch_executor -> official_signal_collector: IMF issue page, PDF, data, transcript 확인
pdf_identity_watch_executor -> binary_identity_comparator: current PDF binary를 baseline과 비교
binary_identity_comparator -> sap_order_state_coordinator: 외부 SAP write 없이 keep-closed action을 기록

이 흐름의 의미는 간단하다. 이 주문은 더 이상 "PDF를 못 봐서 남은 위험"이 아니라 "PDF identity가 맞아서 닫을 수 있는 문서 branch"가 됐다.

6. 실패한 것과 조심할 점

처음 실행에서는 DNS 실패 때문에 current hash를 만들지 못했다. 그래서 manual hold가 맞았다. 이번에는 같은 PDF URL을 다시 받아 hash 비교가 성공했다.

남은 주의점은 하나다. clean verdict는 2026-05-01T16:17:44+09:00에 받은 PDF가 SCM-042 baseline과 같다는 뜻이다. 이후 IMF가 새 errata를 올리거나 같은 URL로 PDF를 다시 배포하면 새 watch를 열어야 한다.

7. 그래서 언제 끝나나

이 PO000225 WEO PDF watch arc는 여기서 끝내도 된다. SCM-037부터 이어진 "compiled PDF가 아직 안 잡혔다"는 꼬리는 SCM-045에서 hash까지 맞추고 닫혔다.

전체 SCM/SAP applied AI series는 끝이라기보다 운영 기능을 하나씩 붙이는 장기 빌드다. 다만 이 특정 IMF WEO PDF closure branch는 다음 run에서 또 끌고 갈 이유가 없다. 다음부터는 새 장애 축이나 평가/운영 자동화로 넘어가면 된다.

실행 로그 첨부

민감 경로와 내부 식별자는 마스킹한 공개용 아티팩트만 아래에 첨부한다.

scm-045-run-public.json
scm-045-publish-check-public.json
scm-045-pdf-identity-watch-result-public.json
scm-045-action-workflow-public.json
scm-045-pdf-identity-watch-casefile-public.json
scm-045-pdf-identity-watch-summary-public.json
scm-045-imf-pdf-identity-watch-verification-public.md
scm-045-pdf-identity-watch-executor-spec-public.md
scm-sap-pdf-identity-watch-executor-public.py

scm-045-run-public.json

scm-045-publish-check-public.json

scm-045-pdf-identity-watch-result-public.json

scm-045-action-workflow-public.json

scm-045-pdf-identity-watch-casefile-public.json

scm-045-pdf-identity-watch-summary-public.json

scm-045-imf-pdf-identity-watch-verification-public.md

scm-045-pdf-identity-watch-executor-spec-public.md

scm-sap-pdf-identity-watch-executor-public.py

0.03MB

OpenAI Realtime API 연결 기준: 브라우저 음성은 WebRTC, 서버 로직은 WebSocket·sideband로 나눠야 한다

이천재 — Thu, 30 Apr 2026 22:47:29 +0900

OpenAI Realtime API를 붙일 때 첫 질문은 "WebRTC가 좋나, WebSocket이 좋나"가 아니다. 마이크와 스피커가 어디에 있고, 표준 API key가 어디에 남아야 하며, 주문 조회나 정책 판단 같은 서버 로직을 누가 처리해야 하는지가 먼저다.

2026-04-30 기준 OpenAI 공식 문서로 보면 기본 경계는 꽤 분명하다. 브라우저나 모바일에서 사용자가 음성으로 대화한다면 WebRTC부터 본다. 서버 worker가 음성 스트림과 이벤트를 직접 처리한다면 WebSocket이 맞다. 전화번호로 들어오는 통화는 SIP path다. 답변 생성 없이 실시간 자막만 필요하면 speech-to-speech session이 아니라 transcription session을 따로 봐야 한다.

짧게 정리하면 이렇다.

브라우저/모바일 음성 에이전트는 WebRTC를 기본값으로 잡는다.
표준 OpenAI API key는 브라우저에 넣지 않는다. client에는 ephemeral key 또는 unified server initialization 경계를 둔다.
WebSocket은 server-to-server에 맞지만 audio buffer와 JSON event 처리를 직접 책임져야 한다.
tool 호출, 주문 조회, 내부 정책, guardrail은 client가 아니라 server sideband로 빼는 편이 안전하다.
실시간 자막만 필요하면 type=transcription session을 쓴다. 이 mode는 보통 model response를 만들지 않는다.
전화 상담처럼 phone number가 entry point라면 SIP trunk와 incoming webhook accept/reject flow를 별도로 설계한다.

Realtime API는 음성 채팅 하나만 뜻하지 않는다

OpenAI Realtime API overview는 Realtime API를 low-latency multimodal application용으로 설명한다. 음성 입력과 음성 출력만 있는 것이 아니라 audio, image, text input과 audio, text output을 다룰 수 있고, realtime audio transcription에도 쓰인다.

그래서 "Realtime API를 쓴다"는 말만으로는 구현 방식이 정해지지 않는다. 브라우저에서 바로 음성 대화를 만들 수도 있고, 서버에서 WebSocket으로 event를 처리할 수도 있다. 전화망에서 들어오는 call을 SIP로 받을 수도 있고, 모델 답변 없이 transcript만 stream할 수도 있다.

문제는 이 네 가지를 한 코드 path에 섞을 때 생긴다. 브라우저 데모에서 편하다는 이유로 표준 API key를 넣거나, WebSocket으로 서버를 만들면서 base64 audio buffer 처리를 빼먹거나, transcription-only 요구사항에 speech-to-speech session을 붙이면 나중에 고치기 어렵다.

브라우저 음성은 WebRTC부터 본다

OpenAI WebRTC guide는 browser나 mobile client가 Realtime model에 연결할 때 WebSocket보다 WebRTC를 권장한다. 이유는 단순하다. 브라우저의 microphone input, remote audio playback, peer connection, data channel이 모두 WebRTC의 영역에 있다.

WebRTC path에도 두 가지 초기화 방식이 있다.

방식	흐름	조심할 점
ephemeral key	서버가 `/v1/realtime/client_secrets`로 short-lived key를 만들고 browser가 SDP를 Realtime API에 보낸다	key 발급 endpoint와 session config를 서버에서 관리해야 한다
unified interface	browser가 SDP를 app server에 보내고 server가 session config와 함께 `/v1/realtime/calls`에 보낸다	구현은 단순해지지만 session initialization에 서버가 critical path가 된다

둘 중 무엇을 고르든 표준 API key를 browser에 넣으면 안 된다. Realtime API reference도 client secret은 client-side environment에서 쓰는 ephemeral key이고, standard API token은 server-side only라고 설명한다. 같은 reference는 현재 client secret token expiry를 one minute로 설명한다. 이 숫자는 변할 수 있으니 배포 전 다시 확인해야 하지만, 구조상 "브라우저에 오래 살아 있는 비밀값을 둔다"는 설계는 맞지 않다.

서버 worker는 WebSocket이 맞다

WebSocket guide는 server-to-server Realtime integration에 WebSocket이 좋은 선택이라고 설명한다. backend system이 Realtime API에 직접 WebSocket으로 연결하고, 표준 API key는 secure backend server에만 남긴다.

대신 WebSocket은 낮은 수준의 인터페이스다. Realtime conversations guide는 WebRTC가 audio send/receive에 필요한 media handling을 많이 도와주지만, WebSocket audio는 input audio buffer에 base64-encoded audio를 직접 보내야 한다고 설명한다. 즉 서버 worker를 만들려면 event loop, reconnect, audio chunk append, commit, response event 처리까지 운영 코드가 가져가야 한다.

간단히 나누면 이렇게 된다.

상황	먼저 볼 path
사용자가 브라우저에서 말하고 바로 듣는다	WebRTC
backend가 call audio stream을 받아 모델 event를 직접 처리한다	WebSocket
browser media는 직접 연결하되 tool 실행은 서버에 둔다	WebRTC + sideband
전화번호로 들어오는 통화를 받는다	SIP
모델 답변 없이 transcript만 필요하다	Realtime transcription

WebSocket을 고르면 "서버니까 안전하다"에서 끝나지 않는다. audio buffer를 어떻게 append하고 commit할지, response.create를 언제 보낼지, response.done과 usage를 어디에 기록할지 정해야 한다.

tool과 내부 정책은 sideband로 분리한다

브라우저에 WebRTC를 붙였다고 해서 모든 로직을 브라우저에 둬야 하는 것은 아니다. Server controls guide는 client가 WebRTC나 SIP로 Realtime API server에 직접 연결하더라도 tool use와 business logic은 application server에 남기는 것이 좋다고 설명한다. 이를 위해 sideband control channel을 둔다.

Sideband는 같은 Realtime session에 두 개의 연결이 붙는 구조다. 하나는 사용자의 client connection이고, 다른 하나는 application server connection이다. 서버 connection은 session을 monitor하고, instructions를 업데이트하고, tool call에 응답할 수 있다.

이 경계는 실제 서비스에서 중요하다. 예를 들어 브라우저 voice agent가 "내 주문 상태 알려줘"라는 요청을 받는다고 하자. 음성 media 자체는 WebRTC가 처리해도 된다. 하지만 주문 DB credential, policy rule, refund 가능 여부 판단은 browser code에 두면 안 된다. client에는 음성 UX를 맡기고, 서버 sideband가 tool call을 받아 검증한 뒤 결과만 session에 돌려주는 구조가 더 낫다.

실시간 자막만 필요하면 transcription session이다

Realtime transcription guide는 transcription-only use case를 따로 설명한다. 마이크나 file input에서 realtime subtitles나 transcripts를 만들 수 있지만, transcription-only mode에서는 model response를 생성하지 않는다. session type도 transcription이다.

이 말은 구현 선택에서 꽤 큰 차이를 만든다. 회의 화면에 실시간 자막만 띄우려는 기능에 speech-to-speech assistant를 붙이면 불필요한 response event와 비용 경계가 생긴다. 반대로 상담 봇처럼 사용자의 말을 듣고 답변까지 해야 하는 경우라면 transcription-only session만으로는 부족하다.

OpenAI docs는 transcription session에서 conversation.item.input_audio_transcription.delta와 conversation.item.input_audio_transcription.completed event를 받을 수 있다고 설명한다. gpt-4o-transcribe와 gpt-4o-mini-transcribe는 incremental transcript를 stream할 수 있고, whisper-1은 delta event에도 full turn transcript가 들어간다고 설명한다.

전화번호가 출발점이면 SIP다

전화 상담처럼 phone number가 entry point라면 WebRTC와 WebSocket만으로는 부족하다. SIP guide는 SIP trunking provider를 통해 phone call을 IP traffic으로 바꾸고, OpenAI SIP endpoint와 incoming call webhook을 연결하는 흐름을 설명한다.

핵심은 inbound call을 webhook으로 받고, call_id를 기준으로 accept 또는 reject를 결정한다는 점이다. accept할 때 model, voice, instructions 같은 Realtime session config를 넘긴다. 세션이 열린 뒤에는 usual monitoring path를 붙일 수 있다.

SIP는 "브라우저 음성 에이전트를 전화로도 열어두자" 정도의 작은 옵션이 아니다. 번호 구매, carrier, webhook 검증, accept/reject 정책, hangup, monitoring이 같이 들어간다. 이 글의 local router도 incoming phone support scenario는 별도 sip route로 분리했다.

비용은 연결이 아니라 Response에서 주로 갈린다

Realtime costs guide는 현재 network bandwidth나 connection 자체 비용은 없고, Response가 생성될 때 input/output token 기준으로 비용이 발생한다고 설명한다. 또 Realtime conversation에서는 이전 turn의 item들이 다음 Response의 input으로 들어가므로 뒤 turn이 더 비싸질 수 있다.

그래서 연결 방식만 바꾼다고 비용 문제가 끝나지 않는다. WebRTC든 WebSocket이든 사용자가 계속 대화하고 Response가 계속 만들어지면 usage가 쌓인다. 비용을 보려면 response.done event의 usage를 저장하고, session이 길어질 때 어떤 context를 유지할지 따로 정해야 한다.

또 하나의 작은 함정은 voice 설정이다. API reference는 model이 audio output을 한 번 낸 뒤에는 그 session에서 voice를 변경할 수 없다고 설명한다. 운영 UI에서 voice를 바꾸게 하려면 첫 audio output 전에 설정을 끝내거나 새 session을 열어야 한다.

로컬 routing gate 결과

이번 run에서는 OpenAI API를 실제 호출하지 않았다. 마이크도 열지 않았고, WebRTC peer connection이나 SIP trunk도 만들지 않았다. 대신 공식 문서의 연결 조건을 deterministic routing gate로 바꿔 8개 scenario를 평가했다.

scenario	score	route	recommendation
`browser-voice-agent`	100	`webrtc`	`use_webrtc_with_ephemeral_or_unified_server_initialization`
`browser-voice-agent-with-order-tool`	95	`webrtc_plus_sideband`	`use_webrtc_for_media_and_sideband_for_private_tool_control`
`backend-audio-worker`	100	`websocket`	`use_server_to_server_websocket`
`backend-worker-no-audio-buffer`	82	`websocket`	`use_server_to_server_websocket`
`live-caption-browser`	100	`realtime_transcription`	`use_realtime_transcription_session_without_model_response`
`public-demo-leaks-standard-key`	30	`webrtc`	`fix_blockers_before_realtime`
`incoming-phone-support`	100	`sip`	`use_sip_with_webhook_accept_reject_and_optional_sideband`
`next-day-podcast-transcript`	85	`not_realtime`	`use_non_realtime_audio_transcription_or_batch_pipeline`

가장 중요한 blocker는 public-demo-leaks-standard-key였다. 브라우저에서 표준 API key를 쓰는 설계는 WebRTC와 WebSocket을 비교하기 전에 막아야 한다. backend-worker-no-audio-buffer는 WebSocket route로 남았지만, base64 audio buffer 처리가 없어서 warning을 받았다.

반대로 browser-voice-agent-with-order-tool은 WebRTC가 틀린 것이 아니었다. media path는 WebRTC가 맞지만, 주문 조회 tool과 내부 정책은 sideband server control로 분리해야 했다. 같은 Realtime API라도 media plane과 control plane을 나눠야 한다는 뜻이다.

구현 전 체크리스트

OpenAI Realtime API를 붙이기 전에 아래 질문을 먼저 본다.

사용자가 브라우저나 모바일에서 마이크와 스피커를 직접 쓰는가.
client에 표준 API key가 들어가지 않는 구조인가.
ephemeral key 또는 unified interface를 발급하는 server endpoint가 있는가.
서버가 직접 audio stream과 event를 처리해야 한다면 WebSocket audio buffer 처리가 준비됐는가.
tool, DB credential, policy rule, guardrail이 client code에 들어가지 않는가.
WebRTC/SIP direct session에 server control이 필요하면 sideband를 설계했는가.
답변 생성이 필요한가, transcript만 필요한가.
transcript-only라면 type=transcription session과 delta/completed event 처리를 따로 잡았는가.
전화번호가 entry point라면 SIP trunk, incoming webhook, accept/reject policy가 있는가.
response.done usage를 저장하고 session이 길어질 때 비용이 늘어나는 구조를 이해했는가.
voice를 session 중간에 바꿔야 하는 UI라면 첫 audio output 전 설정 또는 새 session 정책을 정했는가.

이 중 2번이 비어 있으면 구현을 멈추는 편이 낫다. 4번이 비어 있으면 WebSocket은 아직 이르다. 5번과 6번이 비어 있으면 voice demo는 돌아가도 실제 서비스의 tool 실행 경계가 흔들린다.

같이 보면 좋은 글

참고 자료

실행 로그 첨부

민감정보를 제거한 공개용 로그와 실험 스크립트만 아래에 첨부한다.

wn116-realtime-connection-router-public.json
wn116-realtime-connection-router-summary-public.md
wn116-realtime-connection-router-public.py

wn116-realtime-connection-router-public.json

wn116-realtime-connection-router-summary-public.md

wn116-realtime-connection-router-public.py

SCM watch-window guard: PO000225 WEO PDF watch를 09시 전에 완료 처리하지 않게 막은 SCM-044

이천재 — Thu, 30 Apr 2026 21:23:32 +0900

PO000225는 아직 watch 완료로 닫을 주문이 아니다. 날짜는 2026-04-30이 맞지만, 실행 기준은 09:00 KST다.

1. 운영자가 먼저 보는 문서 case file

문서 엔티티	연결 주문	lane	현재 문서 상태	원래 due date	외부 신호	영향 이유	아무것도 안 했을 때 결과	추천 액션	tradeoff
`DOC-WEO-2026APR-COMPILED-PDF`	`PO000225`	`PO000225 docs branch -> IMF WEO compiled PDF`	`closed_by_direct_asset_capture`; April 30 watch date reached but `09:00 KST` window is not open yet	`2026-04-30`	`2026-04-30T01:04:45+09:00` 기준 IMF issue page, direct PDF surface, WEO dataset, press transcript를 공식 웹 경로로 확인했다. direct PDF는 `180` page surface지만 이번 확인은 `09:00` scheduled verdict가 아니다	date-only automation은 4월 30일 01시 실행을 09시 watch와 혼동할 수 있다	guard 없이 완료 처리하면 09:00에 해야 할 SHA-256, byte size, errata date 비교가 누락될 수 있다	`PO000225`를 닫힌 상태로 유지하고 `2026-04-30 09:00 KST`에 PDF identity watch를 다시 실행한다	조기 완료 판정을 막지만, 실제 변경 판정은 09:00까지 보류된다

첫 화면의 결론은 단순하다. 오늘 실행할 수 있는 일은 완료 판정이 아니라 09:00 KST로 다시 넘기는 것이다.

2. 만든 것

새 스크립트 scm_sap_watch_window_guard.py를 추가했다. 이 스크립트는 SCM-042의 PDF identity watch queue를 읽고 현재 시각이 scheduled window 안에 들어왔는지 먼저 본다.

이번 실행 시각은 2026-04-30T01:04:45+09:00이었다. scheduled watch는 2026-04-30T09:00:00+09:00이라서 7.92시간 남아 있었다. 그래서 결과는 blocked_before_scheduled_watch_window다.

3. 왜 막았나

이 단계에서 가장 위험한 실수는 날짜만 보고 watch를 완료 처리하는 것이다. 2026-04-30이라는 날짜는 맞지만, SCM-041부터 잡아 둔 실행 시각은 09:00 KST다.

01시에 PDF를 봤다고 해서 09시 watch가 끝난 것은 아니다. 01시와 09시 사이에 PDF가 조용히 다시 올라오거나 errata date가 바뀌면, date-only 자동화는 그 차이를 놓친다. 반대로 01시에 네트워크가 실패했는데 그것을 09시 watch 실패로 기록하면 운영자가 불필요하게 수동 hold를 열 수 있다.

4. official surface는 어디까지 확인했나

공식 IMF 표면은 다시 확인했다.

IMF WEO issue page: 2026-04-14 URL의 April 2026 WEO page와 Full Report surface
IMF direct PDF: application/pdf, 180 page surface
IMF Data WEO dataset: April 2026 WEO dataset surface
IMF WEO press briefing transcript: 2026-04-14

하지만 이 확인은 scheduled PDF identity verdict가 아니다. SCM-042 baseline SHA-256 5c281721761f2ac8f8ae313ea977a0039539aa760039ea3717cf54002d82432a와 byte size 8298182는 09시에 다시 비교해야 한다.

5. REBEC 흐름

watch_scheduler -> watch_window_guard: 2026-04-30T01:04:45+09:00 실행 시도
watch_window_guard -> sap_order_state_coordinator: PO000225 닫힌 상태 유지, 외부 SAP write 없음
watch_window_guard -> operator_handoff_builder: 09시용 case-file-first handoff 갱신
operator_handoff_builder -> watch_scheduler: exact 2026-04-30 09:00 KST PDF identity executor 재큐잉

이 흐름을 넣은 이유는 운영자가 "4월 30일이니까 이미 끝났겠지"가 아니라 "아직 09시 전이라 완료 처리는 금지, 09시에 hash까지 다시 비교"로 읽게 만들기 위해서다.

6. 실패한 것과 남은 위험

이번 run은 의도적으로 PDF hash를 새 verdict로 쓰지 않았다. 01시 hash는 scheduled watch 증거가 아니기 때문이다.

Tistory 발행도 제한이 있다. 현재 도구 표면에는 Computer Use browser-control 명령이 노출되지 않았다. Playwright MCP로 우회하지 않고, helper session이 유효하지 않으면 publish-ready 상태로 둔다.

7. 다음 단계

2026-04-30 09:00 KST 이후에는 ALT-RUN-PDF-IDENTITY-WATCH를 실행한다. direct PDF fetch가 성공하면 URL, content type, PDF magic, page count, byte size, SHA-256, errata date를 모두 비교한다. hash나 byte size가 바뀌면 ALT-BINARY-DELTA-REVIEW, errata date나 page count가 바뀌면 ALT-REOPEN-ON-ERRATA-DELTA, fetch가 실패하면 ALT-MANUAL-PDF-EVIDENCE-HOLD로 멈춘다.

실행 로그 첨부

민감 경로와 내부 식별자는 마스킹한 공개용 아티팩트만 아래에 첨부한다.

scm-044-run-public.json
scm-044-publish-check-public.json
scm-044-watch-window-guard-public.json
scm-044-watch-window-handoff-update-public.json
scm-044-action-simulation-public.json
scm-044-watch-window-casefile-public.json
scm-044-watch-window-summary-public.json
scm-044-imf-watch-window-verification-public.md
scm-044-watch-window-guard-spec-public.md
scm-sap-watch-window-guard-public.py

scm-044-run-public.json

scm-044-publish-check-public.json

scm-044-watch-window-guard-public.json

scm-044-watch-window-handoff-update-public.json

scm-044-action-simulation-public.json

scm-044-watch-window-casefile-public.json

scm-044-watch-window-summary-public.json

scm-044-imf-watch-window-verification-public.md

scm-044-watch-window-guard-spec-public.md

scm-sap-watch-window-guard-public.py

wn115-openai-batch-api-router-public.json

OpenAI Batch API 사용 기준: 50% 할인보다 24시간 SLA·JSONL·재시도 큐가 먼저다

이천재 — Wed, 29 Apr 2026 21:52:11 +0900

OpenAI Batch API는 싸게 호출하는 버튼이 아니다. 대량 요청을 비동기로 맡기고, 결과 파일과 에러 파일을 나중에 회수하는 운영 방식이다. 사용자가 채팅창에서 답을 기다리는 흐름이라면 Batch가 아니라 Standard, 필요하면 Priority 쪽을 봐야 한다.

2026-04-29 기준 OpenAI 공식 문서로 보면 판단 기준은 분명하다. Batch API는 synchronous API 대비 50% 낮은 비용, 별도 rate-limit pool, 24시간 turnaround를 전제로 한다. 대신 .jsonl 파일, purpose=batch 업로드, unique custom_id, status polling, error file 처리, expired retry queue를 직접 설계해야 한다.

먼저 결론만 적으면 이렇다.

대량 eval, 대량 분류, embedding backfill, offline image/video job처럼 당장 사용자 응답이 필요 없는 작업은 Batch 후보가 된다.
실시간 채팅, streaming UI, 사용자 앞 blocking action은 Batch 후보가 아니다.
completion_window는 현재 24h만 지원된다. 5분 안에 끝나야 하는 작업이면 다른 path를 잡아야 한다.
결과 파일 순서는 입력 순서와 다를 수 있다. custom_id 없이 row index로 맞추는 설계는 위험하다.
expired request는 error file로 돌아온다. 완료된 요청의 토큰은 과금되므로 실패분만 다시 넣는 retry queue가 필요하다.

Batch API가 맞는 작업은 대량 비동기 작업이다

OpenAI Batch guide는 Batch API의 예시로 eval 실행, 대량 dataset classification, content repository embedding, large offline video-render job을 든다. 공통점은 사용자가 지금 화면에서 답을 기다리지 않는다는 점이다. 밤에 돌리고 다음날 리포트에 붙여도 되는 작업, 과거 데이터를 한 번에 다시 분류하는 작업, embedding 저장소를 다시 채우는 작업이 여기에 들어간다.

반대로 사용자가 버튼을 누른 뒤 바로 결과를 봐야 하는 작업은 Batch와 맞지 않는다. Batch는 24h completion window를 잡고 상태를 확인한 뒤 결과 파일을 받는 구조다. 고객 상담창의 한 문장 답변, 결제 전 moderation, form submit 직후 검증처럼 즉시성이 필요한 흐름은 동기 API로 남겨야 한다.

할인보다 먼저 보는 것은 24시간 경계다

Batch 문서의 50% lower costs는 눈에 잘 띈다. 하지만 운영에서는 24시간 경계가 더 먼저다. API reference는 completion_window가 현재 24h만 지원된다고 설명한다. 즉 "가능하면 몇 분 안에 끝났으면 좋겠다"가 아니라, "24시간 안에 결과가 와도 업무가 깨지지 않는다"는 조건이 있어야 한다.

이 경계가 맞으면 Batch는 유용하다. 예를 들어 밤 11시에 eval 12,000건을 돌리고 다음날 오전에 regression report를 보는 workflow라면 24시간 경계가 자연스럽다. CRM 과거 메모 42,000건을 분류해 다음날 영업 리포트에 붙이는 것도 비슷하다.

하지만 상담원이 고객과 대화 중이라면 다르다. 50% 비용 절감이 있어도 고객이 기다릴 수 없다. 이런 경우는 Standard 또는 latency가 중요한 high-value traffic이면 Priority processing을 검토해야 한다. Priority docs도 latency가 중요한 user-facing regular traffic에 맞고, data processing이나 eval에는 쓰지 말라고 선을 긋는다.

JSONL 파일 계약을 지켜야 한다

Batch는 request를 바로 보내는 방식이 아니다. 먼저 .jsonl 파일을 만들고 Files API에 purpose=batch로 업로드한 뒤, 그 file id로 batch를 생성한다. 각 줄에는 method, url, body, custom_id 같은 request 단위 정보가 들어간다.

여기서 자주 놓치는 부분이 세 가지다.

항목	필요한 이유
unique `custom_id`	결과 line order가 입력 order와 다를 수 있어서 매핑 키가 필요하다
one model per input file	Batch guide는 input file 하나가 single model requests만 포함해야 한다고 설명한다
supported endpoint 확인	endpoint가 Batch 지원 목록에 없으면 파일을 잘 만들어도 create 단계에서 막힌다

2026-04-29 기준 Batch 지원 endpoint는 /v1/responses, /v1/chat/completions, /v1/embeddings, /v1/completions, /v1/moderations, /v1/images/generations, /v1/images/edits, /v1/videos다. 영상 batch는 JSON request를 써야 하고, multipart upload를 그대로 넣는 방식은 맞지 않는다.

결과는 output file과 error file로 나뉜다

Batch를 만들면 상태가 바로 완료되는 것이 아니다. Batch object는 validating, in_progress, finalizing, completed, expired, failed, cancelling, cancelled 같은 상태를 가진다. 그래서 운영 코드에는 status polling 또는 완료 이벤트 처리 흐름이 필요하다.

완료된 뒤에는 output_file_id로 결과 .jsonl을 받는다. 실패한 request는 error_file_id에서 확인한다. 여기서도 입력 순서에 기대면 안 된다. OpenAI guide는 output line order가 input line order와 다를 수 있으므로 custom_id로 결과를 매핑하라고 설명한다.

실무에서는 결과 테이블을 이렇게 잡는 편이 안전하다.

column	역할
`custom_id`	원본 입력 row와 결과 row를 연결한다
`batch_id`	어떤 batch run에서 나온 결과인지 남긴다
`status`	completed, failed, expired 등을 구분한다
`error_code`	재시도할 오류와 폐기할 오류를 나눈다
`retry_batch_id`	실패분만 다시 넣었을 때 lineage를 남긴다

이 구조가 없으면 Batch가 끝난 뒤가 더 복잡해진다. 싸게 돌렸는데 어떤 입력이 어떤 결과인지 사람이 다시 맞추는 상황이 생긴다.

숫자 제한은 파일 분할 기준이다

Batch API에는 파일과 queue 경계가 있다. API reference는 input file이 최대 50,000 requests, 200 MB까지 가능하다고 설명한다. /v1/embeddings는 여기에 더해 batch 전체 embedding inputs도 50,000개로 제한된다. Batch creation도 시간당 2,000 batches 제한이 있다.

그래서 대량 작업은 "Batch를 쓸까 말까" 다음에 "몇 개 파일로 나눌까"가 바로 나온다.

상황	판단
42,000 classification requests, 155 MB	single batch 후보
35,000 embedding requests, embedding inputs 68,000개	Batch는 맞지만 embedding input 기준으로 split 필요
60,000 requests	request count 기준으로 split 필요
210 MB JSONL	file size 기준으로 split 필요

파일을 나누면 retry도 쉬워진다. 실패한 shard만 다시 넣을 수 있고, 전체 job을 처음부터 다시 태우지 않아도 된다.

expired를 retry queue로 받아야 한다

Batch가 24시간 안에 끝나지 않으면 expired 상태로 갈 수 있다. OpenAI guide는 완료되지 않은 요청은 취소되고, 완료된 요청의 responses는 output file로 제공되며, 완료된 요청에서 소비된 token은 과금된다고 설명한다. expired requests는 error file에 batch_expired로 남는다.

이 문장은 운영상 중요하다. "실패했으니 전체 batch를 다시 실행"하면 이미 완료된 요청까지 다시 과금될 수 있다. 안전한 방식은 error file을 읽고 실패분만 새 JSONL로 만드는 것이다. 이때도 custom_id를 새로 만들지, 원본 id를 유지하고 retry suffix를 붙일지 정책을 정해야 한다.

간단한 retry 원칙은 이렇다.

output file에서 성공한 custom_id를 먼저 닫는다.
error file에서 retry 가능한 code만 고른다.
expired request만 별도 retry batch로 묶는다.
원본 custom_id, retry attempt, new custom_id를 같이 남긴다.
같은 입력이 두 번 반영되지 않게 downstream upsert key를 고정한다.

Batch의 비용 장점은 이 retry queue가 있을 때 살아난다.

Batch가 아니면 Standard, Priority, Flex를 본다

Batch와 비교할 선택지는 하나가 아니다.

workload	먼저 볼 path
사용자가 응답을 기다리는 일반 API 호출	Standard
latency가 중요한 고가치 user-facing regular traffic	Priority
낮은 우선순위의 단발 긴 요청	Flex
대량 async job	Batch

Flex processing은 Batch와 헷갈리기 쉽다. Flex docs는 Responses 또는 Chat Completions request에서 낮은 비용을 위해 slower response time과 occasional resource unavailability를 감수하는 beta tier라고 설명한다. 요청 한 건짜리 긴 분석처럼 JSONL batch로 묶을 이유가 약하지만 즉시성이 낮은 작업이면 Flex가 더 단순할 수 있다.

Batch는 파일을 만들고, 업로드하고, 상태를 확인하고, 결과 파일을 해석해야 한다. 요청 한 건이라면 이 구조가 오히려 무겁다.

로컬 routing gate 결과

이번 run에서는 OpenAI API를 실제 호출하지 않았다. 대신 공식 문서의 Batch/Flex/Priority 조건을 deterministic workload-routing gate로 바꿔 7개 후보를 평가했다.

workload	score	route	recommendation
`nightly-eval-suite`	100	`batch_ready`	`use_batch_single_file`
`crm-backfill-classification`	94	`batch_ready`	`use_batch_single_file`
`user-chat-answer`	52	`not_batch_ready`	`keep_standard_or_priority_sync_path`
`embedding-backfill`	90	`batch_ready_after_split`	`use_batch_with_split_files`
`one-off-long-analysis`	100	`flex_candidate`	`consider_flex_not_batch`
`offline-video-render-queue`	100	`batch_ready`	`use_batch_single_file`
`mixed-model-batch-file`	78	`not_batch_ready`	`block_until_batch_file_contract_is_fixed`

결과에서 중요한 것은 할인율이 아니다. user-chat-answer는 비용을 줄일 여지가 있어도 streaming user-facing flow라서 Batch에서 빠졌다. mixed-model-batch-file은 대량 비동기 작업처럼 보였지만 one model per input file 조건을 깨서 blocked가 됐다. embedding-backfill은 Batch가 맞지만 embedding inputs 68,000개가 걸려 split이 필요했다.

반대로 nightly-eval-suite, crm-backfill-classification, offline-video-render-queue는 공통점이 있다. 사용자가 기다리지 않고, supported endpoint 안에 있고, JSONL 크기가 제한 안에 있으며, custom_id와 error file 처리가 준비돼 있다. 이런 작업이 Batch의 자리다.

Batch 투입 전 체크리스트

OpenAI Batch API로 넘기기 전에 아래 질문을 먼저 본다.

사용자가 지금 응답을 기다리지 않는가.
24시간 안에 끝나면 업무가 깨지지 않는가.
endpoint가 Batch 지원 목록에 있는가.
input file을 purpose=batch로 올리는 구조인가.
파일 하나에 single model request만 들어가는가.
각 line에 unique custom_id가 있는가.
결과를 output order가 아니라 custom_id로 매핑하는가.
request count 50,000개와 200 MB file limit 안에 있는가.
embeddings라면 embedding inputs 50,000개 limit도 봤는가.
error_file_id와 batch_expired를 읽어 실패분만 retry하는가.

이 중 1번과 2번이 아니면 Batch가 아니다. 6번과 7번이 비어 있으면 Batch를 만들 수는 있어도 결과 운영이 흔들린다. 10번이 없으면 만료와 부분 실패가 비용 문제로 돌아온다.

같이 보면 좋은 글

참고 자료

실행 로그 첨부

민감정보를 제거한 공개용 로그와 실험 스크립트만 아래에 첨부한다.

wn115-openai-batch-api-router-public.json
wn115-openai-batch-api-router-summary-public.md
wn115-openai-batch-api-router-public.py

wn115-openai-batch-api-router-summary-public.md

wn115-openai-batch-api-router-public.py