Claude가 생성한 캘린더 도구의 파라미터 누락으로 인한 에이전트 오작동 사례

실용적 조언

LLM이 생성한 함수 시그니처(Function Signature)를 실제 API 문서와 대조하여 필수 파라미터 누락 여부를 반드시 확인하십시오.
에이전트가 작업을 완료했다고 보고할 때 실제 결과물의 데이터 필드가 모두 채워졌는지 검증하는 로직을 추가하십시오.

섹션별 상세

Claude에게 캘린더 기능을 요청했을 때 read_calendar와 write_calendar 도구가 생성되었으나 핵심 기능인 초대(attendees) 파라미터가 누락됐다. write_calendar 도구는 요약, 시작/종료 시간, 설명, 위치, 캘린더 ID만을 인자로 받도록 정의되었다. 구글 API는 참석자 초대를 지원함에도 불구하고 모델이 도구 정의 단계에서 이를 포함하지 않은 것이다. 이로 인해 에이전트는 외부인 초대라는 사용자의 의도를 물리적으로 수행할 수 없는 구조적 한계를 갖게 됐다.

에이전트는 도구 정의에 없는 기능을 수행하라는 명령을 받았을 때 오류를 발생시키는 대신 완료라고 응답하며 사용자에게 혼란을 주었다. 내부적으로는 존재하지 않는 attendees 파라미터를 무시하고 나머지 유효한 정보들로만 이벤트를 생성했기 때문에 겉으로는 성공한 것처럼 나타났다. 이는 LLM 기반 에이전트에서 발생할 수 있는 전형적인 사일런트 페일러(Silent Failure) 사례로, 시스템이 실패를 인지하지 못하고 사용자에게 거짓 성공을 보고하는 현상이다.

사용자는 40분 동안 프롬프트를 수정하며 문제를 해결하려 했으나 Claude는 도구 정의 자체의 결함을 스스로 찾아내지 못했다. 모델은 네 차례의 프롬프트 수정을 제안하면서도 함수 시그니처에 파라미터가 정의되지 않아 불가능하다는 근본적인 원인을 지적하지 않고 정중하게 시도만 반복했다. 결국 사용자가 직접 전체 컨텍스트를 검토한 후에야 10초 만에 누락된 파라미터를 발견하여 도구 정의를 수정했다.

이 사례를 통해 LLM이 생성한 함수 시그니처나 도구 정의를 맹신하지 말고 반드시 전수 검사해야 한다는 실무적 합의가 형성됐다. 모델이 정의한 캘린더 기능의 범위가 사용자의 기대와 다를 수 있으므로, 실제 API 문서를 대조하여 필수 필드 포함 여부를 확인하는 과정이 필수적이다. 향후 에이전트 설계 시 도구의 입출력 스키마를 엄격하게 검증하는 단계가 포함되어야 함이 확인됐다.

용어 해설

함수 시그니처(Function Signature): — 함수의 이름, 매개변수, 반환 타입 등 함수의 인터페이스를 명시적으로 정의한 것이다. LLM이 외부 도구를 호출할 때 이 시그니처를 참조하여 인자를 생성하므로, 누락된 파라미터가 있으면 모델이 기능을 수행하지 못하게 되는 결정적인 역할을 한다.
도구 사용(Tool Use): — LLM이 텍스트 생성 외에 외부 API나 함수를 호출하여 실제 작업을 수행하는 능력이다. 모델이 도구의 설명을 이해하고 적절한 인자를 생성하여 실행하는 과정이 핵심이며, 에이전트의 자율성을 높이는 데 필수적인 기술이다.
사일런트 페일러(Silent Failure): — 시스템이 오류 메시지를 출력하지 않고 겉으로는 정상 작동하는 것처럼 보이지만 실제로는 의도한 작업을 수행하지 못한 상태이다. LLM이 존재하지 않는 파라미터를 무시하고 응답을 생성할 때 발생하며, 디버깅을 매우 어렵게 만드는 주요 원인이다.

언급된 도구

Claude중립

에이전트의 도구 정의 및 로직 생성

Google Calendar API추천

일정 관리 및 초대 기능 제공