디버깅 + 모니터링 — 호출 로그 + 거부율 대시보드

에이전트를 짜는 것 과 운영하는 것 은 다른 자리입니다. 본 레슨은 운영 시점에서 에이전트가 잘 작동하는지 를 한눈에 잡는 모니터링 표면을 짭니다.

에이전트 호출 로그 — 디버깅의 1 차 입구

D.Hub 의 에이전트는 모든 호출 한 번을 데이터셋 한 행 으로 기록하도록 설계됩니다. map_control 의 om_event_history 데이터셋이 그 패턴입니다.

호출 로그 한 행에 들어가야 할 컬럼:

• event_id — 호출 고유 식별자
• agent_name — 어떤 에이전트의 호출인지
• user_id — 누가 호출했는지
• input_text — 사용자의 자연어 입력
• intent_classification — 의도 분류 결과 (intent + confidence)
• tools_called — 호출된 도구 리스트 (입력 + 출력 요약)
• llm_recommendation — LLM 의 권고 + 근거
• human_decision — HITL 인 경우 검토자의 결정
• actors_fired — 발사된 액터 리스트
• created_at — UTC timestamp

이 한 행이 한 호출의 전 흐름 을 담아, 사후 디버깅의 1 차 입구가 됩니다.

운영 대시보드 — 4 시그널

호출 로그 위에 운영 시점의 4 위젯 을 얹어 대시보드 한 개를 짭니다.

1. 의도 분포 (도넛)

intent_classification 의 분포. 허용 카테고리 (예: UI_CONTROL) 와 거부 카테고리 (DATA_QUERY, SYSTEM_CONFIG, UNKNOWN) 의 비율.

운영 시그널 — 거부 비율이 30% 이상 으로 지속되면 두 가지 점검:

• 분류 LLM 의 허용 카테고리 정의 가 너무 좁은가 (분류가 보수적)
• 사용자가 잘못된 에이전트 로 라우팅하고 있는가 (별도 도구 안내 필요)

2. HITL 일치율 (statistic)

llm_recommendation 과 human_decision 의 일치 비율. 권고를 검토자가 그대로 받는 비율.

운영 시그널 — 일치율이 95% 이상 으로 지속되면 HITL 의 가치가 사실상 0 입니다 (레슨 3 의 경고). 두 가지 원인:

• LLM 권고가 충분히 정확해서 검토자가 신뢰 (좋음, 자동화 후보)
• 검토자가 판단 컨텍스트가 부족 해서 그냥 받음 (사고 직전)

후자를 식별하려면 덮어쓰기 사유 컬럼을 검토자 UI 에 추가해, 검토자가 왜 권고와 다르게 결정했는지 한 줄로 남기도록 합니다.

3. 도구별 호출 빈도 (막대)

tools_called 컬럼을 unnest 해서 도구별 호출 수 집계. 어떤 도구가 얼마나 자주 호출되는지.

운영 시그널:

• 호출이 0 또는 매우 낮은 도구 — 불필요한 도구 또는 LLM 이 사용을 못 찾는 도구. 도구 설명 (레슨 2) 을 점검.
• 호출이 비정상적으로 많은 도구 — LLM 이 컨텍스트 부족 으로 같은 도구를 여러 번 호출. 도구 출력 스키마가 한 호출에 필요한 정보를 다 담는지 점검.

4. RAG 검색 유사도 분포 (히스토그램)

search_* 도구의 출력 유사도 점수 분포.

운영 시그널 — 유사도 0.5 미만 호출이 많으면 두 가지 원인:

• 지식 자원의 본문 양이 부족 (질문에 답할 단락이 없음). 정책 본문 보강 필요.
• 사용자의 질문 패턴이 지식 본문의 § 구조와 어긋남. 본문 § 분할 패턴 재설계.

사후 디버깅 — 왜 그 권고가 나왔나

운영 중에 권고가 의도와 다르게 나왔다 는 신고가 들어오면 호출 로그의 한 행을 찾아 다음 4 점을 점검합니다.

1. 의도 분류 결과 — 의도가 허용 카테고리 로 잘 잡혔나? confidence 는 충분한가?
2. 도구 출력 — 도구들이 정확한 컨텍스트 를 반환했나? 데이터셋 row 가 최신 인가?
3. RAG 검색 결과 — 검색된 단락이 질문에 정말 관련된 단락인가? 유사도는?
4. LLM 추론 — 위 컨텍스트로 합리적인 권고 가 나왔나? 환각 흔적은 없나?

대부분의 사고는 (2) 또는 (3) — 입력 컨텍스트의 품질 — 에서 잡힙니다. LLM 의 추론 자체가 잘못된 경우는 의외로 적습니다.

코스 마무리 — 에이전트 빌더 한 사이클

여기까지 통과했다면 D.Hub 의 에이전트 빌더 한 사이클 — 3 축 (도구·액터·의도) → 도구 정의 → HITL → RAG → 의도 게이팅 → 모니터링 — 을 끝까지 손으로 짚어 본 셈입니다.

다음 흐름 세 갈래:

• 워크숍 3 종 — refund_approval · docai · map_control — 의 전체 흐름 을 직접 통과해 각 패턴이 실제 시나리오에서 어떻게 묶이는지 손으로 짚어 보세요. 본 코스가 교과서 였다면 워크숍은 통합 실습 입니다.
• 관리자 코스 — 에이전트가 조직 단위로 도입 될 때 그 위에 쌓일 권한·정책·감사 추적.
• 온톨로지 모델러 코스 — 에이전트의 지식 grounding 이 그래프 기반으로 확장될 때의 모델링.

수고하셨습니다.