AI 개발자를 위한 구조화 출력과 함수 호출 설계 가이드: JSON 스키마부터 재시도까지

AI 모델을 활용하여 개발하는 애플리케이션을 구축할 때, 가장 먼저 부딪히는 문제는 AI의 출력을 어떻게 처리할지 결정하는 것입니다. 모델이 생성하는 결과물은 기본적으로 자연어 텍스트 형태입니다. 이 텍스트를 그대로 애플리케이션의 특정 기능이나 데이터베이스에 바로 사용하기 어렵습니다. 따라서 개발자는 AI의 응답을 프로그램이 이해하고 즉시 처리할 수 있는 형태로 변환해야 하는 과제에 직면합니다.

단순히 정보를 요약하거나 질문에 답하는 수준을 넘어, 특정 형식의 데이터를 요구하는 경우가 늘고 있습니다. 예를 들어, 사용자 입력으로부터 추출한 엔티티 목록이나, 특정 구조를 가진 설정 객체가 필요할 수 있습니다. 이러한 요구사항을 충족시키기 위해서는 AI 모델에게 출력을 단순 텍스트가 아닌, 정해진 규칙을 가진 구조화된 형태로 요청하는 기술이 필요합니다.

이러한 구조화된 출력을 제어하는 핵심 기술이 구조화 출력(Structured Output)입니다. 구조화 출력은 JSON 스키마와 같은 명확한 규칙을 이용해 모델의 응답 형식을 미리 지정합니다. 나아가, AI가 외부의 기능을 호출하여 작업을 수행하도록 하는 도구 호출(Tool Calling) 방식은 AI의 활용 범위를 확장하는 핵심 기술입니다. 이 글에서는 구조화 출력의 원리부터 JSON 스키마를 이용한 출력 제어 방법, 그리고 도구 정의와 함수 호출의 작동 방식까지 상세히 다룹니다.

구조화 출력의 원리와 필요성

구조화 출력(Structured Output)은 거대 언어 모델(LLM)의 응답을 개발자가 정의한 특정 형식, 즉 스키마(Schema)에 맞도록 제한하는 기능입니다. 이 방식은 모델이 생성하는 결과물이 단순한 텍스트가 아니라, 기계가 처리할 수 있는 유효하고 파싱 가능한 JSON(JavaScript Object Notation) 형태임을 보장합니다.

구조화 출력을 사용하면 모델의 응답 형식을 정밀하게 제어할 수 있습니다. 응답의 필드 이름, 각 필드가 가져야 할 데이터 타입, 그리고 필수적으로 포함되어야 하는 항목 등을 미리 정의할 수 있습니다. 이로 인해 다운스트림 시스템(Downstream System)에서 데이터를 처리할 때 발생하는 오류를 근본적으로 줄일 수 있습니다.

구조화 출력이 없을 경우, 모델은 문법적으로 틀린 JSON을 생성하거나, 필수적으로 포함되어야 할 필드를 누락할 가능성이 높습니다. 이러한 비구조적인 응답은 애플리케이션의 안정성을 저해하고, 개발자가 복잡한 오류 처리 로직을 추가해야 하는 원인이 됩니다.

다음 표는 구조화 출력이 적용되었을 때와 그렇지 않을 때의 응답 신뢰성 차이를 보여줍니다.

구분	구조화 출력 미적용 시	구조화 출력 적용 시
JSON 문법	문법 오류 발생 가능성 높음	문법적으로 유효한 JSON이 보장됩니다.
필드 누락	필수 필드가 누락될 수 있습니다.	스키마 정의에 따라 누락을 방지합니다.
데이터 타입	데이터 타입이 불일치할 수 있습니다.	정의된 데이터 타입(예: 숫자, 문자열)을 준수합니다.

따라서 구조화 출력은 단순히 형식을 맞추는 것을 넘어, 결과물의 **신뢰성(Reliability)**을 확보하는 핵심 메커니즘입니다. 이 기능은 모델이 생성한 데이터를 즉시 비즈니스 로직에 투입할 수 있도록 만듭니다. 이 원리를 이해하는 것은 LLM API 기초를 학습하는 데 필수적입니다.

