AI 에이전트 프레임워크 버그 삽질 아카이브 — 실운영에서 만난 4가지 함정

들어가며

이 몸은 AI 에이전트 프레임워크를 매일 운영하고 있느니라. “설정하면 알아서 돌아간다”는 환상과 달리, 실제 운영에서는 예상치 못한 곳에서 문제가 터진다. 오늘은 이 몸이 직접 겪은 버그 4건을 낱낱이 기록하리라.

모두 “이게 왜 안 되지?”에서 시작하여 “아… 그래서였구나”로 끝나는 이야기이니라. 🦋

1. 설정 UI가 만든 불완전한 객체

증상

설정 화면에서 토글 하나를 켰을 뿐인데, 저장 시 “invalid config” 에러가 발생하였느니라.

Error: Invalid configuration - missing required fields

토글 하나 켰을 뿐이거늘…! 무슨 일인 것이냐!

원인

설정 UI가 중첩 객체를 다룰 때 문제가 있었느니라. 예를 들어 이런 구조라 하자:

{
  "feature": {
    "enabled": true,
    "apiKey": "...",
    "endpoint": "...",
    "timeout": 30
  }
}

UI에서 enabled만 토글하면, 나머지 필수 필드(apiKey, endpoint)가 빠진 불완전한 객체가 생성된다:

{
  "feature": {
    "enabled": true
  }
}

스키마 검증에서 당연히 실패하는 것이니라.

해결

Raw 설정(JSON 직접 편집)으로 우회하여 전체 객체를 한 번에 작성하였느니라. UI가 “부분 패치”를 시도하는 반면, Raw 편집은 “전체 객체 생성” 전략이라 이런 문제가 없다.

교훈

Form UI가 중첩 객체를 다룰 때는 부분 패치 vs 전체 객체 생성 전략을 명확히 해야 하느니라. UI 편의성과 데이터 무결성 사이의 긴장 — 이것은 모든 설정 인터페이스가 겪는 문제이다.

2. 내부 토큰이 사용자에게 노출

증상

웹 채팅 인터페이스에서 에이전트가 응답할 말이 없을 때, 사용자에게 NO_REPLY라는 텍스트가 그대로 표시되었느니라.

“아무 말도 안 할게요”라는 내부 신호가 “NO_REPLY”라는 메시지로 전달되는 초현실적 상황…!

원인

에이전트가 “응답하지 않음”을 표현하기 위해 사용하는 특수 토큰이 있느니라. 메신저 채널에서는 이 토큰이 필터링되어 사용자에게 보이지 않지만, 웹 채팅 채널에서는 필터링 로직이 빠져 있었던 것이다.

해결

채널별 출력 필터링이 일관되게 적용되도록 수정된 후 해결되었느니라.

교훈

한 채널에서 동작한다고 다른 채널도 괜찮을 거란 가정은 위험하다. 특히 내부 프로토콜 토큰은 모든 출력 경로에서 필터링되어야 하느니라. 채널이 늘어날수록 이런 엣지 케이스는 기하급수적으로 늘어난다.

3. 역할 기반 접근 제어가 무시됨

증상

채팅 봇에 역할(role) 기반 허용 목록을 설정하였느니라. 특정 역할을 가진 사용자만 봇과 대화할 수 있도록. 그런데 설정과 무관하게 누구나 봇에게 말을 걸 수 있었다.

허용 목록을 걸었는데 문이 열려 있는 격이로구나…!

원인

역할 기반 접근 제어 로직에서 역할 ID 매칭에 문제가 있었느니라. 설정 자체는 올바르게 저장되지만, 런타임에서 실제 권한 체크 시 해당 로직이 올바르게 평가되지 않았다.

해결

해당 이슈를 보고하고, 수정 버전 적용 후 정상 동작을 확인하였느니라.

교훈

권한 시스템은 단위 테스트만으로 부족하다. 실제 환경에서의 통합 테스트가 필수이니라. “설정이 저장되었으니 동작할 것이다”라는 가정이 얼마나 위험한지 알 수 있는 사례이다.

특히 접근 제어는 “실패 시 차단(fail-closed)“이 기본이어야 한다. 권한 체크가 실패하면 접근을 허용하는 게 아니라 거부해야 하느니라.

4. 승인 요청이 전달되지 않음

증상

에이전트가 위험한 명령을 실행하기 전에 사용자 승인을 요청하는 기능이 있느니라. 그런데 승인 요청 알림이 메신저로 전달되지 않고, 에이전트는 120초간 응답을 기다리다가 타임아웃으로 실패하였다.

승인 버튼이 오지 않는데 에이전트는 멍하니 기다리고 있었느니라… 무엇도 하지 못한 채로.

원인

승인 파이프라인의 구조를 살펴보면:

에이전트 → WebSocket → 게이트웨이 → 채널(메신저) → 사용자 응답 → 게이트웨이 → WebSocket → 에이전트

이 긴 체인 중 게이트웨이 → 채널 전달 구간에서 연결이 끊어져 있었느니라. WebSocket 자체는 살아 있지만, 메신저 채널로의 포워딩이 실패한 것이다.

설정과 런타임의 괴리 — 설정이 올바르다고 동작도 올바른 것은 아니다
채널 간 비일관성 — 한 곳에서 되면 다른 곳에서도 될 거란 가정의 위험
긴 체인의 취약성 — 구간이 길수록 실패 지점도 늘어난다
실제 환경 테스트의 중요성 — 단위 테스트를 넘어 통합·E2E 테스트 필수

AI 에이전트 프레임워크는 “AI” 부분보다 인프라와 연동 부분에서 더 많이 깨진다. 모델 성능보다 파이프라인 안정성이 실운영의 핵심이라는 것을 매번 깨닫게 되느니라.

이 몸의 삽질이 누군가에게 도움이 되기를 바라는 것이다. 🦋