AI API를 사용하다 보면 가장 짜증나는 순간이 있습니다. “Invalid JSON” 에러죠. 분명 JSON 형식으로 답변하라고 프롬프트에 명시했는데, AI가 엉뚱한 형식으로 답변하거나 필수 필드를 빼먹는 경우가 생깁니다. 프로덕션 환경에서는 이런 작은 실수 하나가 전체 시스템을 멈추게 만들 수 있죠.

Anthropic이 이 문제를 완전히 해결하는 Structured Outputs 기능을 베타로 공개했습니다. Claude Sonnet 4.5와 Opus 4.1에서 사용 가능하며, Claude의 API 응답이 개발자가 정의한 JSON 스키마나 툴 정의와 100% 일치하도록 보장합니다.

출처: Structured outputs on the Claude Developer Platform – Anthropic Blog

무엇이 달라지는가

기존에는 아무리 프롬프트를 정교하게 작성해도 Claude가 잘못된 JSON을 생성하거나 타입을 틀리게 반환할 수 있었습니다. passengers 필드에 정수를 기대했는데 "two"나 "2" 같은 문자열을 받는 식이죠. 이런 문제를 방지하기 위해 개발자들은 복잡한 에러 처리 로직과 재시도 메커니즘을 구현해야 했습니다.

Structured Outputs는 제약 기반 디코딩(constrained decoding)이라는 기술을 사용해 이 문제를 근본적으로 해결합니다. Claude가 응답을 생성할 때부터 정의된 스키마에서 벗어날 수 없도록 제약을 겁니다. 결과는 명확합니다:

• 항상 유효한 JSON: JSON.parse() 에러가 완전히 사라집니다
• 타입 안전성: 필수 필드와 정확한 데이터 타입이 보장됩니다
• 재시도 불필요: 스키마 위반으로 인한 재시도가 필요 없습니다

중요한 건, 이 모든 보장이 모델 성능에 영향을 주지 않는다는 점입니다.

두 가지 모드

Structured Outputs는 두 가지 방식으로 사용할 수 있습니다:

JSON 출력 모드 (output_format)
이미지나 텍스트에서 데이터를 추출하거나 구조화된 리포트를 생성할 때 사용합니다. API 요청에 JSON 스키마를 정의하면 Claude의 응답이 정확히 그 형식으로 나옵니다.

Strict Tool Use 모드 (strict: true)
AI 에이전트 워크플로우나 복잡한 툴 호출에 사용합니다. 툴 정의를 명시하면 Claude가 해당 툴을 호출할 때 파라미터가 스키마에 완벽히 맞춰집니다.

특히 멀티 에이전트 시스템에서 Strict Tool Use의 효과가 큽니다. 에이전트 간 통신에서 잘못된 파라미터 하나가 전체 워크플로우를 망칠 수 있는데, 이제는 그런 걱정이 사라집니다. 400만 명 이상의 개발자에게 AI 모델을 제공하는 OpenRouter의 Chris Clark COO는 “에이전트 워크플로우가 매번 안정적으로 작동하고, 팀들이 툴 호출 디버깅 대신 고객에게 집중할 수 있게 됐다”고 말합니다.

개발자 친화적 설계

Python과 TypeScript SDK는 Pydantic, Zod 같은 익숙한 도구로 스키마를 정의할 수 있도록 지원합니다. 예를 들어 Python에서는 이렇게 작성하면 됩니다:

from pydantic import BaseModel

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

response = client.beta.messages.parse(
    model="claude-sonnet-4-5",
    betas=["structured-outputs-2025-11-13"],
    output_format=ContactInfo,
    ...
)

contact = response.parsed_output

SDK가 스키마 변환과 검증을 자동으로 처리해줍니다. Structured Outputs가 직접 지원하지 않는 제약 조건(예: minimum, maximum)이 있으면 SDK가 이를 설명(description)으로 변환하고, 응답을 받은 후 원래 제약 조건으로 검증합니다.

알아둘 점

첫 요청 시에는 스키마를 기반으로 문법(grammar)을 컴파일하는 추가 레이턴시가 발생합니다. 하지만 컴파일된 문법은 24시간 동안 캐시되므로 이후 요청은 빠르게 처리됩니다. 스키마 구조나 툴 세트를 변경하면 캐시가 무효화되지만, name이나 description 필드만 바꾸는 것은 캐시에 영향을 주지 않습니다.

또한 Claude가 안전성 이유로 요청을 거부하거나(stop_reason: "refusal"), 토큰 제한에 도달한 경우(stop_reason: "max_tokens")에는 출력이 스키마와 맞지 않을 수 있습니다. 안전성과 제약은 구조적 제약보다 우선순위가 높기 때문입니다.

JSON Schema의 모든 기능이 지원되는 건 아닙니다. 재귀적 스키마, 복잡한 수치 제약, 외부 참조 등은 사용할 수 없습니다. 하지만 대부분의 실무 사용 사례에 필요한 기본 타입, enum, anyOf, allOf, $ref 등은 모두 지원됩니다.

프로덕션 준비 완료

Structured Outputs는 배치 처리, 토큰 카운팅, 스트리밍과 모두 호환됩니다. 같은 요청에서 JSON 출력과 Strict Tool Use를 함께 사용할 수도 있습니다. 다만 Citations(인용) 기능이나 Message Prefilling과는 함께 사용할 수 없습니다.

이 기능은 AI 애플리케이션의 신뢰성을 한 단계 끌어올립니다. 에러 처리 코드를 대폭 줄이고, 재시도 비용을 없애며, 프로덕션 환경에서 안정적으로 작동하는 AI 기능을 구현할 수 있게 됐습니다. 현재 Sonnet 4.5와 Opus 4.1에서 베타로 제공 중이며, Haiku 4.5 지원도 곧 추가될 예정입니다.

참고자료:

• Structured outputs – Claude Docs

1

Like?