Structured Outputs vs Tool Use vs Prefills: Getting JSON Out of Claude in 2026

개요

Claude 모델에서 JSON과 같은 구조화된 출력을 얻기 위한 기존의 사전 주입(prefill) 방식이 더 이상 지원되지 않으며, 이제는 output_config.format을 사용하는 구조화된 출력(Structured Outputs) 또는 도구 사용(Tool Use) 기능을 활용해야 합니다.

주요 내용

* 사전 주입(Prefill) 방식의 한계: Claude 모델의 이전 버전에서는 어시스턴트 턴에 JSON의 시작 부분(예: {)을 사전 주입하여 JSON 출력을 유도했으나, Opus 4.6+ 및 Fable 5 버전부터는 이러한 방식이 400 에러를 발생시키며 더 이상 작동하지 않습니다.
* 구조화된 출력 (Structured Outputs):
* JSON 스키마와 같이 특정 형식의 출력을 원할 때 사용됩니다.
* output_config.format 옵션을 통해 Zod 스키마와 같은 정의를 지정할 수 있으며, SDK가 응답을 스키마에 맞춰 자동으로 검증합니다.
* 검증에 실패하면 parsed_output이 null이 되며, 모델이 스키마를 벗어나는 출력을 생성하는 것을 방지합니다.
* 주의사항: 숫자 제약 조건은 서버 측에서 강제되지 않고, 재귀 스키마는 지원되지 않으며, 모든 객체에는 additionalProperties: false가 필요합니다.
* 도구 사용 (Tool Use):
* 모델이 구조화된 인자를 사용하여 특정 작업을 수행하도록 할 때 유용합니다.
* 분류와 같이 특정 도구를 호출하는 데 JSON이 부수적인 결과물로 사용되는 경우에 적합합니다.
* tools 매개변수를 사용하여 도구의 이름, 설명, 입력 스키마 등을 정의할 수 있습니다.
* tool_choice를 특정 도구로 강제하면 모델이 해당 도구를 호출하도록 유도합니다. strict: true 옵션은 인자가 스키마에 유효하도록 보장합니다.
* 구조화된 출력 vs. 도구 사용 선택 기준:
* JSON이 최종적인 "답변"이고 직접 파싱하여 사용할 경우: 구조화된 출력.
* JSON이 다음 단계를 위한 "인자"이며 다른 도구에 전달될 경우: 도구 사용.
* 텍스트에서 필드를 추출하여 레코드를 구축하는 경우: 구조화된 출력.
* 에이전트가 여러 작업 중 하나를 선택하는 경우: 도구 사용.
* 기타 사전 주입 트릭 대체:
* 분류 레이블 강제: enum이 있는 도구 또는 구조화된 출력.
* 서론 생략: 시스템 프롬프트에 "응답 시작 부분 없이 바로 응답하라"는 지시.
* 잘못된 거부 회피: 현재 모델들은 거부를 더 적절하게 처리하므로 일반적인 프롬프트로 충분.
* 중단된 응답 이어가기: 사용자 턴에 이어서 작성하려는 내용을 포함시키고 "이전 응답이 X로 끝났으니 거기서부터 이어가라"고 지시.

시사점

Claude 모델에서 안정적인 구조화된 출력을 얻기 위해서는 API 레벨에서 제공하는 구조화된 출력(output_config.format) 또는 도구 사용(tools) 기능을 활용하는 것이 필수적이며, 이는 기존의 불안정한 사전 주입 방식보다 훨씬 견고하고 유지보수하기 쉽습니다.