Claude Platform Docs
Messages모델 기능

구조화된 출력

에이전트 워크플로에서 검증된 JSON 결과 얻기

“Structured outputs”(구조화된 출력)는 Claude의 응답이 특정 스키마를 따르도록 제약하여, 다운스트림 처리를 위한 유효하고 파싱 가능한 출력을 보장합니다. 구조화된 출력은 서로 보완하는 두 가지 기능을 제공합니다:

  • JSON 출력 (output_config.format): 이미지나 텍스트에서 데이터를 추출하거나, 구조화된 보고서를 생성하거나, API 응답 형식을 지정하는 등의 목적으로 Claude의 응답을 특정 JSON 형식으로 받습니다. 이 페이지에서는 JSON 출력을 다룹니다.
  • 엄격한 도구 사용 (strict: true): 도구 이름과 입력에 대한 스키마 검증을 보장합니다. 엄격한 도구 사용을 참조하세요.

이러한 기능은 독립적으로 사용하거나 같은 요청에서 함께 사용할 수 있습니다.

구조화된 출력을 사용하는 이유

구조화된 출력이 없으면 Claude는 애플리케이션을 중단시키는 잘못된 형식의 JSON 응답이나 유효하지 않은 도구 입력을 생성할 수 있습니다. 프롬프트를 신중하게 작성하더라도 다음과 같은 문제가 발생할 수 있습니다:

  • 유효하지 않은 JSON 구문으로 인한 파싱 오류
  • 누락된 필수 필드
  • 일관되지 않은 데이터 타입
  • 오류 처리와 재시도가 필요한 스키마 위반

구조화된 출력은 “constrained decoding”(제약된 디코딩)을 통해 스키마를 준수하는 응답을 보장합니다:

  • 항상 유효함: JSON 파싱 오류가 발생하지 않습니다
  • 타입 안전성: 필드 타입과 필수 필드가 보장됩니다
  • 신뢰성: 스키마 위반으로 인한 재시도가 필요하지 않습니다

작동 방식

  1. 스키마 정의하기

    원하는 구조를 JSON 스키마 또는 사용하는 언어의 타입으로 기술합니다. 스키마는 JSON Schema를 따르며, 일부 제한 사항이 있습니다.

  2. output_config.format으로 전송하기

    요청은 type: "json_schema"와 함께 output_config.format에 스키마를 담아 전달합니다. SDK 헬퍼가 이를 자동으로 설정해 줍니다.

  3. 응답 읽기

    Claude는 응답의 텍스트 콘텐츠 블록에 스키마와 일치하는 유효한 JSON을 반환합니다. SDK 헬퍼는 이를 사용자의 타입으로 파싱합니다.

사용법

from pydantic import BaseModel



class ContactInfo(BaseModel):
    name: str
    email: str
    plan_interest: str
    demo_requested: bool


client = Anthropic()

response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": (
                "Extract the key information from this email: "
                "John Smith (john@example.com) is interested in our Enterprise plan "
                "and wants to schedule a demo for next Tuesday at 2pm."
            ),
        }
    ],
    output_format=ContactInfo,
)

print(response.parsed_output)

권장 방법인 client.messages.parse()에 Pydantic 모델을 output_format으로 전달하세요. SDK는 모델의 스키마를 변환하고, 이를 output_config.format으로 전송하며, 응답을 검증하고, 파싱된 모델을 parsed_output에 반환합니다.

앞의 예제는 다음을 출력합니다:

Output
name='John Smith' email='john@example.com' plan_interest='Enterprise' demo_requested=True

필드의 키를 알고 있다면 dict 대신 중첩 Pydantic 모델을 사용하세요. SDK는 dict 필드를 빈 properties를 가진 객체로 전송하므로, Claude는 그 필드에 {}만 반환할 수 있습니다. 키를 미리 알 수 없다면 임의의 키를 가진 객체를 참조하세요.

SDK 변환 작동 방식

대부분의 SDK 헬퍼는 지원되지 않는 기능을 사용하는 스키마를 변환합니다. 변환 단계는 다음과 같습니다:

  1. 지원되지 않는 제약 조건 제거 (예: minimum, maximum, minLength, maxLength)
  2. 지원되지 않는 각 제약 조건을 필드 설명에 추가하여 설명 업데이트 (예: {minimum: 100})
  3. 모든 객체에 additionalProperties: false 추가
  4. 문자열 형식 필터링으로 지원되는 목록만 남김
  5. 헬퍼가 응답을 검증하는 경우, 원래 스키마와 그 모든 제약 조건에 대해 응답 검증

