구조화된 출력

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

• JSON 출력 (output_config.format): Claude의 응답을 특정 JSON 형식으로 받습니다
• 엄격한 도구 사용 (strict: true): 도구 이름과 입력에 대한 스키마 검증을 보장합니다

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

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

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

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

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

• 항상 유효함: 더 이상 JSON.parse() 오류가 없습니다
• 타입 안전: 필드 타입과 필수 필드가 보장됩니다
• 신뢰성: 스키마 위반으로 인한 재시도가 필요 없습니다

JSON 출력

JSON 출력은 Claude의 응답 형식을 제어하여 Claude가 스키마와 일치하는 유효한 JSON을 반환하도록 보장합니다. 다음이 필요할 때 JSON 출력을 사용하세요:

• Claude의 응답 형식 제어
• 이미지나 텍스트에서 데이터 추출
• 구조화된 보고서 생성
• API 응답 형식 지정

빠른 시작

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,
            },
        }
    },
)
print(next(block.text for block in response.content if block.type == "text"))

응답 형식: 응답의 텍스트 콘텐츠 블록에 스키마와 일치하는 유효한 JSON

{
  "name": "John Smith",
  "email": "john@example.com",
  "plan_interest": "Enterprise",
  "demo_requested": true
}

작동 방식

1. 1

   JSON 스키마 정의

   Claude가 따르기를 원하는 구조를 설명하는 JSON 스키마를 만드세요. 스키마는 일부 제한 사항이 있는 표준 JSON Schema 형식을 사용합니다(JSON Schema 제한 사항 참조).

2. 2

   output_config.format 매개변수 추가

   API 요청에 type: "json_schema"와 스키마 정의를 포함한 output_config.format 매개변수를 포함하세요.

3. 3

   응답 파싱

   Claude의 응답은 스키마와 일치하는 유효한 JSON이며, 응답의 텍스트 콘텐츠 블록에 반환됩니다.

SDK에서 JSON 출력 사용하기

SDK는 스키마 변환, 자동 검증, 인기 있는 스키마 라이브러리와의 통합을 포함하여 JSON 출력을 더 쉽게 사용할 수 있게 하는 헬퍼를 제공합니다.

네이티브 스키마 정의 사용하기

원시 JSON 스키마를 작성하는 대신, 사용하는 언어에서 익숙한 스키마 정의 도구를 사용할 수 있습니다:

• Python: client.messages.parse()와 함께 Pydantic 모델 사용
• TypeScript: zodOutputFormat()과 함께 Zod 스키마 사용, 또는 jsonSchemaOutputFormat()과 함께 타입이 지정된 JSON Schema 리터럴 사용
• Java: outputConfig(Class<T>)를 통한 자동 스키마 도출과 함께 일반 Java 클래스 사용
• Ruby: output_config: {format: Model}과 함께 Anthropic::BaseModel 클래스 사용
• PHP: outputConfig: ['format' => MyClass::class]와 함께 StructuredOutputModel을 구현하는 클래스 사용
• C#: 스키마를 자동으로 도출하는 제네릭 Create<T>() 오버로드와 함께 일반 C# 클래스 사용
• Go: 베타 API에서 JSON 스키마로 자동 리플렉션되는 Go 구조체, 또는 output_config를 통한 원시 JSON 스키마 사용
• CLI: output_config를 통해 전달되는 원시 JSON 스키마

from pydantic import BaseModel
from anthropic import Anthropic


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)

SDK별 메서드

각 SDK는 구조화된 출력을 더 쉽게 사용할 수 있게 하는 헬퍼를 제공합니다. 전체 세부 사항은 개별 SDK 페이지를 참조하세요.

from pydantic import BaseModel
# ...
class ContactInfo(BaseModel):
    name: str
    email: str
    plan_interest: str
# ...
response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Extract contact info: John Smith, john@example.com, interested in the Pro plan",
        }
    ],
    output_format=ContactInfo,
)

# 파싱된 출력에 직접 접근합니다
contact = response.parsed_output
print(contact.name, contact.email)

from anthropic import transform_schema
from pydantic import TypeAdapter
# ...

# 먼저 Pydantic 모델을 JSON 스키마로 변환한 다음 변형합니다
schema = TypeAdapter(ContactInfo).json_schema()
schema = transform_schema(schema)
# 필요한 경우 스키마를 수정합니다
schema["properties"]["custom_field"] = {"type": "string"}

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "..."}],
    output_config={
        "format": {"type": "json_schema", "schema": schema},
    },
)

