새벽 2시의 문제

몇 주 전 새벽 2시, 나는 내가 만든 AI 에이전트가 무언가를 수행하는 것을 터미널을 통해 지켜보고 있었습니다. 원래는 깨진 테스트를 수정해야 했습니다. 하지만 에이전트는 그저 가만히 앉아 이상한 줄들을 출력하며, 조용히 모델을 반복해서 호출하고 있었습니다.

멈춘 걸까? 제대로 작동하고 있는 걸까? 비용은 얼마나 썼을까? 나는 전혀 알 수 없었습니다. 내가 가진 것이라고는 print() 문들이 가득한 화면뿐이었습니다.

그 순간 깨달음이 찾아왔습니다. 내 스택의 다른 모든 부분에는 관측성 (Observability)이 있었습니다. 나의 API, 데이터베이스, 큐에는 모두 대시보드, 트레이스 (Traces), 알림 (Alerts)이 있었습니다. 하지만 내 시스템에서 가장 새롭고 자율적인 부분인 **AI 에이전트 (AI agents)**는 완전한 블랙박스였습니다.

그래서 파트너와 함께 이를 해결하기로 했습니다. 네, 저는 AI 페어 프로그래머 (AI pair-programmer)와 함께 이것을 만들었으며, 이는 해커톤에서도 기쁘게 허용하는 사항입니다. AI 에이전트에게 그들 스스로가 원할 법한 도구를 주는 것이 당연하게 느껴졌습니다.

우리는 이것을 AgentWatch라고 불렀습니다.

AgentWatch는 자율형 AI 에이전트를 위한 드롭인 (drop-in) 관측성 레이어입니다. 약 3줄의 코드만 추가하면, 에이전트가 수행하는 모든 단계, 모든 토큰, 모든 비용을 SigNoz에서 실시간으로 확인할 수 있습니다.

전체 아이디어는 포스트잇 한 장에 담길 만큼 명확합니다: AI 에이전트를 관측할 수 없다면, 당신은 그것을 소유하고 있는 것이 아니다.

핵심 아이디어: 에이전트 실행은 곧 하나의 트레이스이다

이 프로젝트가 구축된 근간이 되는 통찰은 다음과 같습니다. 자율형 에이전트를 자세히 들여다보면, 단일 실행은 정확히 **분산 트레이스 (distributed trace)**와 같습니다:

• 최상위 실행은 **루트 스팬 (root span)**입니다.
• 모든 LLM 호출은 **자식 스팬 (child span)**입니다.
• 모든 도구 (tool) 호출은 **자식 스팬 (child span)**입니다.
• 토큰과 비용은 단지 **스팬 속성 (span attributes)**일 뿐입니다.

OpenTelemetry는 이미 트레이스를 수행하는 방법을 알고 있습니다. 그리고 커뮤니티는 최근 모델 이름, 입력 토큰, 출력 토큰, 비용을 기록하는 표준 방식인 **GenAI 시맨틱 컨벤션 (GenAI semantic conventions)**에 합의했습니다. SigNoz는 이러한 컨벤션을 기본적으로 읽어들입니다.

따라서 우리의 작업은 간단했습니다. 그것들을 손쉽게 방출(emit)할 수 있도록 만드는 것이었습니다. 그것이 바로 @observe 데코레이터 (decorator)입니다.

from agentwatch import observe, tool_span

@observe(agent="e2e-test-fixer")     # 이것이 기본적으로 요구되는 전부입니다
...

그게 전부입니다. Glue code (접착 코드)도, SigNoz 전용 배관 작업도 필요 없습니다. 에이전트를 감싸기만 하면, 모든 실행이 깔끔한 Trace (추적)로 변환됩니다.

증명을 위해, 지켜볼 가치가 있는 에이전트를 만들었습니다

라이브러리는 데모만큼만 설득력이 있습니다. 그래서 우리는 작지만 실제적인 자율 에이전트인 **E2E test-fixer (E2E 테스트 수정기)**를 구축했습니다. 이 에이전트는 Playwright를 사용하여 임시 쇼핑 앱을 대상으로 Chromium을 구동합니다. 테스트 스위트는 잘못된 Selector (선택자), 누락된 Wait (대기), 잘못된 Assertion (단언)이라는 세 가지 실제 버그로 시작합니다. 에이전트는 다음과 같이 동작합니다:

1. 테스트를 실행하고 실패를 확인합니다.
2. Groq를 통한 Llama-3.3-70B라는 실제 LLM에게 근본 원인을 묻습니다.
3. Spec (명세)을 패치합니다.
4. 모든 것이 Green (통과) 상태가 될 때까지 재실행합니다.

여기서 에이전트가 정확히 그 작업을 수행하는 모습입니다:

두 번의 시도 모두 Green (통과)입니다. 실제 브라우저, 실제 테스트 실행, 실제 LLM 호출을 사용했으며, 이 과정 중 조작된 것은 전혀 없습니다.

1단계: 모든 것을 보기 - Trace (추적)

에이전트가 실행되는 순간, 그 전체 이야기가 SigNoz에 하나의 Trace (추적)로 나타납니다. 실행, 실패, 세 번의 LLM 진단 호출, 세 번의 패치 단계, 재실행, 통과에 이르는 전체 Reasoning chain (추론 체인)을 볼 수 있습니다. 그리고 어떤 LLM Span (스팬)을 클릭하든, 실제 GenAI 속성들을 확인할 수 있습니다:

• model: llama-3.3-70b-versatile
• input tokens: 191, output tokens: 49
• cost: $0.000338
• finish reason: stop

처음으로 내 에이전트가 무엇을 생각하고 있는지, 그리고 각 생각이 얼마의 비용이 드는지 실제로 볼 수 있었습니다. 그 블랙박스가 마침내 열린 것입니다.

2단계: 무료로 제공되는 메트릭 (Metrics)

AgentWatch는 표준 OpenTelemetry를 사용하기 때문에, SigNoz는 추가 작업 없이 동일한 트레이스 (Traces)로부터 완전한 **APM (Application Performance Monitoring)**을 자동으로 도출합니다.

지연 시간 백분위수 (Latency percentiles), Apdex, 에러율 (Error rate), 그리고 에이전트가 사용한 모든 모델에 대한 행을 포함한 작업별 상세 내역을 확인할 수 있습니다. 이를 위해 우리는 추가적인 계측 (Instrumentation) 코드를 전혀 작성하지 않았습니다.

3단계: 모든 것을 위한 하나의 대시보드

AgentWatch는 클릭 한 번으로 가져올 수 있는 완성된 SigNoz 대시보드도 함께 제공합니다.

• 총 실행 횟수 (Total runs): 178
• 수정 성공률 (Fix success rate): 94.4%
• 총 LLM 비용 (Total LLM cost): $3.15
• 모델별 토큰 사용량, 시간에 따른 비용, 도구 활동 등을 한눈에 파악할 수 있습니다.

핵심 아이디어: 에이전트가 스스로를 관찰하고, 스스로를 멈춥니다

이 부분이 제가 가장 자랑스럽게 생각하는 지점입니다. 대부분의 관측성 (Observability)은 일방통행입니다. 에이전트가 데이터를 방출하면, 사람이 나중에 대시보드를 확인하는 방식이죠. 우리는 다른 질문을 던졌습니다.

에이전트가 자신의 텔레메트리 (Telemetry)를 실시간으로 읽고, 이를 바탕으로 의사결정을 내릴 수 있다면 어떨까?

그래서 우리는 루프를 닫았습니다 (Closed the loop). AgentWatch는 런타임 (Runtime) 중에 SigNoz로부터 에이전트 자신의 비용을 다시 쿼리하여 제어 신호, 즉 **비용 차단기 (Cost circuit breaker)**로 사용할 수 있습니다. 각 사이클이 시작되기 전, 에이전트는 SigNoz에 지금까지 얼마를 썼는지 묻고, 만약 예산을 초과했다면 스스로 작동을 멈춥니다.

cycle 1: ran fix_suite -> fixed=True in 2 attempts
   SigNoz read-back: spent=$0.0090 | success=100%
