구조화된 출력

구조화된 출력은 Claude의 응답을 특정 스키마를 따르도록 제한하여 다운스트림 처리를 위한 유효하고 파싱 가능한 출력을 보장합니다. 구조화된 데이터 응답을 위해 JSON 출력(output_format)을 사용하거나, 도구 이름 및 입력에 대한 보장된 스키마 검증을 위해 엄격한 도구 사용(strict: true)을 사용하세요.

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

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

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

구조화된 출력은 제한된 디코딩을 통해 스키마 준수 응답을 보장합니다:

• 항상 유효함: 더 이상 JSON.parse() 오류 없음
• 타입 안전: 보장된 필드 타입 및 필수 필드
• 신뢰할 수 있음: 스키마 위반으로 인한 재시도 불필요
• 두 가지 모드: 데이터 추출과 같은 작업을 위한 JSON, 복잡한 도구 및 에이전트 워크플로우와 같은 상황을 위한 엄격한 도구

빠른 시작

JSON 출력 vs 엄격한 도구 사용 시기

사용 사례에 맞는 모드를 선택하세요:

에이전트를 위한 엄격한 도구 사용이 중요한 이유

신뢰할 수 있는 에이전트 시스템을 구축하려면 보장된 스키마 준수가 필요합니다. 유효하지 않은 도구 매개변수는 함수 및 워크플로우를 손상시킵니다. Claude는 호환되지 않는 타입("2" 대신 2)이나 누락된 필드를 반환하여 런타임 오류를 유발할 수 있습니다.

엄격한 도구 사용은 타입 안전 매개변수를 보장합니다:

• 함수는 매번 올바르게 타입된 인수를 받습니다
• 도구 호출을 검증하고 재시도할 필요가 없습니다
• 규모에서 일관되게 작동하는 프로덕션 준비 에이전트

예를 들어, 예약 시스템이 passengers: int를 필요로 한다고 가정합니다. 엄격한 모드가 없으면 Claude는 passengers: "two" 또는 passengers: "2"를 제공할 수 있습니다. strict: true를 사용하면 passengers: 2가 보장됩니다.

구조화된 출력 작동 방식

SDK에서 JSON 출력 작업

Python 및 TypeScript SDK는 스키마 변환, 자동 검증, 인기 있는 스키마 라이브러리와의 통합을 포함하여 JSON 출력 작업을 더 쉽게 만드는 헬퍼를 제공합니다.

Pydantic 및 Zod 사용

Python 및 TypeScript 개발자의 경우 원시 JSON 스키마를 작성하는 대신 Pydantic 및 Zod와 같은 친숙한 스키마 정의 도구를 사용할 수 있습니다.

SDK 특정 메서드

Python: client.beta.messages.parse() (권장)

parse() 메서드는 자동으로 Pydantic 모델을 변환하고, 응답을 검증하며, parsed_output 속성을 반환합니다.

Python: transform_schema() 헬퍼

스키마를 보내기 전에 수동으로 변환해야 할 때 또는 Pydantic 생성 스키마를 수정하려고 할 때 사용합니다. client.beta.messages.parse()와 달리 제공된 스키마를 자동으로 변환하는 경우, 이는 변환된 스키마를 제공하므로 추가로 사용자 정의할 수 있습니다.

SDK 변환 작동 방식

Python 및 TypeScript SDK는 자동으로 지원되지 않는 기능이 있는 스키마를 변환합니다:

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

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

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

일반적인 사용 사례

중요한 고려 사항

문법 컴파일 및 캐싱

구조화된 출력은 컴파일된 문법 아티팩트를 사용한 제한된 샘플링을 사용합니다. 이는 인식해야 할 몇 가지 성능 특성을 도입합니다:

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

프롬프트 수정 및 토큰 비용

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

• 입력 토큰 수가 약간 증가합니다
• 주입된 프롬프트는 다른 시스템 프롬프트처럼 토큰 비용이 발생합니다
• output_format 매개변수를 변경하면 해당 대화 스레드에 대한 프롬프트 캐시가 무효화됩니다

JSON Schema 제한 사항

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

유효하지 않은 출력

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

거부 (stop_reason: "refusal")

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

• 응답에는 stop_reason: "refusal"이 있습니다
• 200 상태 코드를 받습니다
• 생성된 토큰에 대해 청구됩니다
• 출력이 스키마와 일치하지 않을 수 있습니다(거부가 우선합니다)

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

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

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

스키마 검증 오류

스키마가 지원되지 않는 기능을 사용하거나 너무 복잡한 경우 400 오류가 발생합니다:

"스키마에 너무 많은 재귀 정의"

• 원인: 스키마에 과도하거나 순환적인 재귀 정의가 있습니다
• 해결책: 스키마 구조를 단순화하고 중첩 깊이를 줄이세요

"스키마가 너무 복잡함"

• 원인: 스키마가 복잡성 제한을 초과합니다
• 해결책: 더 작은 스키마로 분할하고, 구조를 단순화하거나, strict: true로 표시된 도구 수를 줄이세요

유효한 스키마의 지속적인 문제의 경우 스키마 정의와 함께 지원팀에 문의하세요.

기능 호환성

작동하는 기능:

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

호환되지 않는 기능:

• 인용: 인용은 텍스트와 함께 인용 블록을 인터리빙해야 하며, 이는 엄격한 JSON 스키마 제약과 충돌합니다. output_format이 활성화된 경우 400 오류를 반환합니다.
• 메시지 프리필링: JSON 출력과 호환되지 않음

from pydantic import BaseModel
from anthropic import Anthropic, transform_schema

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

client = Anthropic()

# With .create() - requires transform_schema()
response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    betas=["structured-outputs-2025-11-13"],
    messages=[
        {
            "role": "user",
            "content": "Extract the key information from this email: John Smith ([email protected]) is interested in our Enterprise plan and wants to schedule a demo for next Tuesday at 2pm."
        }
    ],
    output_format={
        "type": "json_schema",
        "schema": transform_schema(ContactInfo),
    }
)

print(response.content[0].text)

# With .parse() - can pass Pydantic model directly
response = client.beta.messages.parse(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    betas=["structured-outputs-2025-11-13"],
    messages=[
        {
            "role": "user",
            "content": "Extract the key information from this email: John Smith ([email protected]) is interested in our Enterprise plan and wants to schedule a demo for next Tuesday at 2pm."
        }
    ],
    output_format=ContactInfo,
)

print(response.parsed_output)