Agent는 블랙박스다

Agent를 배포하면 이런 질문이 온다.

"Agent가 왜 그렇게 답했어?" "어제보다 느려진 것 같은데?" "API 비용이 얼마나 나오는 거야?"

답하려면 모니터링이 필요하다.

---

핵심 지표 (KPI)

지표	설명	목표
응답 시간	질문~최종 응답	< 15초
Tool 호출 수	질문당 평균	< 5회
정확도	현장 만족도	> 90%
캐시 히트율	캐시 적중률	> 50%
에러율	Tool 실패율	< 5%
Token 비용	질문당 비용	< $0.01

---

구조적 로깅

import json
import time
from datetime import datetime

class AgentMonitor:
    """Agent 실행을 모니터링합니다."""

    def __init__(self):
        self.sessions = []

    def start_session(self, user_query: str) -> dict:
        return {
            "query": user_query,
            "start_time": time.time(),
            "tool_calls": [],
            "tokens": {"input": 0, "output": 0},
            "errors": [],
        }

    def log_tool_call(self, session: dict, tool_name: str,
                      args: dict, result: str, duration: float,
                      cached: bool):
        session["tool_calls"].append({
            "tool": tool_name,
            "args": args,
            "result_length": len(result),
            "duration_ms": round(duration * 1000),
            "cached": cached,
            "timestamp": datetime.now().isoformat()
        })

    def end_session(self, session: dict, response: str,
                    token_usage: dict):
        session["end_time"] = time.time()
        session["total_time"] = session["end_time"] - session["start_time"]
        session["response_length"] = len(response)
        session["tokens"] = token_usage
        session["tool_count"] = len(session["tool_calls"])
        session["cache_hits"] = sum(
            1 for tc in session["tool_calls"] if tc["cached"]
        )
        self.sessions.append(session)
        return session

    def get_dashboard(self) -> str:
        if not self.sessions:
            return "아직 데이터가 없습니다."

        avg_time = sum(s["total_time"] for s in self.sessions) / len(self.sessions)
        avg_tools = sum(s["tool_count"] for s in self.sessions) / len(self.sessions)
        total_tokens = sum(s["tokens"].get("total_tokens", 0) for s in self.sessions)
        error_count = sum(len(s["errors"]) for s in self.sessions)

        return f"""Agent 대시보드 ({len(self.sessions)}개 세션):
  평균 응답 시간: {avg_time:.1f}초
  평균 Tool 호출: {avg_tools:.1f}회
  총 Token 사용: {total_tokens:,}
  에러 발생: {error_count}건
  예상 비용: ${total_tokens * 0.000002:.4f}"""

---

LangSmith 연동 (권장)

LangChain을 사용하면 LangSmith로 자동 추적이 가능하다.

# 환경 변수 설정
export LANGCHAIN_TRACING_V2=true
export LANGCHAIN_API_KEY=your_key
export LANGCHAIN_PROJECT=equipment-agent

# 코드 변경 없이 자동 추적!
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
result = agent_executor.invoke({"input": "CNC-003 상태"})

# LangSmith 대시보드에서 확인:
# - 전체 실행 트레이스
# - 각 Tool 호출 상세
# - Token 사용량
# - 에러 발생 위치
# - 응답 시간 분포

LangSmith는 무료 플랜으로도 충분히 시작할 수 있다. Agent 디버깅에 필수 도구다.

---

현장 리포트 자동화

# 매일 아침 자동으로 리포트 생성
def daily_report(monitor: AgentMonitor):
    sessions = monitor.sessions  # 최근 24시간

    slow_queries = [s for s in sessions if s["total_time"] > 15]
    error_sessions = [s for s in sessions if s["errors"]]
    heavy_queries = [s for s in sessions if s["tool_count"] > 8]

    report = f"""일일 Agent 리포트 ({datetime.now().strftime('%Y-%m-%d')})

총 질문: {len(sessions)}건
평균 응답: {sum(s['total_time'] for s in sessions) / len(sessions):.1f}초

주의 항목:
  느린 질문(>15초): {len(slow_queries)}건
  에러 발생: {len(error_sessions)}건
  과도한 Tool 호출(>8회): {len(heavy_queries)}건
"""

    if slow_queries:
        report += "\n느린 질문 TOP 3:\n"
        for s in sorted(slow_queries, key=lambda x: -x["total_time"])[:3]:
            report += f"  - {s['query'][:50]} ({s['total_time']:.1f}초)\n"

    return report