Claude는 단순화된 스키마를 받지만, 응답을 검증하는 헬퍼는 코드에서 모든 제약 조건을 여전히 강제합니다.

예시: minimum: 100이 있는 필드는 전송되는 스키마에서 일반 정수가 되며, SDK는 필드 설명에 {minimum: 100}을 추가합니다. 응답을 검증하는 헬퍼는 여전히 minimum: 100에 대해 응답을 확인합니다.

원시 JSON 스키마 사용하기

파일, OpenAPI 명세 또는 런타임에 스키마를 빌드하는 코드에서 얻은 JSON 스키마를 사용하려면 output_config.format에 전달하세요.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": (
                "Extract the key information from this email: "
                "John Smith (john@example.com) 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,
            },
        }
    },
)
text = next(block.text for block in response.content if block.type == "text")
contact = json.loads(text)
print(contact)

앞의 예제는 다음을 출력합니다:

Output
{'name': 'John Smith', 'email': 'john@example.com', 'plan_interest': 'Enterprise', 'demo_requested': True}

API에서 지원하지 않는 제약 조건을 필드 설명으로 옮기려면, 전송하기 전에 anthropic 패키지의 transform_schema()에 스키마를 통과시키고 필요하면 결과를 수정하세요. transform_schema()는 Pydantic 모델도 받을 수 있습니다. client.messages.parse()와 달리, 이 함수는 스키마를 전송하지 않고 변환된 스키마를 반환합니다.

일반적인 사용 사례

엄격한 도구 사용

문법 제약 샘플링으로 도구 입력에 JSON Schema 준수를 강제하려면 엄격한 도구 사용을 참조하세요.

두 기능을 함께 사용하기

JSON 출력과 엄격한 도구 사용은 서로 다른 문제를 해결하며 함께 작동합니다:

  • JSON 출력은 Claude의 응답 형식(Claude가 말하는 내용)을 제어합니다.
  • 엄격한 도구 사용은 도구 매개변수(Claude가 함수를 호출하는 방식)를 검증합니다.

두 기능을 결합하면 Claude는 유효성이 보장된 매개변수로 도구를 호출하는 동시에 구조화된 JSON 응답을 반환할 수 있습니다. 이는 신뢰할 수 있는 도구 호출과 구조화된 최종 출력이 모두 필요한 에이전트 워크플로에 유용합니다.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Help me plan a trip to Paris departing May 15, 2026",
        }
    ],
    # JSON 출력: 구조화된 응답 형식
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "summary": {"type": "string"},
                    "next_steps": {"type": "array", "items": {"type": "string"}},
                },
                "required": ["summary", "next_steps"],
                "additionalProperties": False,
            },
        }
    },
    # 엄격한 도구 사용: 보장된 도구 매개변수
    tools=[
        {
            "name": "search_flights",
            "strict": True,
            "input_schema": {
                "type": "object",
                "properties": {
                    "destination": {"type": "string"},
                    "date": {"type": "string", "format": "date"},
                },
                "required": ["destination", "date"],
                "additionalProperties": False,
            },
        }
    ],
)

print(response)

중요 고려 사항

문법 컴파일 및 캐싱

구조화된 출력은 컴파일된 문법 아티팩트와 함께 제약된 샘플링을 사용합니다. 이로 인해 알아 두어야 할 몇 가지 성능 특성이 있습니다:

  • 첫 요청 지연 시간: 특정 스키마를 처음 사용할 때는 문법이 컴파일되는 동안 추가 “latency”(지연 시간)가 발생합니다.
  • 자동 캐싱: 컴파일된 문법은 마지막 사용 시점부터 24시간 동안 캐시되어, 이후 요청이 훨씬 빨라집니다.
  • 캐시 무효화: JSON 스키마 구조를 변경하거나, 구조화된 출력과 도구 사용을 함께 사용하는 경우 요청의 도구 집합을 변경하면 캐시가 무효화됩니다. name 또는 description 필드만 변경하는 경우에는 캐시가 무효화되지 않습니다.