SDK 변환 작동 방식

Python, TypeScript, Ruby 및 PHP SDK는 지원되지 않는 기능이 있는 스키마를 자동으로 변환합니다. C# 및 Go SDK는 스키마가 네이티브 타입에서 도출될 때(C#의 Create<T>(), Go 베타 API의 구조체 리플렉션 또는 BetaJSONSchemaOutputFormat()) 동일한 변환을 적용합니다. 변환 단계:

1. 지원되지 않는 제약 조건 제거 (예: minimum, maximum, minLength, maxLength)
2. 제약 조건이 구조화된 출력에서 직접 지원되지 않는 경우, 제약 정보로 설명 업데이트 (예: "Must be at least 100")
3. 모든 객체에 additionalProperties: false 추가
4. 지원되는 목록으로만 문자열 형식 필터링
5. 원래 스키마(모든 제약 조건 포함)에 대해 응답 검증

이는 Claude가 단순화된 스키마를 받지만, 코드는 여전히 검증을 통해 모든 제약 조건을 적용한다는 것을 의미합니다.

예시: minimum: 100이 있는 Pydantic 필드는 전송된 스키마에서 일반 정수가 되지만, SDK는 설명을 "Must be at least 100"으로 업데이트하고 원래 제약 조건에 대해 응답을 검증합니다.

일반적인 사용 사례

from pydantic import BaseModel


class Invoice(BaseModel):
    invoice_number: str
    date: str
    total_amount: float
    line_items: list[dict]
    customer_name: str


client = anthropic.Anthropic()
invoice_text = "Invoice #12345, Date: 2024-01-15, Total: $500.00"

response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=4096,
    output_format=Invoice,
    messages=[
        {"role": "user", "content": f"Extract invoice data from: {invoice_text}"}
    ],
)

print(response.parsed_output)

from pydantic import BaseModel

client = Anthropic()


class Classification(BaseModel):
    category: str
    confidence: float
    tags: list[str]
    sentiment: str


feedback_text = "Great product, but the delivery was slow."
response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    output_format=Classification,
    messages=[{"role": "user", "content": f"Classify this feedback: {feedback_text}"}],
)

print(response.parsed_output)

from pydantic import BaseModel

client = Anthropic()


class APIResponse(BaseModel):
    status: str
    data: dict
    errors: list[dict] | None
    metadata: dict


response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    output_format=APIResponse,
    messages=[{"role": "user", "content": "Process this request: ..."}],
)

print(response.parsed_output)

엄격한 도구 사용

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

두 기능 함께 사용하기

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

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

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

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 출력과 엄격한 도구 사용 모두 이러한 제한 사항을 공유합니다.

속성 순서

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

예를 들어, 다음 스키마가 주어지면:

{
  "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 상태 코드를 받게 됩니다
• 생성된 토큰에 대해 요금이 청구됩니다
• 거부 메시지가 스키마 제약 조건보다 우선하기 때문에 출력이 스키마와 일치하지 않을 수 있습니다

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

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

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

열거형 값 대소문자

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

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

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

스키마 복잡도 한도

구조화된 출력은 JSON 스키마를 Claude의 출력을 제약하는 문법으로 컴파일하여 작동합니다. 더 복잡한 스키마는 컴파일하는 데 더 오래 걸리는 더 큰 문법을 생성합니다. 과도한 컴파일 시간을 방지하기 위해 API는 여러 복잡도 한도를 적용합니다.

명시적 한도

다음 한도는 output_config.format 또는 strict: true가 있는 모든 요청에 적용됩니다:

추가 내부 한도

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

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

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

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

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

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

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

4. 여러 요청으로 분할하세요. 엄격한 도구가 많은 경우, 별도의 요청이나 하위 에이전트로 분할하는 것을 고려하세요.

유효한 스키마에서 지속적인 문제가 발생하면 스키마 정의와 함께 지원팀에 문의하세요.

데이터 보존

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

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

모든 기능에 대한 ZDR 및 HIPAA 적격성은 API 및 데이터 보존을 참조하세요.

기능 호환성

함께 작동:

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

호환되지 않음:

• 인용: 인용은 인용 블록을 텍스트와 교차 배치해야 하며, 이는 엄격한 JSON 스키마 제약 조건과 충돌합니다. output_config.format과 함께 인용이 활성화되면 400 오류를 반환합니다.
• 메시지 프리필링: JSON 출력과 호환되지 않음

다음 단계

Compatibility