대부분의 AI 에이전트 데모는 최종 답변 단계에서 멈춥니다.

제 것도 처음에는 그랬습니다. 환불 질문에 답하고, 정책 도구(policy tool)를 호출하며, 프롬프트 인젝션(prompt-injection) 경로를 피할 수 있는 고객 지원 에이전트를 만들었습니다. 겉으로 보기에는 괜찮아 보였습니다.

그러다 저는 조금 더 불편한 질문을 던졌습니다. 만약 이 에이전트가 프로덕션 환경에서 고장 난다면, 실제로 무슨 일이 일어났는지 알 수 있을까?

그 질문이 TraceGate가 되었습니다.

TraceGate는 OpenTelemetry와 SigNoz로 구축된 AI 에이전트를 위한 릴리스 게이트(release gate)입니다. 에이전트 시나리오를 실행하고, 텔레메트리(telemetry)를 SigNoz로 전송한 다음, 실행 결과가 안전하게 배포할 수 있을 만큼 충분한 증거를 생성했는지 확인합니다.

문제점

AI 에이전트는 디버깅하기 어려운 상태에서도 데모를 통과할 수 있습니다.

도구가 세 번 재시도(retry)하고도 여전히 성공적인 답변을 반환할 수 있습니다. LLM 호출이 비용 메타데이터(cost metadata) 없이 발생할 수 있습니다. 프롬프트 인젝션 테스트는 통과할 수 있지만, 어떤 안전 경로가 사용되었는지에 대한 흔적을 남기지 않을 수 있습니다. 이것들은 일반적인 의미의 제품 실패는 아닙니다. 그것들은 관측 가능성(observability)의 실패입니다.

그것이 바로 제가 TraceGate를 통해 잡아내고 싶었던 것입니다.

아이디어는 간단합니다. 에이전트가 배포되기 전에 관측 가능성 계약(observability contract)을 충족해야 합니다. 계약이 실패하면 릴리스는 차단됩니다.

TraceGate가 확인하는 것

TraceGate는 YAML 계약을 사용하여 안전한 릴리스 실행에 포함되어야 할 내용을 설명합니다.

제가 사용한 계약의 일부는 다음과 같습니다:

name: TraceGate AI Agent Release Contract
serviceName: tracegate-demo-agent

...

기본 데모는 의도적으로 하나의 체크를 실패하도록 설정되어 있습니다. trace.lookup 도구는 세 번 재시도하지만, 계약은 단 한 번의 재시도만 허용합니다.

이 점이 데모를 유용하게 만듭니다. TraceGate가 모든 것이 건강한 척하지 않기 때문입니다. TraceGate는 릴리스를 차단하고 그 이유를 설명합니다.

TraceGate FAIL
Checks: 7/8 passed
Critical failures: 1
...

아키텍처 (The architecture)

스택은 다음과 같습니다:

Vite
React
TypeScript
...

흐름은 다음과 같습니다:

시나리오 (Scenario) -> 에이전트 러너 (Agent runner) -> OpenTelemetry -> SigNoz -> TraceGate 계약 평가기 (contract evaluator) -> 통과 (Pass) 또는 차단 (block)

Node 러너가 시나리오를 실행합니다. OpenTelemetry는 스팬 (spans), 메트릭 (metrics), 로그 (logs)를 기록합니다. SigNoz는 OTLP를 통해 텔레메트리 (telemetry)를 수신합니다. TraceGate는 실행 결과를 읽고 이를 계약 (contract)에 따라 평가합니다.

OpenTelemetry 설정을 위해, 저는 OTLP HTTP 익스포터 (exporters)를 사용했습니다:

const endpoint =
  process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? "http://localhost:4318";

...

제 로컬 설정에서, SigNoz는 다음과 같은 스팬 (spans)을 수신했습니다:

agent.run
llm.call
tool.ticket.lookup
...

제가 겪었던 빌드 문제

가장 많은 디버깅이 필요했던 부분은 로컬 SigNoz 설정이었습니다.

저는 SigNoz를 로컬에서 실행하기 위해 Foundry를 사용했습니다. 처음 모든 것을 시작했을 때, UI는 정상적으로 작동했지만 텔레메트리 (telemetry) 경로가 유용하지 않았습니다. 컬렉터 (collector)는 살아있는 것처럼 보였지만, 파이프라인 (pipeline)이 제가 기대했던 데이터를 실제로 전송하지 않고 있었습니다.

문제는 OpAMP 및 MCP 서비스 배선 (wiring) 주변의 생성된 로컬 설정에 있었습니다. 저는 생성된 설정을 패치하여 인제스터 (ingester)가 실제 SigNoz 서비스를 가리키고, MCP 서버가 SigNoz UI 서비스를 가리키도록 했습니다. 그 이후에 OTLP 익스포트 (export)가 작동했고 ClickHouse에서 스팬 (spans)을 확인할 수 있었습니다.

그 부분이 저에게는 이 프로젝트에서 가장 "실제적인" 부분이었습니다. 게이트 (gate)를 위한 코드는 텔레메트리 (telemetry)가 실제로 백엔드에 도달한다는 것을 증명하는 것에 비하면 매우 간단했습니다.