프롬프트 수정 및 토큰 비용

구조화된 출력을 사용할 때, Claude는 예상되는 출력 형식을 설명하는 추가 시스템 프롬프트를 자동으로 받습니다. 이는 다음을 의미합니다:

  • 입력 토큰 수가 약간 증가합니다.
  • 주입된 프롬프트는 다른 시스템 프롬프트와 마찬가지로 토큰 비용이 발생합니다.
  • output_config.format 매개변수를 변경하면 해당 대화 스레드의 프롬프트 캐싱 캐시가 무효화됩니다.

JSON Schema 제한 사항

구조화된 출력은 일부 제한 사항이 있는 표준 JSON Schema를 지원합니다. JSON 출력과 엄격한 도구 사용 모두 이러한 제한 사항을 공유합니다.

임의의 키를 가진 객체

객체의 모든 키를 properties에 나열하거나, SDK에 전달하는 클래스 또는 스키마의 필드로 나열하세요. additionalProperties는 false여야 하므로, Claude는 나열한 키만 반환할 수 있습니다.

API는 properties가 비어 있거나 없는 객체를 허용하지만, Claude는 그 객체에 {}만 반환할 수 있습니다. map, dictionary 또는 record 타입은 키를 나열하지 않으므로, Python 및 TypeScript SDK는 이를 빈 properties를 가진 객체로 전송합니다. Java 및 Ruby SDK는 대신 오류를 발생시킵니다.

키를 미리 알 수 없다면 대신 배열을 사용하세요. 다음 스키마와 같이 각 항목에 key와 value를 지정하세요:

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "key": { "type": "string" },
      "value": { "type": "string" }
    },
    "required": ["key", "value"],
    "additionalProperties": false
  }
}

속성 순서

구조화된 출력을 사용할 때, 객체의 속성은 스키마에 정의된 순서를 유지하지만, 한 가지 중요한 주의 사항이 있습니다: 필수 속성이 먼저 나오고, 그 뒤에 선택적 속성이 나옵니다.

예를 들어, 다음 스키마가 주어진 경우:

{
  "type": "object",
  "properties": {
    "notes": { "type": "string" },
    "name": { "type": "string" },
    "email": { "type": "string" },
    "age": { "type": "integer" }
  },
  "required": ["name", "email"],
  "additionalProperties": false
}

출력은 속성을 다음 순서로 정렬합니다:

  1. name (필수, 스키마 순서)
  2. email (필수, 스키마 순서)
  3. notes (선택, 스키마 순서)
  4. age (선택, 스키마 순서)

즉, 출력은 다음과 같을 수 있습니다:

{
  "name": "John Smith",
  "email": "john@example.com",
  "notes": "Interested in enterprise plan",
  "age": 35
}

출력의 속성 순서가 애플리케이션에 중요하다면, 모든 속성을 필수로 표시하거나 파싱 로직에서 이러한 순서 변경을 고려하세요.

유효하지 않은 출력

구조화된 출력은 대부분의 경우 스키마 준수를 보장하지만, 출력이 스키마와 일치하지 않을 수 있는 시나리오가 있습니다:

거부 (stop_reason: "refusal")

Claude는 구조화된 출력을 사용할 때도 안전성과 유용성 특성을 유지합니다. Claude가 안전상의 이유로 요청을 거부하는 경우:

  • 응답에 stop_reason: "refusal"이 포함됩니다.
  • 200 상태 코드를 받게 됩니다.
  • 생성된 토큰에 대해 요금이 청구됩니다.
  • 거부 메시지가 스키마 제약 조건보다 우선하므로 출력이 스키마와 일치하지 않을 수 있습니다.

모델의 사고나 단계별 추론을 요구하는 속성은 reasoning_extraction 거부로 이어질 수 있습니다. 대신 간단한 설명을 요청하세요. 사고 블록에 추론 유지하기를 참조하세요.

토큰 한도 도달 (stop_reason: "max_tokens")

응답이 max_tokens 한도에 도달하여 잘린 경우:

  • 응답에 stop_reason: "max_tokens"가 포함됩니다.
  • 출력이 불완전하여 스키마와 일치하지 않을 수 있습니다.
  • 완전한 구조화된 출력을 얻으려면 더 높은 max_tokens 값으로 재시도하세요.

Enum 값 대소문자

