AI 에이전트를 위한 관측성 계층(Observability Layer) 구축하기: ProteusTracer

우리가 구축하는 것

Proteus 에이전트 프레임워크를 위한 프로덕션급 관측성 계층(Observability Layer)입니다. 모든 LLM 호출, 도구 호출(tool invocation), 토큰 소비량을 캡처하여, 실패 원인을 몇 시간이 아닌 몇 초 만에 디버깅할 수 있도록 합니다.

사전 요구 사항

• Node.js 18+
• Proteus 에이전트 프로젝트 (또는 모든 에이전트 프레임워크)
• TypeScript 5+
• OpenTelemetry 개념에 대한 기본적인 이해

1단계: 핵심 인터페이스 정의하기

관측성(observability)을 구동할 타입(types)부터 시작하세요. 이는 모든 트레이서(tracer)가 충족해야 하는 계약입니다.

// types.ts
export interface Span {
  id: string;
...

이를 통해 빌딩 블록을 확보할 수 있습니다. 모든 LLM 호출은 스팬(span)이 됩니다. 모든 도구 호출(tool invocation)은 자식 스팬(child span)이 됩니다. 모든 토큰 수는 메트릭(metric)이 됩니다.

2단계: ProteusTracer 구축하기

이제 해당 인터페이스들을 에이전트의 실행 흐름을 감싸는 작동 가능한 트레이서(tracer)로 연결합니다.

// proteus-tracer.ts
import { Span, SpanKind, SpanStatus, Metric, TraceContext } from './types';
import { v4 as uuidv4 } from 'uuid';
...

3단계: 에이전트를 위한 브릿지 핸들러(bridge handler) 생성하기

이 단계는 트레이서가 실제 에이전트 실행과 만나는 지점입니다. 브릿지 핸들러는 에이전트의 단계(phases)를 감싸고 모든 호출을 계측(instrument)합니다.

typescript
// bridge-handler.ts
...