#대모델 도구 호출 Schema 설계

Schema는 인터페이스 문서가 아니라 모델이 도구를 선택하고 사용하기 위한 조작 설명서다. 모델에게 보여주는 「도구 메뉴판」에 해당하며, 명확히 쓰지 않으면 모델이 엉뚱한 것을 주문한다.

#원칙 1: 도구 명명은 업무 동작에 밀착시킬 것

// ✅ 권장: 명확하고 분명함
function query_user_order() {
  // 명확한 업무 동작
}

// ❌ 반례: 모호함
function getData() {
  // 범위가 지나치게 넓음
}

모델은 당신의 백엔드 동료가 아니다. 모호한 함수명 뒤에서 도대체 무엇을 조회하고, 무엇을 바꾸며, 부작용이 있는지 알지 못한다.

#원칙 2: 파라미터는 적고 정확하게

#원칙 3: 읽기와 쓰기를 분리할 것

리스크: 권한 통제가 복잡해지고, 감사 추적이 어려워진다

삭제  ┐
결제  ├──▶ 개별 도구 신설 + 확인 플로우 추가
외부 발송 ┘

#원칙 4: 에러 피드백을 구조화할 것

도구 호출이 실패하면 실패의 유형을 모델에게 명확히 알려야 한다

• 파라미터 부족
• 권한 부족
• 객체 없음
• 서비스 타임아웃

#정리

Function Calling의 Schema는 단순한 인터페이스 문서가 아니라 모델이 도구를 선택하고 사용하기 위한 조작 설명서다. 설계 시 도구 책임을 명확히, 명명은 업무에 밀착, 파라미터는 강하게 제약, 읽기·쓰기는 분리하고 구조화된 에러 피드백을 제공해야 한다. Schema가 실행 가능한 명세에 가깝게 쓰일수록 도구 호출이 안정된다.

#핵심 통찰

1. Schema의 독자는 모델이지 사람이 아니다 — 이 문서의 근본 명제. 인터페이스 문서는 사람이 컨텍스트를 보충할 수 있지만(동료에게 묻고 코드를 보고), 모델에게는 Schema 하나뿐이므로 어떤 생략도 환각의 입구가 된다.
2. 나쁜 Schema의 실패 모드는 「호출 안 함」이 아니라 「잘못 호출함」이다 — 「모델은 도구를 호출할 줄 모르는 게 아니라, 잘못된 타이밍에 잘못된 도구를 호출한다」는 것이 가장 반직관적이면서 값진 판단이다. 이는 Schema 문제가 성공률 지표에는 드러나지 않고 오직 잘못된 행동으로만 드러난다는 뜻이므로 발견하기가 더 어렵다.
3. 명명이 곧 의미 주석이다 — getData와 query_user_order는 코드 층위에서 동등하지만 모델의 눈에는 차이가 크다. 후자는 「동작(query) + 주체(user) + 객체(order)」를 전부 이름에 써넣어 제약 세 개를 공짜로 제공한다.
4. 선택 공간을 「생성」에서 「선택」으로 되돌릴 것 — 열거형 vs 자유 문자열, 필드 분할 vs 자연어 덩어리는 본질적으로 모델의 개방형 생성 작업을 폐쇄형 선택 작업으로 강등시키는 것이다. 제약이 강할수록 오류 확률이 낮아지며, 이것이 Agent 안정성을 높이는 가장 저렴한 수단이다.
5. 읽기·쓰기 분리는 Agent 장면에서 아키텍처 결벽증이 아니라 보안 경계다 — 조회와 수정이 한 도구에 섞이면 권한 통제를 도구 단위로 걸 수 없고, 감사도 「보기만 했다」와 「고쳤다」를 구분할 수 없다.
6. 고위험 동작은 「도구 단위 + 확인 플로우」 이중 보험으로 — 삭제, 결제, 외부 발송은 불가역이다. 방안은 개별 도구를 만들고(권한과 감사를 걸기 쉽게) 동시에 확인 플로우를 더하는 것(사람을 루프에)이다. 둘 중 하나만으로는 부족하다.
7. 에러 정보는 Agent의 피드백 신호이므로 기계가 읽을 수 있어야 한다 — 구조화된 에러가 있어야 모델이 「파라미터를 보충해 재시도」, 「다른 도구로 전환」, 「포기」를 구분할 수 있다. 자연어 스택트레이스 덩어리를 반환하는 것은 모델에게 노이즈 속에서 추측하라는 것과 같다.
8. 최종 판단 기준: Schema가 실행 가능한 명세에 가까울수록 좋다 — Schema가 합격인지 판단하는 간단한 방법은 이렇게 묻는 것이다. 당신의 시스템을 한 번도 본 적 없는 엔지니어가 이 Schema만 읽고 올바르게 호출할 수 있는가? 모델의 요구 수준은 그보다 더 높다.

#엔지니어링 실전 Tips

• REST 인터페이스를 1:1로 tool에 매핑하지 말 것. 백엔드 인터페이스는 리소스 기준으로 조직되고 도구는 업무 동작 기준으로 조직되어야 하며, 둘의 입도는 다르다.
• 파라미터의 description에는 「타입 설명」이 아니라 「업무 제약」을 쓸 것 — "주문번호, 18자리 숫자, 사용자의 직전 질문에서 유래"가 "문자열"보다 훨씬 낫다.
• 열거값은 내부 코드(0 / 1 / 2)가 아니라 업무 언어(결제 대기 / 발송 완료)로 쓸 것을 권장한다. 모델은 전자에 훨씬 잘 정렬된다.
• 도구 수가 팽창하면 「책임 단일」과 「도구가 너무 많아 모델이 못 고름」이 충돌한다. 이때는 책임 단일을 우선 지키고, 도구 그룹핑이나 장면별 동적 도구 목록 재단으로 선택 문제를 해결할 것.
• 구조화 에러는 {code, message, hint} 3단 형식을 권장한다. 그중 hint는 모델이 보라고 쓰는 다음 단계 제안이며, 실측상 code만 주는 것보다 수렴이 빠르다.
• 고위험 도구의 확인 플로우는 도구 실행 전에 발생해야 한다. 그렇지 않으면 모델이 이미 「완료」를 컨텍스트에 써버렸을 수 있다.
• 상용 전 「신입 동료 테스트법」으로 자가 점검할 것: Schema만 따로 시스템을 모르는 사람에게 보내고, 그가 올바른 호출 하나를 구성할 수 있는지 볼 것.