우리 API 문서는 AI 에이전트에게 실패하는 바로 그 행동을 하라고 안내했다

AI 에이전트가 사용하는 헬프데스크 API에서 티켓 ID가 숫자로 반환되지만 입력은 문자열을 요구해, 흔한 도구 체인이 깨졌다.

감사 결과 대부분의 연쇄 호출이 스키마 검증에서 실패했으며, 실제 동작과 문서화된 계약 사이의 미묘한 타입 불일치가 드러났다.

팀은 공개 스키마를 바꾸지 않고 숫자 ID를 문자열로 전처리하는 방식으로 문제를 해결해 에이전트 워크플로를 복구했다.

이번 사례는 작은 입출력 타입 차이도 AI 에이전트 도구를 조용히 망가뜨릴 수 있으며, 특히 MCP 통합에서 API 테스트와 문서가 실제 기계 동작과 일치해야 함을 보여준다.