구조화된 출력 (Structured Outputs)

모델 응답을 JSON으로 받아서 프로그램에서 바로 쓸 때, 문법이 어긋나거나 필드가 빠진 걸 매번 다시 파싱·재시도해야 하는 경우가 많아요. 구조화된 출력은 Claude의 응답을 특정 스키마에 맞춰 보장해 주는 기능이에요. 파싱 오류 걱정 없이 바로 쓸 수 있는, 스키마를 준수한 출력을 받을 수 있어요.

출처: https://platform.claude.com/docs/en/build-with-claude/structured-outputs

무엇을 제공하나요

구조화된 출력은 서로 보완되는 두 가지 기능으로 이뤄져요.

JSON 출력 (output_config.format) — Claude의 응답을 특정 JSON 형식으로 받아요.
엄격한 도구 사용 (strict: true) — 도구 이름과 입력 값이 스키마를 지키도록 보장해요.

이 둘은 같은 요청에서 함께 쓸 수도 있고, 필요에 따라 따로 쓸 수도 있어요.

구조화된 출력이 없으면 모델이 잘못된 JSON이나 유효하지 않은 도구 입력을 만들어내서 애플리케이션이 깨질 수 있어요. 프롬프트를 신경 써서 써도 문법 오류, 필수 필드 누락, 데이터 타입 불일치 같은 문제는 생길 수 있어요. 구조화된 출력은 제약된 디코딩(constrained decoding)으로 이런 문제를 원천 차단해요. JSON.parse() 오류가 더 이상 나지 않고, 필드 타입과 필수 필드가 보장되며, 스키마 위반 때문에 재시도할 일이 없어요.

JSON 출력 사용하기

응답 형식을 제어하려면 output_config 객체 안의 format으로 JSON 스키마를 지정해요. 예를 들어 이메일에서 핵심 정보를 추출해 특정 형식으로 받는 요청은 이렇게 써요.

{
  "model": "claude-opus-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "이 이메일에서 핵심 정보를 추출해 주세요: John Smith ([email protected]) is interested in our Enterprise plan and wants to schedule a demo for next Tuesday at 2pm."
    }
  ],
  "output_config": {
    "format": {
      "type": "json_schema",
      "schema": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "email": {"type": "string"},
          "plan_interest": {"type": "string"},
          "demo_requested": {"type": "boolean"}
        },
        "required": ["name", "email", "plan_interest", "demo_requested"],
        "additionalProperties": false
      }
    }
  }
}

format의 type을 json_schema로 정하고, schema에 원하는 필드와 타입, 필수 항목을 적어요. 이렇게 하면 모델이 정확히 그 스키마를 따르는 JSON을 돌려줘요.

참고로 예전 베타 시절의 output_format 파라미터는 지금 output_config.format으로 옮겨졌고 베타 헤더도 더 필요 없어요. API가 옛 헤더(structured-outputs-2025-11-13)와 output_format 필드를 한동안은 계속 받아주지만, Python SDK v1.0 이상에서는 output_format={...}를 거부하고 output_config를 쓰라고 TypeError를 내요.

엄격한 도구 사용

도구 정의에 strict: true를 붙이면 도구 이름과 입력 값이 JSON 스키마를 정확히 지키도록 보장돼요. 도구 입력이 잘못 만들어져서 애플리케이션 로직이 깨지는 일을 막고 싶을 때 유용해요. JSON 출력과 함께 쓰면 응답 형식과 도구 입력 양쪽을 모두 검증할 수 있어요.

더 알아보기

도구 정의와 strict: true의 자세한 사용법은 «도구 사용 (Tool Use)» 문서를 봐요.
모델이 생각(thinking)을 켠 상태에서 구조화된 출력을 쓰는 법은 적응형 사고 문서를 봐요.
요청 전 토큰 수를 미리 세고 싶다면 «토큰 카운팅» 문서를 봐요.