COST CIRCUIT BREAKER - SigNoz reports $0.0090 >= budget.
...

이제 SigNoz는 단순한 _관찰자 (observer)_가 아닙니다. 바로 _안전 장치 (safety mechanism)_입니다. 루프가 완성되었습니다. 새벽 2시에 돈을 조용히 태워버리는 악몽은 더 이상 일어날 수 없습니다. 에이전트가 자신의 지갑을 직접 감시하기 때문입니다.

프로덕션 준비 완료: 실제로 작동하는 알림 (alerts)

관찰하는 것도 좋지만, 호출(paged)을 받는 것은 더 좋습니다. AgentWatch는 비용 급증 및 실패 시 작동하는 알림 패키지 (alert pack)를 제공하며, 실제로 SigNoz에서 실시간으로 작동하는 것을 확인했습니다.

이것이 왜 중요한가

지금 모두가 AI 에이전트를 구축하고 있습니다. 하지만 프로덕션 환경에서 해당 에이전트들이 무엇을 하고 있는지 볼 수 있는 사람은 거의 없습니다. AgentWatch는 이 문제를 해결하는 작고 재사용 가능한 레이어이며, 에이전트 시대를 위한 SRE 코파일럿 (SRE copilot) 레이어입니다.

• 개방형 표준, 종속성 없음 (no lock-in) - 순수한 OpenTelemetry GenAI 컨벤션 (conventions)을 따릅니다.
• 즉시 적용 가능 (Drop-in) - 약 3줄의 코드로 OpenAI, Anthropic, Groq 또는 모든 OpenAI 호환 제공업체와 함께 작동합니다.
• 재사용 가능 - 일회성 스크립트가 아닌, 실제로 pip로 설치 가능한 라이브러리입니다.
• 심층적인 SigNoz 통합 - 트레이스 (traces), 메트릭 (metrics), 로그 (logs), 배포 가능한 대시보드, 작동하는 알림, 그리고 실시간 리드백 (live read-back)을 지원합니다.

저희는 또한 혹독하게 테스트했습니다. 이 라이브러리는 테스트 스위트 (test suite)를 통과했으며, 여기에는 대부분의 초보적인 버전들이 실수하는 까다로운 케이스, 즉 각 동시 실행 (concurrent run)의 토큰과 비용을 정확하게 격리하여 유지하는 기능도 포함되어 있습니다.

우리가 배운 점

• 비용은 사후 고려 사항이 아니라, 일급 신호 (first-class signal)입니다. 모든 LLM 스팬 (span)에 달러 가치를 부여하는 순간, 우리는 에이전트를 완전히 다르게 생각하기 시작했습니다.
• 표준은 빠르게 보상을 가져다줍니다. GenAI 컨벤션을 방출 (emitted)했기 때문에, SigNoz는 우리의 데이터를 즉시 이해할 수 있었습니다.
• 관측 가능성 (Observability)은 제어 평면 (control plane)이 될 수 있습니다. 에이전트를 관리하기 위해 텔레메트리 (telemetry)를 다시 읽어들이는 과정은, 이 프로젝트를 단순한 래퍼 (wrapper)에서 우리가 진심으로 열광하는 무언가로 변화시켰습니다.

시도해 보세요

• 에이전트에 계측 (Instrument) 하기: AgentWatch를 설치하고, @observe를 추가한 뒤, SigNoz를 가리키도록 설정하세요.
• 키 없이 데모를 실행하거나, 실제 LLM 호출을 위해 무료 Groq 키를 입력하세요.
• 코드 및 설정: https://github.com/avinashjindal7866/agentwatch

전체 데모

에이전트, 트레이스 (trace), 메트릭 (metrics), 대시보드 (dashboard), 자율 제어 루프 (self-governing loop), 그리고 알림 (alert)까지 - 시작부터 끝까지의 모든 과정은 다음과 같습니다:

AI 에이전트를 관찰할 수 없다면, 당신은 그것을 소유하고 있는 것이 아닙니다. 이제 마침내, 우리는 관찰할 수 있게 되었습니다.

SigNoz 해커톤의 에이전트들을 위해 제작되었습니다.