"결과를 JSON으로만 답해"라고 프롬프트로 부탁해도, 모델이 가끔 마크다운으로 감싸거나 설명을 덧붙여 파싱이 깨질 수 있습니다. 구조화된 출력(structured outputs)은 응답을 정의한 스키마에 맞게 제약해, 바로 파싱 가능한 출력을 보장합니다. 이 글은 두 모드와 작동 원리, 주의점을 공식 기준으로 정리합니다. (공식 문서: docs.claude.com · 기준 시점: 2026년 6월)
왜 필요한가
프롬프트 엔지니어링만으로 JSON을 강제하면 다음 문제가 남습니다.
- 응답을 마크다운 코드블록으로 감싸거나 잡담을 덧붙임
- 형식이 조금만 바뀌어도 정규식 파싱이 깨짐
- 스키마 위반 시 에러 처리와 재시도가 필요
구조화된 출력은 이를 "부탁"이 아니라 "보장"으로 바꿉니다. 공식 문서도 항상 유효한 JSON이 필요하면 프롬프트 기법 대신 이 기능을 쓰라고 안내합니다.
두 가지 모드
- JSON 출력(output_format) — 응답 전체를 지정한 JSON 형식으로 받습니다. 데이터 추출·정형 응답에 적합합니다.
- 엄격한 도구 사용(strict: true) — 도구의 이름과 입력이 스키마를 반드시 따르도록 검증합니다. 복잡한 도구·에이전트 워크플로에 적합합니다.
두 기능은 독립적으로 쓰거나 한 요청에서 함께 쓸 수 있습니다.
어떻게 보장하나
구조화된 출력은 JSON 스키마를 grammar(문법)로 컴파일한 뒤, 생성 단계에서 그 규칙을 벗어나는 토큰이 나오지 않도록 제약합니다(제약 디코딩, constrained decoding). 즉 모델이 스키마를 위반하는 출력을 애초에 만들 수 없습니다. 스키마가 복잡할수록 컴파일이 오래 걸릴 수 있어, 과도하게 큰 스키마는 단순화가 권장됩니다.
쓰는 법
원하는 데이터 형태를 JSON 스키마로 정의해 전달합니다.
# 원하는 출력 형태를 스키마로 정의
schema = {
"type": "object",
"properties": {
"name": {"type": "string"},
"price": {"type": "number"},
"in_stock": {"type": "boolean"}
},
"required": ["name", "price"]
}
# 이 스키마를 출력 형식(output_format) 파라미터로 전달합니다.
# 정확한 파라미터 형식과 베타 헤더는 공식 문서에서 확인하세요.SDK를 쓰면 더 쉽습니다. Python은 Pydantic, TypeScript는 Zod로 스키마를 정의할 수 있고, SDK가 지원되지 않는 제약(min·max 등)은 자동으로 단순화하고 설명에 반영해 줍니다(실제 제약은 여러분 코드에서 검증).
주의할 점
- 가용성·상태 변동 — 모델·플랫폼별로 지원 범위가 다르고, 일부는 베타 헤더가 필요할 수 있습니다. 정식 제공(GA) 여부와 대상 모델은 바뀌니 공식 문서가 기준입니다.
- 비호환 기능 — Citations(인용)와 메시지 프리필(prefilling)은 함께 쓸 수 없습니다(인용과 함께 쓰면 400 오류).
- 확장 사고와의 트레이드오프 — 추론 과정이 더 중요한 작업이면 확장 사고가 나을 수 있습니다. 문법 제약은 thinking 영역에는 적용되지 않습니다.
- 스키마 단순화 — 지나치게 복잡한 스키마는 나눠서 단순하게 유지하세요.
관련 가이드
도구 사용의 기본 작동 원리는 Tool Use 가이드, 첫 호출은 Claude API 시작하기, 에러·한도는 에러와 레이트리밋 다루기를 함께 보세요.
구조화된 출력의 파라미터·베타 헤더·지원 모델·정식 제공 여부 등은 변동될 수 있으며, 가장 정확한 정보는 공식 문서(docs.claude.com)에서 확인하시기 바랍니다. 본 사이트는 Anthropic 공식 사이트가 아닙니다.