JSON 스키마를 이용한 출력 제어

JSON 스키마(JSON Schema)는 원하는 데이터의 구조와 타입을 명확하게 정의하는 표준입니다. 이 스키마는 모델의 응답이 어떤 형태와 규칙을 따라야 하는지 지정하는 핵심 제어 기준이 됩니다. 스키마를 활용하여 모델에게 출력을 강제하면, 모델은 항상 유효한 JSON(JSON) 형식으로 응답을 반환합니다.

이러한 제어 방식을 통해 출력의 신뢰성이 높아집니다. 단순히 "JSON 형태로 응답해 주세요"라고 지시하는 것과 달리, 스키마는 어떤 필드가 반드시 존재해야 하는지, 그리고 그 필드의 데이터 타입이 무엇이어야 하는지를 구체적으로 규정합니다. 예를 들어, 특정 필드는 반드시 문자열이어야 하고, 다른 필드는 숫자여야 한다는 규칙을 강제할 수 있습니다.

스키마를 적용하면 필드의 누락이나 데이터 타입 오류가 원천적으로 방지됩니다. 이는 개발자가 모델의 출력을 받아 후속 처리(downstream processing)를 할 때 발생하는 파싱 오류를 최소화합니다. 구조화된 출력을 사용하면 결과가 항상 예측 가능한 형태를 갖추기 때문에, 별도의 복잡한 오류 처리 로직 없이 데이터를 즉시 사용할 수 있습니다.

스키마는 데이터 모델링의 관점에서 작동합니다. 개발자는 필요한 데이터를 가장 정확하게 반영하는 JSON 스키마를 설계하고, 이를 모델의 출력 제약 조건으로 제공합니다. 이 과정은 마치 데이터베이스의 테이블 구조를 미리 정의하는 것과 유사합니다.

