구조화된 출력은 Claude의 응답을 특정 스키마를 따르도록 제한하여 다운스트림 처리를 위한 유효하고 파싱 가능한 출력을 보장합니다. 두 가지 상호 보완적인 기능을 사용할 수 있습니다:
output_format): Claude의 응답을 특정 JSON 형식으로 얻기strict: true): 도구 이름 및 입력에 대한 스키마 검증 보장이러한 기능은 독립적으로 또는 동일한 요청에서 함께 사용할 수 있습니다.
구조화된 출력은 현재 Claude Sonnet 4.5, Claude Opus 4.1, Claude Opus 4.5, Claude Haiku 4.5에 대한 Claude API의 공개 베타 기능으로 사용 가능합니다.
이 기능을 사용하려면 베타 헤더 structured-outputs-2025-11-13을 설정하세요.
이 양식을 사용하여 피드백을 공유하세요.
구조화된 출력이 없으면 Claude는 잘못된 형식의 JSON 응답이나 애플리케이션을 중단시키는 유효하지 않은 도구 입력을 생성할 수 있습니다. 신중한 프롬프팅을 사용하더라도 다음과 같은 문제가 발생할 수 있습니다:
구조화된 출력은 제약된 디코딩을 통해 스키마 준수 응답을 보장합니다:
JSON.parse()JSON 출력은 Claude의 응답 형식을 제어하여 Claude가 스키마와 일치하는 유효한 JSON을 반환하도록 합니다. 다음이 필요한 경우 JSON 출력을 사용하세요:
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: structured-outputs-2025-11-13" \
-d '{
"model": "claude-sonnet-4-5",
"max_tokens": 1024,
"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": {
"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
}
}
}'응답 형식: response.content[0].text에서 스키마와 일치하는 유효한 JSON
{
"name": "John Smith",
"email": "[email protected]",
"plan_interest": "Enterprise",
"demo_requested": true
}JSON 스키마 정의
Claude가 따를 구조를 설명하는 JSON 스키마를 만듭니다. 스키마는 표준 JSON Schema 형식을 사용하지만 일부 제한이 있습니다(JSON Schema 제한사항 참조).
output_format 매개변수 추가
API 요청에 output_format 매개변수를 포함하고 type: "json_schema"와 스키마 정의를 지정합니다.
베타 헤더 포함
요청에 anthropic-beta: structured-outputs-2025-11-13 헤더를 추가합니다.
응답 파싱
Claude의 응답은 스키마와 일치하는 유효한 JSON이며 response.content[0].text에서 반환됩니다.
Python 및 TypeScript SDK는 스키마 변환, 자동 검증, 인기 있는 스키마 라이브러리와의 통합을 포함하여 JSON 출력 작업을 더 쉽게 만드는 헬퍼를 제공합니다.
Python 및 TypeScript 개발자의 경우 원시 JSON 스키마를 작성하는 대신 Pydantic 및 Zod와 같은 친숙한 스키마 정의 도구를 사용할 수 있습니다.
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)Python: client.beta.messages.parse() (권장)
parse() 메서드는 Pydantic 모델을 자동으로 변환하고, 응답을 검증하며, parsed_output 속성을 반환합니다.
parse() 메서드는 client.messages가 아닌 client.beta.messages에서 사용 가능합니다.
Python: transform_schema() 헬퍼
스키마를 전송하기 전에 수동으로 변환해야 하거나 Pydantic 생성 스키마를 수정하려는 경우입니다. client.beta.messages.parse()는 제공된 스키마를 자동으로 변환하는 것과 달리, 이는 변환된 스키마를 제공하므로 추가로 사용자 정의할 수 있습니다.
Python 및 TypeScript SDK는 지원되지 않는 기능이 있는 스키마를 자동으로 변환합니다:
minimum, maximum, minLength, maxLength)additionalProperties: false 추가이는 Claude가 단순화된 스키마를 수신하지만 코드가 검증을 통해 모든 제약을 계속 적용함을 의미합니다.
예시: minimum: 100이 있는 Pydantic 필드는 전송된 스키마에서 일반 정수가 되지만, 설명은 "최소 100이어야 함"으로 업데이트되고, SDK는 원본 제약에 대해 응답을 검증합니다.
엄격한 도구 사용은 도구 매개변수를 검증하여 Claude가 올바르게 입력된 인수로 함수를 호출하도록 합니다. 다음이 필요한 경우 엄격한 도구 사용을 사용하세요:
신뢰할 수 있는 에이전트 시스템을 구축하려면 보장된 스키마 준수가 필요합니다. 엄격한 모드가 없으면 Claude는 호환되지 않는 타입("2" 대신 2)이나 누락된 필수 필드를 반환하여 함수를 중단시키고 런타임 오류를 유발할 수 있습니다.
엄격한 도구 사용은 타입 안전 매개변수를 보장합니다:
예를 들어, 예약 시스템에 passengers: int가 필요하다고 가정합니다. 엄격한 모드가 없으면 Claude는 passengers: "two" 또는 passengers: "2"를 제공할 수 있습니다. strict: true를 사용하면 응답은 항상 passengers: 2를 포함합니다.
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: structured-outputs-2025-11-13" \
-d '{
"model": "claude-sonnet-4-5",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "What is the weather in San Francisco?"}
],
"tools": [{
"name": "get_weather",
"description": "Get the current weather in a given location",
"strict": true,
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"]
}
},
"required": ["location"],
"additionalProperties": false
}
}]
}'응답 형식: response.content[x].input에서 검증된 입력이 있는 도구 사용 블록
{
"type": "tool_use",
"name": "get_weather",
"input": {
"location": "San Francisco, CA"
}
}보장:
input은 input_schema를 엄격히 따릅니다name은 항상 유효합니다 (제공된 도구 또는 서버 도구에서)도구 스키마 정의
도구의 input_schema에 대한 JSON 스키마를 만듭니다. 스키마는 표준 JSON Schema 형식을 사용하지만 일부 제한이 있습니다(JSON Schema 제한사항 참조).
strict: true 추가
도구 정의에서 name, description, input_schema와 함께 최상위 속성으로 "strict": true를 설정합니다.
베타 헤더 포함
요청에 anthropic-beta: structured-outputs-2025-11-13 헤더를 추가합니다.
도구 호출 처리
Claude가 도구를 사용할 때, tool_use 블록의 input 필드는 input_schema를 엄격히 따르고, name은 항상 유효합니다.
JSON 출력과 엄격한 도구 사용은 다양한 문제를 해결하며 함께 사용할 수 있습니다:
결합하면 Claude는 보장된 유효 매개변수로 도구를 호출하고 구조화된 JSON 응답을 반환할 수 있습니다. 이는 신뢰할 수 있는 도구 호출과 구조화된 최종 출력이 모두 필요한 에이전트 워크플로우에 유용합니다.
response = client.beta.messages.create(
model="claude-sonnet-4-5",
betas=["structured-outputs-2025-11-13"],
max_tokens=1024,
messages=[{"role": "user", "content": "Help me plan a trip to Paris for next month"}],
# JSON outputs: structured response format
output_format={
"type": "json_schema",
"schema": {
"type": "object",
"properties": {
"summary": {"type": "string"},
"next_steps": {"type": "array", "items": {"type": "string"}}
},
"required": ["summary", "next_steps"],
"additionalProperties": False
}
},
# Strict tool use: guaranteed tool parameters
tools=[{
"name": "search_flights",
"strict": True,
"input_schema": {
"type": "object",
"properties": {
"destination": {"type": "string"},
"date": {"type": "string", "format": "date"}
},
"required": ["destination", "date"],
"additionalProperties": False
}
}]
)구조화된 출력은 컴파일된 문법 아티팩트를 사용한 제약된 샘플링을 사용합니다. 이는 인식해야 할 일부 성능 특성을 도입합니다:
name 또는 description 필드만 변경하면 캐시가 무효화되지 않습니다구조화된 출력을 사용할 때 Claude는 자동으로 예상 출력 형식을 설명하는 추가 시스템 프롬프트를 받습니다. 이는 다음을 의미합니다:
output_format 매개변수를 변경하면 해당 대화 스레드에 대한 프롬프트 캐시가 무효화됩니다구조화된 출력은 표준 JSON Schema를 지원하지만 일부 제한이 있습니다. JSON 출력과 엄격한 도구 사용 모두 이러한 제한사항을 공유합니다.
Python 및 TypeScript SDK는 지원되지 않는 기능을 제거하고 필드 설명에 제약을 추가하여 스키마를 자동으로 변환할 수 있습니다. 자세한 내용은 SDK 특정 메서드를 참조하세요.
구조화된 출력은 대부분의 경우 스키마 준수를 보장하지만 출력이 스키마와 일치하지 않을 수 있는 시나리오가 있습니다:
거부 (stop_reason: "refusal")
Claude는 구조화된 출력을 사용할 때도 안전성 및 도움이 되는 속성을 유지합니다. Claude가 안전상의 이유로 요청을 거부하는 경우:
stop_reason: "refusal"을 가집니다토큰 제한 도달 (stop_reason: "max_tokens")
max_tokens 제한에 도달하여 응답이 잘린 경우:
stop_reason: "max_tokens"을 가집니다max_tokens 값으로 재시도하세요스키마가 지원되지 않는 기능을 사용하거나 너무 복잡한 경우 400 오류를 받게 됩니다:
"스키마의 재귀 정의가 너무 많음"
"스키마가 너무 복잡함"
strict: true로 표시된 도구 수 감소유효한 스키마의 지속적인 문제의 경우 스키마 정의와 함께 지원팀에 문의하세요.
작동:
호환되지 않음:
output_format이 활성화된 경우 400 오류를 반환합니다.문법 범위: 문법은 Claude의 직접 출력에만 적용되며, 도구 사용 호출, 도구 결과 또는 생각 태그(확장 생각 사용 시)에는 적용되지 않습니다. 문법 상태는 섹션 간에 재설정되어 Claude가 자유롭게 생각하면서도 최종 응답에서 구조화된 출력을 생성할 수 있습니다.