Orchid — 에이전트 디버깅·재현·비용추적을 위한 로컬 프록시(orchid-trace)

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

TL;DR

Orchid는 에이전트와 외부 API 사이에 가벼운 로컬 프록시를 두어 모든 요청·응답·토큰 정보를 SQLite에 기록하고 이를 웹 UI로 시각화하거나 MCP 엔드포인트로 노출해 에이전트와 함께 실행을 병행해서 읽을 수 있게 만든 오픈소스 도구이다. 코드 계측이나 원격 텔레메트리 전송 없이 네트워크 수준에서 트레이스를 확보하므로 데이터 유출 우려를 최소화한 상태로 디버깅·분석이 가능하다.

프록시가 기록한 트레이스는 playback 모드로 재생해 외부 API 호출을 대체할 수 있으므로 CI/CD 파이프라인에서 결정론적 회귀 테스트를 실행하고 API 사용 비용을 제거할 수 있다. 또한 모델별 토큰 단가를 업로드하면 턴·세션별 비용을 집계해 비용 거버넌스 정책과 예산 초과 차단을 프록시 수준에서 적용할 수 있다.

이 방식은 애플리케이션 코드 변경 부담을 없애고 재현성과 비용 가시성을 동시에 제공하는 대신, 네트워크 프록시를 배치하고 기록 파일 관리를 운영에 포함해야 한다는 운영적 고려사항이 존재한다. 프로젝트 소스는 GitHub에 공개되어 있어 바로 시험해 볼 수 있다: https://github.com/mario-guerra/orchid-trace

주요 논점

01찬성소수

프록시 기반 로컬 기록은 코드 계측·클라우드 의존 없이 실행 가시성과 재현 테스트를 제공하므로 멀티에이전트 디버깅에 실질적 도움이 된다는 주장이다.

02찬성소수

플레이백 모드로 API 호출을 대체하면 CI 환경에서 API 비용을 제거하고 테스트 결정론성을 확보할 수 있다는 주장이다.

실용적 조언

서비스 코드에 손대지 않고 에이전트 실행을 기록하려면 로컬 intercepting proxy를 경유하도록 네트워크 구성을 바꿔 트래픽을 캡처하라.
CI/CD 파이프라인에서 외부 모델 호출 비용을 없애려면 기록된 트레이스를 playback 모드로 재생해 결정론적 회귀 테스트를 실행하라.
운영 중 비용 가시성이 필요하면 모델별 토큰 단가를 프록시에 업로드해 턴·세션별 비용 집계를 활성화하고 초과 시 차단 규칙을 마련하라.

섹션별 상세

멀티에이전트 앱에서 문제가 발생하면 UI에서 증상이 보이지 않고 로그를 grep해야 하는 운영상 어려움이 있었다는 문제 상황에서 출발했다. 제안된 해결책은 애플리케이션 코드에 계측을 추가하지 않고 네트워크 계층에서 트래픽을 가로채는 intercepting proxy를 배치하는 것이다. 프록시는 각 요청과 응답 그리고 토큰 수를 로컬 SQLite DB에 기록하고 원본 API로 투명하게 포워딩해 실행 정보를 확보한다. 이 방식은 코드 변경 없이 전체 실행 흐름을 재현·검사할 수 있게 해 디버깅 부담을 줄인다.

프록시가 작동하는 핵심 경로는 클라이언트(에이전트)→프록시(가로채기·기록)→외부 API(포워딩)이며, 기록은 SQLite에 저장되고 별도의 웹 UI에서 트레이스 단위로 시각화된다. 또한 프록시가 제공하는 MCP 엔드포인트를 통해 코딩 에이전트가 실행 기록을 읽어 실행과 병행해 디버깅할 수 있어 사람-에이전트 협업 디버깅이 가능하다. 게시글은 이 흐름이 'AI가 다른 AI의 실행을 읽어 함께 디버깅'하는 실무적 이점으로 이어진다고 밝힌다. 로컬 저장·MCP 연동으로 원본 데이터가 외부로 전송되지 않는다는 점이 핵심 주장이다.