JSON

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string"
    },
    "author": {
      "type": "string"
    }
  },
  "required": ["title", "author"]
}
```text
위 예시처럼 스키마를 정의하면, 모델은 `title`과 `author` 두 필드를 반드시 포함하고, 각각이 문자열 타입인 JSON 객체를 반환하도록 제한됩니다. 이처럼 스키마를 이용한 출력 제어는 모델의 추론 능력과 시스템의 안정성을 결합하여, 신뢰도 높은 구조화된 데이터를 얻는 가장 확실한 방법입니다. 구조화된 출력을 활용하는 것은 [LLM API 기초](/dev/llm-api-basics/) 지식을 바탕으로 시스템을 설계할 때 필수적인 고려 사항입니다.

## 도구 정의와 함수 호출의 원리

도구 사용(Tool Use)은 대규모 언어 모델(LLM)을 외부 시스템이나 API와 연결하는 기능입니다. 모델이 단순히 텍스트를 생성하는 것을 넘어, 실제 작업을 수행할 수 있도록 확장하는 원리입니다. 개발자는 모델이 사용할 수 있는 도구(Tool) 목록을 정의하고 모델에 제공합니다. 이 도구 목록에는 각 도구의 기능 설명과 필요한 입력값(arguments)의 구조가 포함됩니다.

모델은 사용자 요청을 받은 후, 제공된 도구 목록을 참조하여 어떤 도구를 호출해야 가장 적절한지 판단합니다. 모델이 호출을 결정하면, 응답으로 호출할 도구의 이름과 그에 필요한 인자들을 구조화된 형태로 반환합니다. 이 과정에서 모델은 직접 API를 호출하지 않습니다. 대신, **어떤 도구를 어떤 인자로 사용해야 하는지에 대한 요청서**를 생성하는 것입니다.

이 요청서를 받은 애플리케이션이 실제 도구 실행을 담당합니다. 애플리케이션은 모델이 요청한 대로 외부 API를 호출하고, 그 실행 결과를 다시 모델에게 입력으로 전달합니다. 이 순환 과정을 통해 모델은 도구 실행의 결과를 바탕으로 최종적인 답변을 생성합니다.

도구 호출은 크게 두 가지 방식으로 나뉩니다. 하나는 개발자가 직접 제어하는 클라이언트 도구(Client Tools)를 사용하는 방식이며, 다른 하나는 시스템 제공자가 인프라 내에서 실행하는 서버 도구(Server Tools)를 사용하는 방식입니다. 이 구조는 모델이 외부 정보를 활용하는 방식에 대한 이해를 돕습니다.

이러한 도구 정의와 호출 원리를 이해하는 것은 LLM 에이전트(Agent)를 설계하는 핵심 단계입니다. 모델의 추론 능력과 외부 시스템의 실행 능력을 결합하여, 실질적인 업무 자동화가 가능해집니다. [LLM API 기초](/dev/llm-api-basics/) 섹션에서 다루는 API 개념과 연결하여 이해할 수 있습니다.

## 구현 방식: JSON 출력과 도구 사용

JSON 출력(JSON Output) 기능은 모델이 생성하는 응답의 형식을 특정 JSON 구조로 제한할 때 사용합니다. 이 기능을 사용하면 모델은 개발자가 정의한 스키마에 맞는 유효한 JSON 데이터를 반환합니다. 따라서 응답을 받아 후속 처리(downstream processing)를 할 때 데이터 파싱 오류가 발생할 위험을 줄입니다.

도구 사용(Tool Use) 기능은 모델이 자체 지식만으로 해결할 수 없는 외부의 기능이나 API를 호출할 필요가 있을 때 활용합니다. 개발자는 모델에게 사용 가능한 도구 목록을 정의하고, 모델은 사용자 요청을 분석하여 적절한 도구와 그에 필요한 인자(arguments)를 구조화된 형태로 결정합니다. 이 과정에서 모델은 어떤 도구를 호출해야 하는지 판단하는 역할을 수행합니다.

이 두 가지 기능은 독립적으로 사용할 수도 있고, 하나의 요청에서 함께 사용할 수도 있습니다. JSON 출력은 응답 데이터의 구조적 무결성을 보장하고, 도구 사용은 외부 세계와의 상호작용 능력을 부여합니다. 이 두 기능을 결합하면, 모델이 외부 기능을 호출한 후 그 결과를 다시 특정 JSON 형식으로 구조화하여 반환하는 복잡한 워크플로우를 설계할 수 있습니다.

두 기능의 역할 차이를 이해하면 구현에 도움이 됩니다.

| 기능 | 목적 | 결과물의 형태 | 사용 시점 |
| :--- | :--- | :--- | :--- |
| JSON 출력 | 응답 데이터의 형식 제어 | 유효한 JSON 문자열 | 데이터 추출 및 구조화가 필요할 때 |
| 도구 사용 | 외부 기능 호출 및 실행 | 호출할 함수와 인자 구조 | 실시간 정보 검색이나 계산이 필요할 때 |

이러한 구조화된 출력을 활용하는 방식은 [LLM API 기초](/dev/llm-api-basics/) 개념과 연결됩니다. 모델의 출력을 단순 텍스트가 아닌, 예측 가능하고 기계가 처리하기 쉬운 형태로 강제하는 것이 핵심입니다.

## 검증 및 오류 처리의 필요성

구조화 출력(Structured Output)을 사용하지 않을 경우, 모델의 응답은 개발자가 예상한 형식을 따르지 않을 수 있습니다. 이로 인해 JSON 문법 오류나 필드 누락 같은 파싱 오류가 발생할 위험이 높습니다. 응답 데이터의 타입 불일치나 스키마 위반이 발생하면, 애플리케이션의 후속 처리 과정 전체가 중단될 수 있습니다.

이러한 불안정성을 해결하기 위해 구조화 출력이 필요합니다. 구조화 출력은 모델의 응답을 사전에 정의된 JSON 스키마(JSON Schema)의 제약 조건 내에서만 생성하도록 강제합니다. 즉, 모델이 스키마를 벗어난 데이터를 생성하는 것을 근본적으로 방지합니다. 이 제약 덕분에 결과는 항상 유효하고 파싱 가능한 형태가 됩니다.

만약 구조화 출력이 없다면, 시스템은 모델의 응답을 받은 후 유효성 검사(validation) 로직을 복잡하게 구현해야 합니다. 스키마 위반이 감지될 때마다 재시도(retry) 메커니즘을 설계하거나, 복잡한 예외 처리 코드를 작성해야 합니다. 이는 개발 난이도를 높이고 시스템의 안정성을 떨어뜨리는 원인이 됩니다.

구조화 출력을 사용하면 이러한 오류 처리 과정이 대폭 간소화됩니다. 모델 자체가 스키마를 준수하도록 제어되므로, 개발자는 응답을 받은 후 유효성 검사에 드는 노력을 줄일 수 있습니다. 도구 사용(Tool Use) 기능 역시 마찬가지입니다. 모델이 호출할 도구의 이름이나 인자(arguments)가 정의된 스키마를 따르도록 제한함으로써, 외부 API 호출을 위한 입력 데이터의 신뢰성을 확보합니다.

구조화 출력과 도구 사용은 단순히 JSON 형태로 데이터를 받는 수준을 넘어섭니다. 이 기능들은 시스템의 안정성과 신뢰성을 보장하는 핵심 메커니즘입니다. 이를 통해 개발자는 모델의 응답이 예측 가능하고, 후속 비즈니스 로직에 즉시 투입될 수 있는 상태임을 확신할 수 있습니다.

## 흔한 오해

**"JSON 스키마를 사용하면 모델이 항상 완벽한 데이터를 생성합니다."** JSON 스키마는 응답의 구조와 데이터 타입을 보장하여 파싱 오류를 방지합니다. 하지만 스키마가 정의하는 필드에 들어갈 내용의 정확성이나 논리적 오류는 별도로 검증해야 합니다.

**"도구 사용은 단순히 API 호출 목록을 나열하는 기능입니다."** 도구 사용은 모델이 주어진 도구 중 어떤 것을 호출해야 할지 결정하는 과정입니다. 모델은 사용자의 요청에 맞춰 적절한 도구와 그에 필요한 인자를 구조화하여 호출합니다.

**"구조화 출력을 사용하면 모든 파싱 오류가 사라집니다."** 구조화 출력은 JSON 문법적 오류를 방지하여 응답을 항상 유효한 JSON 형태로 만듭니다. 그러나 데이터 타입이나 필드 누락 같은 논리적 오류는 여전히 별도의 검증 절차가 필요합니다.

## 정리

- 구조화 출력은 모델의 응답을 특정 스키마에 맞춰 유효한 JSON 형태로 제한합니다.
- JSON 스키마를 활용하여 데이터의 구조와 타입을 명확하게 정의할 수 있습니다.
- 도구 사용은 모델이 외부 기능을 호출하도록 연결하는 핵심 메커니즘입니다.
- 구조화 출력을 사용하면 응답의 유효성이 높아져 애플리케이션 안정성이 향상됩니다.

## 참고 자료

- [Anthropic — 구조화 출력](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) — JSON 스키마로 응답 형식 강제
- [Anthropic — 도구 사용](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) — 함수 호출과 도구 정의
- [JSON Schema Reference](https://json-schema.org/understanding-json-schema/reference) — 스키마 작성 문법

구조화 출력의 원리와 필요성

JSON 스키마를 이용한 출력 제어

AI 개발의 다른 글

LLM API 기초: 요청, 스트리밍, 에러 처리

프롬프트 설계: 재현 가능한 출력을 얻는 법

RAG 파이프라인 설계: 검색으로 환각 줄이기

AI 에이전트 개발 가이드: 도구 사용, 루프 구조, 실패 처리 원리