AI Agent Tool Calling은 왜 JSON Schema에 의존하는가? 매개변수·타입 오류와 검증 방법

이 시리즈의 이전 게시물에서는 JSON 스키마, 함수 호출 및 MCP의 발전을 통해 이러한 요소가 존재하는 이유를 설명합니다. 도구 호출에서 MCP로의 JSON 데이터 흐름은 바이트가 이동하는 위치를 추적합니다. JSON 스키마가 표준 에이전트 계약이 되는지 여부는 생태계 융합을 포괄합니다. 이 기사는 도구 호출이 거의 필연적으로 JSON 스키마에 의존하는 이유와 매개변수 및 유형 오류를 분류하고 검증하는 방법이라는 실용적인 질문에 중점을 둡니다.

모델이 도구를 선택하고 매개변수를 채울 때 호스트는 "운을 신뢰"할 수 없습니다. 실행 전에 동일한 스키마에 대해 빠른 실패가 발생해야 합니다. 하나의 환각적인 주장은 데이터를 삭제하거나, 잘못된 이메일을 보내거나, 다음 차례를 독살할 수 있습니다. 요점: JSON 스키마는 모델 API, MCP 및 호스트 런타임 모두에서 이해되는 유일한 매개변수 계약입니다. 구문 분석 후 실행 전에 유효성을 검사하고 재시도를 위해 구조화된 오류를 다시 제공합니다.

도구 호출이 JSON 스키마에 의존하는 이유

도구 호출(함수 호출과 동일한 데이터 흐름)은 모델이 도구를 선택하고 계약과 일치하는 JSON 인수를 출력한다는 의미입니다. 세 당사자가 다음 사항에 동의해야 합니다.

• Model APIs: OpenAI, Gemini, and Anthropic Tools APIs describe parameters with JSON Schema; some vendors also constrain decoding with Schema.
• MCP: each Tool’s inputSchema is JSON Schema; Hosts often pass it through or trim to a subset when mapping to model APIs.
• 호스트 프로그램: 기계 판독 가능, 버전 지정 가능, CI 확인 가능 계약이 필요합니다. ajv, Python jsonschema 등은 "프롬프트의 JSON 형식"을 몇 배나 앞섰습니다.

Without Schema, hosts regex-parse or prompt-parse arguments—that breaks at Agent scale. Schema gives shape (which fields), types, and constraints (enum, minimum, pattern)—everything you need syntactically before calling HTTP/DB/MCP. Business rules (“does priority=high violate SLA?”) still need code; Schema blocks most hallucinations at the syntax layer.

User intent → model reads JSON Schema in tools[]
           → outputs tool_calls[].function.arguments (JSON string)
           → host JSON.parse + Schema validate
           → only then call MCP / HTTP / DB

스키마가 콜 체인에 있는 세 위치

Vs. Structured Output: Structured Output constrains the final user-facing JSON reply; Tool Calling Schema constrains execution parameters. You can share one Schema source (Pydantic / Zod), but validate Tool arguments on every tool_calls before execute.

매개변수 오류: 누락, 추가, 잘못된 이름, 구문

매개변수 오류는 JSON이 구문 분석할 수 있지만(또는 구문 분석하기 전에 실패함) 스키마 키 및 필수 규칙을 위반함을 의미합니다.

// Schema fragment
{
  "type": "object",
  "properties": {
    "ticket_id": { "type": "string", "description": "Ticket ID" },
    "note": { "type": "string" }
  },
  "required": ["ticket_id"],
  "additionalProperties": false
}

// Model output (missing ticket_id) → validation fails
{ "note": "Please handle ASAP" }

유형 오류: 불일치, 열거형, 중첩, 강제

유형 오류: 필드가 존재하지만 값의 JSON 유형 또는 형식이 스키마를 위반합니다.

Coercion: some validators coerce "10" to 10. In production Agents, prefer coercion off—silent fixes hide systematic drift. If you must coerce, document it and lock behavior in CI samples.

// Type error example
Schema: { "limit": { "type": "integer", "minimum": 1, "maximum": 100 } }
Model:  { "limit": " fifty " }  // string, not numeric → fail

유효성 검사: 구문, 인수, 엄격 모드

1. 스키마 자체의 유효성을 검사합니다.

Before registering tools, meta-validate parameters / inputSchema (draft 2020-12, etc.). JSON Toolbox in the browser works locally—don’t ship invalid Schema to model APIs.

2. 스키마에 대한 인수 검증

After JSON.parse(arguments), validate with the same Schema used at registration:

• JavaScript / TypeScript: ajv (mind draft and strict options)
• Python: jsonschema, Pydantic (model_validate after JSON parse)
• Codegen : Zod / Pydantic → JSON Schema 단일 소스

3. 공급업체 엄격 모드

OpenAI strict: true requires a stricter subset (e.g. all objects with additionalProperties: false). That reduces model-side errors but does not replace host validation—dialects differ by vendor; see the Contract article.

4. 샘플 기반 CI

도구별: 유효한 인수 샘플 + CI의 의도적인 실패. 스키마 변경으로 인해 API 변경이 중단됩니다.

엔드투엔드 파이프라인 및 오류 피드백

최소 파이프라인(데이터 흐름 문서 확장):

1. tools/list or static register → validate each inputSchema syntax
2. On tool_calls → JSON.parse(arguments)
   ├─ parse fail → tool message "JSON syntax error: …" → model retry
   └─ parse ok → ajv/jsonschema validate
        ├─ fail → structured errors (missing, type, enum) → feed back
        └─ ok → execute + optional business rules
3. Tool result → optional result Schema before append to messages
4. Log: schema version, raw arguments, error codes (no secrets)

Error feedback must be machine-readable: “ticket_id is required” beats “bad params, retry”. Many frameworks format validation errors as JSON in the tool role for self-correction.

실행에는 여전히 인증 및 멱등성이 필요합니다. 스키마는 "이 ticket_id가 사용자에게 속함"이 아닌 형태를 보장합니다.

실용적인 권장 사항

• 단일 스키마 소스 : Pydantic / Zod → MCP inputSchema + OpenAI 도구.
• 설명은 프롬프트입니다. 열거형 및 필수 규정 준수를 유도합니다. API 코드와 같은 스키마를 검토하세요.
• 간단한 스키마, 엄격한 유효성 검사: oneOf/$ref 깊이를 대상 API 하위 집합으로 자릅니다. 빠른 실패, 자동 수정 없음.
• 두 가지 필수 체크포인트: 실행 전 tool_calls 이후; MCP 이후 컨텍스트 이전 반환(결과가 모델에 제공되는 경우)
• 로컬에서 먼저 유효성 검사: 프로덕션 전에 JSON 도구 상자에 스키마 + 샘플 인수를 붙여넣습니다.
• 구조화된 출력과 분리: 사용자 응답 스키마 대 도구 스키마 - 병합하지 마세요.

FAQ

요약 및 다음 단계

도구 호출은 모델, MCP 및 호스트에 대한 공유되고 검증 가능한 매개변수 계약이기 때문에 JSON 스키마에 의존합니다. 매개변수 오류(누락, 추가, 잘못된 이름, 구문) 및 유형 오류(유형, 열거형, 중첩)를 분류합니다. 실행 전에 가로채고 자체 수정을 위해 구조화된 오류를 피드합니다.

다음: 하나의 실제 도구(예: 티켓 생성)를 선택하고, 스키마 + 유효한/잘못된 샘플을 작성하고, JSON 도구 상자에서 로컬로 검증한 다음 에이전트에 연결합니다. 시리즈 순서: 진화 → 데이터 흐름 → 계약 → 이 기사(검증).