Claude API 구조화된 출력(structured outputs) — JSON 스키마로 출력 보장하기

"결과를 JSON으로만 답해"라고 프롬프트로 부탁해도, 모델이 가끔 마크다운으로 감싸거나 설명을 덧붙여 파싱이 깨질 수 있습니다. 구조화된 출력(structured outputs)은 응답을 정의한 스키마에 맞게 제약해, 바로 파싱 가능한 출력을 보장합니다. 이 글은 두 모드와 작동 원리, 주의점을 공식 기준으로 정리합니다. (공식 문서: platform.claude.com/docs · 기준 시점: 2026년 9월, structured-outputs 문서 재대조)

왜 필요한가

프롬프트 엔지니어링만으로 JSON을 강제하면 다음 문제가 남습니다.

• 응답을 마크다운 코드블록으로 감싸거나 잡담을 덧붙임
• 형식이 조금만 바뀌어도 정규식 파싱이 깨짐
• 스키마 위반 시 에러 처리와 재시도가 필요

구조화된 출력은 이를 "부탁"이 아니라 "보장"으로 바꿉니다. 공식 문서도 항상 유효한 JSON이 필요하면 프롬프트 기법 대신 이 기능을 쓰라고 안내합니다.

두 가지 모드

• JSON 출력(output_config.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_config.format 으로 전달합니다 (2026년 9월 공식 문서 기준, 베타 헤더 불필요).
# msg = client.messages.create(model="claude-sonnet-5", max_tokens=1024,
#     output_config={"format": {"type": "json_schema", "schema": schema}},
#     messages=[...])
# 예전 베타의 output_format 필드·베타 헤더는 전환 기간에만 허용되며,
# Python SDK 1.0+에서는 beta create()에 output_format을 넘기면 TypeError가 납니다.

SDK를 쓰면 더 쉽습니다. Python은 Pydantic, TypeScript는 Zod로 스키마를 정의할 수 있고, SDK가 지원되지 않는 제약(min·max 등)은 자동으로 단순화하고 설명에 반영해 줍니다(실제 제약은 여러분 코드에서 검증).

주의할 점

• 가용성·상태 — 2026년 9월 공식 문서 기준 정식 제공이며 베타 헤더는 더 이상 필요 없습니다. 지원 모델은 Opus 5·Sonnet 5·Fable 5.1·Opus 4.6~4.8·Sonnet 4.6·Sonnet 4.5·Opus 4.5·Haiku 4.5 등(Bedrock은 4.5·4.6 계열만). 파라미터가 output_format에서 output_config.format으로 옮겨졌으니 옛 예제를 그대로 쓰지 마세요(messages.parse() 헬퍼만 편의상 output_format=을 계속 받습니다). 대상 모델은 바뀔 수 있으니 공식 문서가 기준입니다.
• 비호환 기능 — Citations(인용)와 메시지 프리필(prefilling)은 함께 쓸 수 없습니다(인용과 함께 쓰면 400 오류).
• 확장 사고와의 트레이드오프 — 추론 과정이 더 중요한 작업이면 확장 사고가 나을 수 있습니다. 문법 제약은 thinking 영역에는 적용되지 않습니다.
• 스키마 단순화 — 지나치게 복잡한 스키마는 나눠서 단순하게 유지하세요.

관련 가이드

도구 사용의 기본 작동 원리는 Tool Use 가이드, 첫 호출은 Claude API 시작하기, 에러·한도는 에러와 레이트리밋 다루기를 함께 보세요.

구조화된 출력의 파라미터·베타 헤더·지원 모델·정식 제공 여부 등은 변동될 수 있으며, 가장 정확한 정보는 공식 문서(platform.claude.com/docs)에서 확인하시기 바랍니다. 본 사이트는 Anthropic 공식 사이트가 아닙니다.

코드 없이 채팅에서 표·목록·JSON 형식으로 받고 싶다면 Claude 출력 형식 지정하기를 참고하세요.

더 보기: 도구 사용 베스트 프랙티스

관련 글

• Claude API 도구 사용(Tool Use) 완벽 가이드 — 함수 호출 작동 원리
• Claude API 도구 사용 베스트 프랙티스: 정의·에러·병렬 호출 실무
• Claude API 시작하기: 첫 호출까지 (개발자 입문)
• Claude API 키 발급·요금·사용법 완전정리 (2026)
• Claude SDK 시작하기 — Python·TypeScript 공식 클라이언트 사용법