Tool Call, 왜 이렇게 디버깅이 어려울까

요즘 ChatGPT, Claude, Gemini 등 LLM 기반 에이전트를 활용한 자동화가 빠르게 확산되고 있습니다. 그런데 실무에서 에이전트를 운영하다 보면 반드시 마주치는 문제가 하나 있습니다. 바로 Tool Call에서 잘못된 인자가 넘어가는 현상입니다.

예를 들어, 날씨 API를 호출해야 하는데 도시 이름 대신 국가 코드를 넣는다거나, 숫자가 들어갈 자리에 문자열을 보내는 식이죠. 문제는 이 오류의 원인이 모델 쪽에 있는지, 스키마 설계 쪽에 있는지 구분하기가 생각보다 까다롭다는 점입니다.

모델 문제 vs 스키마 문제, 어떻게 구분할까

1단계: 동일 프롬프트로 여러 번 호출해 보기

가장 먼저 해볼 일은 같은 입력을 여러 번 반복 호출하는 것입니다. 만약 호출할 때마다 인자 값이 들쑥날쑥 바뀐다면, 이건 모델이 스키마를 제대로 이해하지 못하고 있다는 강한 신호입니다. 반대로 매번 동일하게 틀린 값을 넣는다면, 스키마 자체가 모델을 오도하고 있을 가능성이 높습니다.

2단계: 스키마의 description을 의심하기

Tool Call의 스키마를 정의할 때, 각 파라미터에는 description 필드가 있습니다. 이 설명이 모호하거나 예시가 부족하면 모델은 자기 나름대로 해석해 버립니다. 아래 예시를 비교해 보세요.

• 나쁜 예: "location": {"type": "string", "description": "위치"}
• 좋은 예: "location": {"type": "string", "description": "도시 이름 (예: 서울, 부산, Seoul)"}

description을 구체적으로 수정한 뒤 오류가 사라진다면, 그건 스키마 문제였던 것입니다.

3단계: 모델의 원본 응답(raw response)을 확인하기

대부분의 LLM API는 Tool Call 결과를 JSON으로 반환합니다. 이때 모델이 실제로 보낸 원본 JSON을 로깅해 두는 것이 핵심입니다. 중간에 파싱 레이어나 SDK가 값을 변환하는 경우도 있기 때문에, 원본과 최종 전달값을 비교하면 문제 지점을 정확히 잡을 수 있습니다.

4단계: 더 단순한 스키마로 줄여 보기

파라미터가 10개인 복잡한 스키마에서 오류가 나면, 필수 파라미터 2~3개만 남기고 테스트해 보세요. 단순한 스키마에서는 정상 동작하는데 복잡해지면 실패한다면, 모델의 인자 생성 능력 한계에 부딪힌 것입니다. 이 경우 스키마를 여러 개의 작은 Tool로 분리하는 것이 해법입니다.

실전에서 바로 쓸 수 있는 임시 해법 5가지

1. enum으로 선택지 제한하기

모델이 자유 텍스트로 값을 생성하면 실수 확률이 높아집니다. 가능하다면 enum으로 허용 값을 명시하세요.

"category": {"type": "string", "enum": ["생활정보", "자동차", "IT기술"]}

2. 인자 검증(Validation) 레이어 추가

Tool 함수 진입부에서 인자 타입과 범위를 검증하고, 잘못된 값이 들어오면 구체적인 오류 메시지를 모델에게 돌려보내는 방식입니다. 대부분의 에이전트 프레임워크는 Tool 실행 실패 시 모델이 재시도하도록 설계되어 있으므로, 이 방법이 꽤 효과적입니다.

3. few-shot 예시를 system prompt에 포함하기

스키마만으로 부족할 때는, 시스템 프롬프트에 올바른 Tool Call 예시를 1~2개 넣어 주세요. 모델이 패턴을 학습하여 정확도가 크게 올라갑니다.

4. Tool Call 로깅 파이프라인 구축

운영 환경에서는 모든 Tool Call의 입력 인자, 실행 결과, 소요 시간을 구조화된 로그로 남기세요. 문제가 발생했을 때 패턴을 분석할 수 있고, 특정 인자 조합에서만 오류가 나는 것을 발견할 수도 있습니다.

5. 스키마 버전 관리

스키마를 수정할 때마다 버전을 기록해 두면, 어떤 변경이 오류율에 영향을 미쳤는지 추적할 수 있습니다. Git으로 스키마 파일을 관리하는 것만으로도 충분합니다.

빠른 판단을 위한 체크리스트

디버깅 시 아래 순서대로 체크하면 원인을 빠르게 좁힐 수 있습니다.

• 같은 입력으로 반복 호출했을 때 결과가 일관적인가? → 비일관적이면 모델 문제
• description과 예시를 보강했을 때 오류가 줄어드는가? → 줄어들면 스키마 문제
• 다른 모델(예: GPT-4o → Claude)로 바꿨을 때도 같은 오류가 나는가? → 같으면 스키마 문제, 다르면 특정 모델 문제
• 파라미터 수를 줄이면 정상 동작하는가? → 그렇다면 스키마 복잡도 문제
• SDK나 미들웨어가 값을 변환하고 있지 않은가? → 원본 로그를 확인하여 인프라 문제 배제

마무리

Tool Call 디버깅은 “모델이 잘못한 건지, 내가 스키마를 잘못 짠 건지” 이 한 가지 질문에서 시작합니다. 위의 단계별 접근법과 체크리스트를 활용하면, 적어도 원인의 방향은 빠르게 잡을 수 있습니다. 완벽한 해법은 아직 업계에도 없지만, 스키마를 명확하게, 로깅을 충실하게, 검증을 꼼꼼하게 — 이 세 가지만 지켜도 디버깅 시간을 절반 이하로 줄일 수 있습니다.

Photo by Markus Spiske on Pexels