Orchid는 저장된 트레이스를 재생(playback)해 실제 API를 호출하지 않고도 애플리케이션을 결정론적으로 테스트할 수 있도록 설계됐다. 작동 방식은 프록시가 기록된 응답을 그대로 반환해 테스트 하니스가 동일한 응답 시퀀스를 받게 하는 것으로, CI/CD 파이프라인에서 API 비용이 발생하지 않는 환경을 만든다. 게시글은 이로 인해 기록을 테스트 자산으로 저장하고 무비용 회귀 테스트를 돌릴 수 있다고 언급했다. 비용 절감 및 재현성 확보가 실무적 이익으로 제시된다.

비용 관리 기능은 모델별 토큰 단가를 업로드하면 프록시가 턴별·세션별 비용을 계산해 집계하는 방식이다. 이 데이터를 바탕으로 비용 거버넌스 정책을 만들고, 향후에는 예산 초과 시 프록시가 잘못 동작하는 에이전트를 차단하는 게 목표라고 밝혀졌다. 즉, 네트워크 수준에서 비용·행동 제어를 결합해 런어웨이 에이전트를 제어하는 운영적 안전장치를 마련하려는 의도가 드러난다. 이 접근은 에이전트 오케스트레이션에서 예산 관리를 자동화하는 옵션을 제공한다.

용어 해설

인터셉팅 프록시(Intercepting Proxy): — 애플리케이션과 외부 LLM/API 사이에 위치해 모든 요청·응답을 가로채 로컬에 기록하고 원본 요청을 그대로 전달하는 구성이다. 네트워크 수준에서 트래픽을 캡처하므로 애플리케이션 코드 변경 없이 입력·출력·토큰 수를 수집할 수 있다. 디버깅·재현 테스트·비용 추적에 유용하다.
MCP: — 게시글 문맥에서는 프록시가 제공하는 일종의 가벼운 서버 인터페이스로, 기록된 실행(trace)을 외부 도구(예: 코딩 에이전트)가 읽을 수 있게 노출한다. 작동 방식은 프록시가 각 실행을 DB에 저장하고 MCP 엔드포인트로 접근 가능하게 해 에이전트가 실행 내역을 조회·병행 실행하도록 허용하는 것이다. 다중 에이전트 워크플로 디버깅에 활용된다.
플레이백 모드(Playback Mode): — 프록시가 저장해 둔 요청·응답을 실제 API 호출 대신 재생(return)해 애플리케이션이 동일한 응답 시퀀스를 받도록 하는 모드이다. CI/CD 환경에서 외부 API 호출 없이 결정론적 테스트를 가능하게 하며 API 사용 비용을 제거한다. 테스트 하니스와 결합해 회귀·통합 테스팅에 적합하다.
비용 추적(Cost Tracking): — 모델별 토큰 단가를 업로드하면 프록시가 각 턴의 토큰 수에 단가를 곱해 호출별·세션별 비용을 집계하는 기능이다. 호출 수준 비용 가시성으로 예산 초과 탐지·회계 처리·비용 거버넌스 정책 적용 근거를 제공한다. 런어웨이 에이전트 차단 정책과 결합해 비용 통제에 활용된다.
SQLite: — 경량 임베디드 관계형 데이터베이스로, 별도 서버 없이 단일 파일에 실행 로그와 트레이스를 저장한다. 프록시는 SQLite에 모든 요청·응답·토큰 메타데이터를 기록해 로컬 보관·검색·플레이백을 가능하게 한다. 간단한 배포와 오프라인 디버깅에 장점이 있다.

언급된 도구

Orchid (orchid-trace)추천링크

에이전트와 API 사이에 끼워 요청·응답·토큰을 로컬에 기록하고 웹 UI·플레이백·MCP 엔드포인트·비용 집계를 제공하는 로컬 프록시 도구

언급된 리소스

GitHubOrchid - orchid-trace (GitHub)