워크벤치 (The workbench)

TraceGate에는 랜딩 페이지와 워크벤치 (workbench)가 있습니다.

랜딩 페이지는 핵심 아이디어를 설명합니다: 트레이스 (traces)가 동의할 때만 에이전트를 배포하십시오.

워크벤치 (workbench)는 다음을 보여줍니다:

최신 릴리스 판결 (latest release verdict)
통과된 체크 항목 (checks passed)
심각한 실패 (critical failures)
...

게이트 매트릭스 (gate matrix)는 제가 가장 중요하게 생각하는 부분입니다. 이는 모호한 릴리스 신뢰도를 구체적인 체크 항목으로 변환합니다.

예를 들어:

루트 에이전트 실행 스팬 (Root agent run span): 통과 (pass)
추적된 LLM 호출 (LLM calls traced): 통과 (pass)
모델 속성 존재 여부 (Model attribute present): 통과 (pass)
...

이는 리뷰어에게 "내 로컬 환경에서는 데모가 잘 작동했다"라는 말보다 훨씬 더 나은 시작점을 제공합니다.

판사 테스트 모드 (Judge test mode)

호스팅된 앱이 정적인 목업 (mockup)처럼 느껴지는 것을 원하지 않았기에, 판사가 운영하는 테스트 모드도 추가했습니다.

판사는 다음과 같은 정보를 입력할 수 있습니다:

서비스 이름 (service name)
시나리오 (scenario)
도구 이름 (tool name)
...

그러면 TraceGate가 새로운 판결을 생성합니다.

예를 들어:

서비스 (service): checkout-agent
도구 (tool): inventory.lookup
허용된 재시도 횟수 (allowed retries): 1
...

이것이 릴리스를 차단합니다.

만약 관찰된 재시도 횟수가 0으로 변경되면, 릴리스 준비가 완료됩니다.

이를 통해 누군가에게 제 로컬 환경 전체를 먼저 설정해달라고 요청하지 않고도 제품을 더 쉽게 테스트할 수 있습니다.

배운 점

가장 크게 배운 점은 관측성 (observability)이 의사 결정과 연결될 때 더 유용하다는 것입니다.

이 프로젝트를 하기 전에는 주로 관측성을 버그가 발생한 후에 확인하는 용도로 취급했습니다. AI 에이전트의 경우, 그것은 너무 늦은 시점입니다. 만약 에이전트가 위험한 경로를 택하거나, 메타데이터를 누락하거나, 비용을 숨기거나, 불안정한 도구를 여러 번 재시도한다면, 저는 릴리스 검증 (release validation) 단계에서 이를 알고 싶습니다.

두 번째로 배운 점은 "에이전트가 작동했다"라는 말은 너무 광범위하다는 것입니다. 이제 저는 이를 두 가지 질문으로 나눕니다:

에이전트가 예상된 결과를 생성했는가?
에이전트가 해당 결과를 디버깅할 수 있는 충분한 증거를 생성했는가?

TraceGate는 두 번째 질문에 집중합니다.

다음에 만들 것

다음 버전에는 시각적 계약 에디터 (visual contract editor)가 포함되어야 합니다. 해커톤(hackathon)에서는 YAML을 작성하는 것도 괜찮지만, 팀은 UI에서 필요한 스팬 (spans), 속성 (attributes), 예산 (budgets), 그리고 시나리오 (scenarios)를 선택함으로써 릴리스 게이트 (release gate)를 생성할 수 있어야 합니다.

또한 GitHub Actions 지원도 추가하고 싶습니다. TraceGate가 위치하기에 가장 자연스러운 곳은 CI이며, 그곳에서 머지 (merge) 전 에이전트 릴리스를 차단할 수 있습니다.

마지막 개선 사항은 더 깊은 SigNoz 아티팩트 (artifacts)를 구현하는 것입니다. 각 계약 (contract)은 그에 매칭되는 대시보드 (dashboard), 알림 (alert), 그리고 조사 프롬프트 (investigation prompt)를 생성해야 하며, 이를 통해 릴리스 게이트와 디버깅 워크플로우 (debugging workflow)가 연결된 상태를 유지할 수 있습니다.

마치며

TraceGate는 한 가지 불편한 질문에서 시작되었습니다: 만약 내 AI 에이전트가 나중에 실패한다면, 그 원인을 이해할 수 있는 증거를 내가 가지고 있을 것인가?

SigNoz는 이미 팀들에게 텔레메트리 (telemetry)를 검사할 수 있는 강력한 환경을 제공합니다. TraceGate는 그 텔레메트리 위에 릴리스 워크플로우 (release workflow)를 추가합니다.

프로젝트는 규모가 작지만, 그 아이디어는 유용하다고 느껴집니다. 에이전트는 단순히 최종 답변이 좋아 보인다는 이유만으로 출시되어서는 안 됩니다. 에이전트는 그 동작이 신뢰할 수 있을 만큼 추적 가능 (traceable)할 때 출시되어야 합니다.