Agent Super Spy: 로컬 LLM 관측성(Observability) 통합 스택

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

핵심 요약

로컬 LLM 에이전트 개발 시 에이전트가 생성하는 정확한 LLM 호출과 네트워크 트래픽을 파악하는 것은 매우 어렵다. Agent Super Spy는 Opik, Phoenix, mitmproxy를 하나의 LLM 프록시 주변에 결합하여 모든 API 호출에 대한 완전한 가시성을 제공하는 올인원 스택이다. 사용자는 에이전트나 SDK의 베이스 URL을 이 프록시로 설정하기만 하면, 실시간 트래픽 검사부터 상세한 트레이스 시각화까지 한 번에 수행할 수 있다. 이를 통해 개발자는 복잡한 에이전트의 동작을 투명하게 모니터링하고 디버깅 효율을 극대화할 수 있다.

배경

Docker 및 Docker Compose 설치, 기본적인 LLM API(OpenAI, Anthropic 등) 사용 경험, 환경 변수 및 네트워크 프록시 설정에 대한 이해

대상 독자

로컬 환경에서 LLM 에이전트를 개발하고 디버깅하는 엔지니어

의미 / 영향

이 스택은 블랙박스에 가까웠던 LLM 에이전트의 내부 통신 과정을 투명하게 공개한다. 특히 여러 도구를 개별적으로 설정할 필요 없이 Docker 기반으로 즉시 구축할 수 있어, 개발 초기 단계에서 관측성 확보에 드는 비용을 획기적으로 줄여준다.

섹션별 상세

Agent Super Spy는 llm-proxy, mitmproxy, Phoenix, Opik을 결합하여 로컬 개발 환경에서 LLM 호출을 모니터링하는 통합 환경을 구축한다. llm-proxy는 경로 기반 라우팅을 통해 Anthropic, OpenAI 등 다양한 프로바이더의 요청을 처리하며, OpenTelemetry(OTEL)를 통해 트레이스 데이터를 내보낸다.

mitmproxy를 활용하여 암호화된 HTTPS 트래픽을 포함한 모든 원시 네트워크 패킷을 웹 UI에서 직접 검사할 수 있다. 이를 통해 HTTP 헤더, 요청 페이로드, 응답 데이터를 상세히 확인할 수 있으며, 로컬 개발 시 에이전트가 외부와 어떻게 통신하는지 투명하게 파악 가능하다.

bash

# Route all traffic through mitmproxy for inspection
export HTTP_PROXY=http://localhost:8080
export HTTPS_PROXY=http://localhost:8080

# Or route only LLM calls through the llm-proxy
export ANTHROPIC_BASE_URL=http://localhost:4000/anthropic
export OPENAI_BASE_URL=http://localhost:4000/openai

에이전트의 트래픽을 프록시로 라우팅하기 위한 환경 변수 설정

프록시 레벨에서 API 키 관리 기능을 제공하여 보안과 편의성을 동시에 확보한다. keys.jsonc 파일을 통해 로컬용 가상 키와 실제 프로바이더 키를 매핑하면, SDK에는 가상 키를 사용하고 프록시가 업스트림 API로 전달할 때 실제 키로 교체하는 방식이다.

json

{
  "my-local-key": {
    "anthropic": "sk-ant-real-key...",
    "openai": "sk-real-key...",
    "api.openrouter.com": "sk-or-real-key..."
  }
}

keys.jsonc 파일을 이용한 로컬 키와 실제 API 키 매핑 설정 예시

Docker Compose를 기반으로 설계되어 기존 프로젝트와의 연결이 용이하다. 공유 네트워크(llm-proxy-net)를 통해 다른 컨테이너에서 실행 중인 에이전트도 쉽게 프록시에 접근할 수 있으며, setup.sh와 start.sh 스크립트로 복잡한 설정 없이 즉시 스택을 실행할 수 있다.

yaml

networks:
  llm-proxy-net:
    name: llm-proxy-net
    external: true

services:
  my-agent:
    networks:
      - default
      - llm-proxy-net
    environment:
      ANTHROPIC_BASE_URL: http://llm-proxy:4000/anthropic

기존 Docker 프로젝트를 LLM 관측성 네트워크에 연결하는 설정

실무 Takeaway

로컬 에이전트 개발 시 ANTHROPIC_BASE_URL 등을 로컬 프록시로 설정하여 모든 LLM 호출을 가로채고 분석할 수 있다.
mitmproxy의 CA 인증서를 설치하면 HTTPS로 암호화된 에이전트의 통신 내용까지 상세히 디버깅할 수 있다.
keys.jsonc를 활용해 실제 API 키를 코드나 환경 변수에 직접 노출하지 않고 프록시 단에서 안전하게 관리할 수 있다.

언급된 리소스

GitHubOpik GitHub

문서Phoenix Documentation

문서mitmproxy Documentation