콘텐츠로 이동

도구 스키마와 검증 (Schemas)

모델이 도구를 정확히 호출하려면, "어떤 도구가 있고 어떤 인자를 받는지"를 미리 알아야 합니다. 그 정보를 모델에게 알려주는 형식이 도구 스키마(Schema) 입니다. 스키마는 모델에게 인자 형태를 가르치는 동시에, 모델이 만들어낸 도구 호출을 우리가 검증하는 기준이 됩니다. 이 페이지는 공식 가이드 OpenAI Function Calling 을 바탕으로 도구 스키마와 검증을 설명합니다.

개요

함수 호출은 모델이 "어떤 함수를, 어떤 인자로 부를지" 결정하는 것이라고 했죠. 그런데 그 결정이 정확해지려면 모델이 각 도구의 인자 형태를 알고 있어야 합니다. 스키마는 그 정보를 기계가 읽을 수 있게 정의한 것입니다. 모델은 스키마를 읽고 올바른 인자를 만들어내고, 우리 코드는 그 인자가 스키마에 맞는지 검증해 잘못된 값이 실행에 들어가는 것을 막습니다. 이 구조가 도구 호출을 신뢰 가능하게 만듭니다.

핵심 개념

스키마가 하는 일

스키마는 크게 두 가지 일을 해요. 하나는 모델에게 인자 형태를 알려주는 것이고, 다른 하나는 모델이 만든 도구 호출을 검증하는 기준이 되는 것입니다. 예를 들어 moveElement 도구의 인자가 x, y 숫자 두 개라는 것을 스키마로 정의하면, 모델은 그 형태에 맞춰 호출하고, 우리는 받은 값이 숫자인지 검증합니다.

JSON 스키마 형태

도구의 이름·설명·매개변수 형태를 JSON 스키마로 정의합니다. 각 인자의 타입(문자열, 숫자, 배열 등), 필수 여부, 설명을 담아요. 모델은 이 설명을 읽고 올바른 값을 만들어냅니다. 예를 들어 날씨 도구면 location은 문자열이고 설명에 "도시와 주 이름"이라고 적는 식이죠. 인자에 대한 설명이 풍부할수록 모델이 정확한 값을 만들 가능성이 높아집니다.

타입 안전한 스키마 (Zod/JSON Schema)

타입스크립트 환경에서는 스키마를 직접 JSON으로 쓰기보다 Zod 스키마로 정의하고 AI SDK가 변환하게 하는 방식이 자주 쓰입니다. z.object({ x: z.number(), y: z.number() })처럼 쓰면, 모델에게 보낼 JSON 스키마가 자동 생성되고 타입도 추론됩니다. 스키마 하나로 모델 전달(프롬프트)과 코드 검증(런타임)을 함께 처리하는 것이 이점이에요.

검증(Validation) — 잘못된 호출 막기

스키마는 단순 문서가 아니라 검증 기준입니다. 모델이 인자를 잘못 만들면 코드는 그 호출을 스키마와 대조해 거부하거나 바로잡습니다. 예를 들어 숫자여야 할 x에 문자열이 오면 실행에 들어가지 않게 막아요. 이게 없으면 모델의 오류가 고스란히 실행 오류로 이어집니다.

엄격 모드 (Strict)

공급자가 지원하면 엄격한 도구 호출(strict mode) 을 켤 수 있습니다. 모델이 스키마에 정의된 인자와 타입을 더 엄격히 따르도록 강제해서, 예상 밖의 인자나 형식이 섞이는 것을 줄여줍니다. 스키마가 단정적이라면 이 옵션으로 검증을 더 단단하게 만들 수 있어요.

실제 적용 (데이터스케쳐스)

  • 캔버스 요소 배치 — moveElement의 인자를 z.object({ x: z.number(), y: z.number() })로 정의해, 모델이 좌표를 제대로 만들도록 하고 실행 전에 검증합니다.
  • 데이터 조회 도구 — 조회 함수의 인자(예: 테넌트 ID, 날짜 범위)를 스키마로 정의해, 잘못된 값이 쿼리에 들어가는 것을 막습니다.
  • 뉴런 행동 결정 — 행동 도구의 인자 형식을 스키마로 고정해, 에이전트가 형식에 맞는 결정만 내리게 합니다.
  • 엄격 모드 적용 — 스키마가 단정적인 도구는 strict를 켜서 검증을 강화합니다.

더 알아보기