구조화된 출력은 문자열 enum 및 const 값의 대소문자를 보장하지 않습니다. Claude는 스키마와 대소문자만 다른 값을 반환할 수 있으며, 이는 일반적으로 공백 뒤에 오는 단어의 첫 글자에서 발생합니다. 예를 들어, 다음 스키마가 주어진 경우:

{
  "type": "string",
  "enum": ["Conversation Topic 1", "Conversation Topic 2", "Conversation topic 3"]
}

해당 값이 enum에 정확히 존재하지 않더라도 출력에 "Conversation Topic 3"(대문자 “T”)이 포함될 수 있습니다. 응답은 오류나 특별한 stop_reason 없이 정상적으로 완료됩니다. 이는 JSON 출력과 엄격한 도구 사용 모두에 적용됩니다. enum 값은 대소문자를 구분하지 않고 비교하고, 대소문자만 다른 enum 값은 피하세요.

스키마 복잡도 제한

구조화된 출력은 JSON 스키마를 Claude의 출력을 제약하는 문법으로 컴파일하여 작동합니다. 스키마가 복잡할수록 더 큰 문법이 생성되어 컴파일 시간이 길어집니다. 과도한 컴파일 시간을 방지하기 위해 API는 여러 복잡도 제한을 적용합니다.

명시적 제한

다음 제한은 output_config.format 또는 strict: true가 포함된 모든 요청에 적용됩니다:

제한값설명
요청당 엄격한 도구 수20strict: true가 설정된 도구의 최대 개수입니다. 엄격하지 않은 도구는 이 제한에 포함되지 않습니다.
선택적 매개변수24모든 엄격한 도구 스키마와 JSON 출력 스키마에 걸친 선택적 매개변수의 총 개수입니다. required에 나열되지 않은 각 매개변수가 이 제한에 포함됩니다.
유니온 타입을 사용하는 매개변수16모든 엄격한 스키마에 걸쳐 anyOf 또는 타입 배열(예: "type": ["string", "null"])을 사용하는 매개변수의 총 개수입니다. 이러한 매개변수는 기하급수적인 컴파일 비용을 발생시키므로 특히 비용이 큽니다.

추가 내부 제한

앞의 표에 있는 명시적 제한 외에도, 컴파일된 문법 크기에 대한 추가 내부 제한이 있습니다. 이러한 제한이 존재하는 이유는 스키마 복잡도가 단일 차원으로 환원되지 않기 때문입니다. 선택적 매개변수, 유니온 타입, 중첩 객체, 도구 수와 같은 기능은 서로 상호작용하여 컴파일된 문법을 불균형적으로 크게 만들 수 있습니다.

이러한 제한을 초과하면 “Schema is too complex for compilation.” 메시지와 함께 400 오류를 받게 됩니다. 이러한 오류는 앞의 표에 있는 각 개별 제한을 충족하더라도, 스키마의 결합된 복잡도가 효율적으로 컴파일할 수 있는 수준을 초과했음을 의미합니다. 최종 안전장치로서 API는 180초의 컴파일 타임아웃도 적용합니다. 모든 명시적 검사를 통과하더라도 매우 큰 컴파일된 문법을 생성하는 스키마는 이 타임아웃에 도달할 수 있습니다.

스키마 복잡도를 줄이기 위한 팁

복잡도 제한에 도달하는 경우, 다음 전략을 순서대로 시도해 보세요:

  1. 중요한 도구만 엄격하게 표시하세요. 도구가 많다면, 스키마 위반이 실제 문제를 일으키는 도구에만 엄격한 도구 사용을 적용하고, 더 간단한 도구는 Claude의 자연스러운 준수에 맡기세요.

  2. 선택적 매개변수를 줄이세요. 가능한 경우 매개변수를 required로 만드세요. 각 선택적 매개변수는 문법 상태 공간의 일부를 대략 두 배로 늘립니다. 매개변수에 항상 합리적인 기본값이 있다면, 이를 필수로 만들고 Claude가 해당 기본값을 명시적으로 제공하도록 하는 것을 고려하세요.

  3. 중첩 구조를 단순화하세요. 선택적 필드가 있는 깊게 중첩된 객체는 복잡도를 가중시킵니다. 가능한 경우 구조를 평평하게 만드세요.

  4. 여러 요청으로 분할하세요. 엄격한 도구가 많다면, 이를 별도의 요청이나 서브에이전트로 분할하는 것을 고려하세요.

