Quick Reference
Claude API의 structured outputs에는 서로 다른 두 계약이 있습니다. 최종 응답 JSON이 필요한 경우는 output_config.format의 JSON outputs, 도구 이름과 인자를 막아야 하는 경우는 도구 정의의 strict: true를 씁니다. 둘 다 JSON Schema를 쓰지만, 하나가 다른 하나의 실행 안전성을 대신하지 않습니다.
| 필요한 계약 | API 표면 | 보장하는 것 | 호출자가 계속 확인할 것 |
|---|---|---|---|
| 최종 결과 JSON | output_config.format | text content block의 schema 일치 JSON | 값의 사실성·업무 규칙·refusal·요청 오류 |
| 도구 호출 인자 | tool의 strict: true | 선택된 tool name과 input schema 일치 | 실제 도구 인가·실행 결과·부작용 |
| 읽기 좋은 형식 | prompt와 예시 | 생성 방향 | parser와 타입 일치 |
| 외부 시스템 변경 | 서버 코드 | 없음 | 인증·권한·idempotency·감사 로그 |
{
"output_config": {
"format": {
"type": "json_schema",
"schema": {
"type": "object",
"properties": {
"summary": { "type": "string" },
"riskLevel": { "type": "string", "enum": ["low", "high"] }
},
"required": ["summary", "riskLevel"],
"additionalProperties": false
}
}
}
}JSON outputs
JSON outputs는 Messages API 요청의 output_config.format에 type: "json_schema"와 schema를 넣는 기능입니다. 응답은 별도 JSON 필드가 아니라 response content의 text block에 schema를 만족하는 JSON 문자열로 돌아옵니다. 따라서 응답 block을 찾고 JSON을 파싱한 뒤, 업무 규칙을 검사하는 순서가 필요합니다.
text = next(block.text for block in response.content if block.type == "text")
payload = json.loads(text)
if payload["riskLevel"] == "high" and not payload["summary"].strip():
raise ValueError("업무 규칙: high risk에는 요약이 필요합니다.")schema는 표현 계약입니다. required, enum, additionalProperties를 실제 소비자가 요구하는 만큼만 좁힙니다. 모델이 선택한 문자열이 올바른 분류인지, 입력 자료가 최신인지, 여러 필드가 합쳐져 유효한 상태인지는 schema 밖의 일입니다.
strict tool use
도구 호출을 제한할 때는 input_schema만 적는 것과 strict: true를 켜는 것을 구분합니다. 일반 tool use에서 모델은 도구 사용 요청을 만들고, 호출자가 tool_use block의 name, id, input을 읽어 실제 코드를 실행한 뒤 tool_result를 다시 보내야 합니다. strict tool use는 그 요청의 도구 이름·입력이 schema에 맞도록 제약하지만, 실제 도구가 허용된 작업인지 판단하지 않습니다.
{
"name": "get_order",
"description": "현재 사용자가 접근 가능한 주문 한 건을 읽습니다. 변경하지 않습니다.",
"strict": true,
"input_schema": {
"type": "object",
"properties": { "orderId": { "type": "string" } },
"required": ["orderId"],
"additionalProperties": false
}
}| 단계 | Claude가 하는 일 | 서버가 책임질 일 |
|---|---|---|
| 도구 선택 | schema에 맞는 호출 요청 생성 | 허용된 tool인지 확인 |
| 실행 전 | input 전달 | 현재 사용자·tenant·resource 권한 확인 |
| 실행 | 결과를 기다림 | timeout·idempotency·rate limit 처리 |
| 결과 반환 | tool_result로 다음 응답 생성 | 민감 정보 필터링·감사 로그 기록 |
제한과 오류 처리
structured outputs는 현재 지원 모델과 플랫폼에서만 사용합니다. schema의 지원 범위와 복잡도 제한이 있으므로, 큰 union·깊은 중첩·모든 경우를 하나의 schema에 넣기보다 응답 종류를 나누는 편이 오류를 줄입니다. 기존 beta의 output_format은 새 요청에서 output_config.format으로 옮겨 쓰는 것이 기준입니다.
schema 일치가 성공 응답·정확한 판단·안전한 도구 실행을 뜻하지는 않습니다. HTTP 오류, refusal, timeout, max_tokens, 입력 자료 부족은 별도 실패 경로이며, strict tool use도 서버의 인증·인가와 부작용 제어를 대신하지 않습니다.
권장 흐름
1. API 오류와 refusal을 먼저 처리한다.
2. JSON outputs의 text block을 파싱한다.
3. schema 밖 업무 규칙과 원문 근거를 검증한다.
4. 도구 호출은 서버에서 권한·중복 실행·감사 로그를 처리한다.참고 링크
2 sources