유효한 스키마에서 문제가 지속되는 경우, 스키마 정의와 함께 지원팀에 문의하세요.

베타에서 마이그레이션하기

output_format 매개변수는 output_config.format으로 이동했으며, 베타 헤더는 더 이상 필요하지 않습니다. output_format 매개변수는 지원 중단되었습니다. 그래도 사용하려면 structured-outputs-2025-11-13 베타 헤더를 추가하세요. 이 헤더가 없으면 API는 400 오류를 반환합니다.

Python SDK(v1.0 이상)에서는 output_format={...}로 전달된 스키마 딕셔너리가 TypeError를 발생시킵니다. 대신 output_config를 사용하세요. parse() 또는 stream()에 output_format=Model로 전달된 Pydantic 모델은 SDK가 이를 output_config로 전송하므로 변경 없이, 베타 헤더 없이도 작동합니다. 업데이트된 API 형태는 원시 JSON 스키마 사용하기를 참조하세요.

기능 호환성

함께 작동하는 기능:

  • 배치 처리: 50% 할인으로 구조화된 출력을 대규모로 처리합니다
  • 토큰 카운팅: 컴파일 없이 토큰을 계산합니다
  • 스트리밍: 일반 응답처럼 구조화된 출력을 스트리밍합니다
  • 결합 사용: 같은 요청에서 JSON 출력(output_config.format)과 엄격한 도구 사용(strict: true)을 함께 사용합니다

호환되지 않는 기능:

  • 인용: 인용은 인용 블록을 텍스트와 교차 배치해야 하므로 엄격한 JSON 스키마 제약 조건과 충돌합니다. output_config.format과 함께 인용이 활성화되면 API는 400 오류를 반환합니다. 각 값에 대한 인용과 함께 구조화된 데이터를 추출하려면 인용과 함께 구조화된 데이터 가져오기를 참조하세요.
  • 메시지 프리필: 프리필은 JSON 출력과 호환되지 않습니다.

제공 여부

구조화된 출력
API
  • Messages API
  • Managed Agents 지원되지 않음
모델
  • 모든 모델

적용 엔드포인트

  • /v1/messages
제로 데이터 보존적격(조건부)

적용 모델 제외

프롬프트와 Claude의 출력은 저장되지 않습니다. JSON 스키마만 마지막 사용 후 최대 24시간 동안 캐시됩니다. 이는 동일한 문법 파이프라인을 사용하는 엄격한 도구 사용(도구의 strict: true)에도 적용됩니다. 자세히 알아보기

HIPAA적격

JSON 스키마 정의에 PHI를 포함해서는 안 됩니다. PHI 처리 지침을 참조하세요. 자세히 알아보기

구조화된 출력을 사용할 때 프롬프트와 응답은 ZDR로 처리됩니다. 다만 JSON 스키마 자체는 최적화 목적으로 마지막 사용 시점부터 최대 24시간 동안 임시로 캐시됩니다. API 응답 이후에는 어떠한 프롬프트나 응답 데이터도 보존되지 않습니다.

구조화된 출력은 HIPAA 적격이지만, JSON 스키마 정의에 PHI를 포함해서는 안 됩니다. API는 JSON 스키마를 메시지 콘텐츠와 별도로 캐시되는 문법으로 컴파일하며, 이렇게 캐시된 스키마는 프롬프트 및 응답과 동일한 PHI 보호를 받지 않습니다. 스키마 속성 이름, enum 값, const 값 또는 pattern 정규식에 PHI를 포함하지 마세요. PHI는 HIPAA 보호 조치에 따라 보호되는 메시지 콘텐츠(프롬프트 및 응답)에만 나타나야 합니다.

다음 단계

제공된 문서에 대한 질문에 답할 때 Claude가 출처를 인용하도록 합니다.

문법 제약 샘플링으로 Claude의 도구 입력에 JSON Schema 준수를 강제합니다.

Claude를 외부 도구 및 API에 연결합니다. 도구가 실행되는 위치와 에이전트 루프의 작동 방식을 알아보세요.

모델 및 기능에 대한 Anthropic의 가격 구조를 알아보세요.

이 페이지가 도움이 되었나요?