ONEDEV

Tracely-ai

AI Agent OrchestrationCLIPython

★ 1,408주당 +36조회 4

무엇인가

Tracely는 AI 에이전트의 프로덕션 트레이스를 회귀 테스트 자산으로 전환하는 CI/CD 계층이다. 관측 대시보드가 끝나는 지점에서 시작해 배포 파이프라인의 차단 지점에 자리한다. 실패한 실행 한 건이 이후 PR을 막는 테스트가 된다.

어떻게 동작하나

트레이스는 OTLP로 수집된다. agent.id, conversation.id, turn, step 같은 에이전트 의미 필드는 인덱스된 1급 컬럼으로 승격되어 스팬 목록이 아니라 대화 스레드 단위로 묶인다. 평가자는 별도 탭이 아니라 트레이스 테이블의 컬럼으로 붙고, 대화·실행·스팬 레벨에서 LLM-as-judge 또는 모델이 필요 없는 구조 검사로 채점한다. 채점 결과는 SSE로 스트리밍되어 그리드에 실시간 반영된다. 실패는 구조적·의미적으로 클러스터링되어 하나의 이슈와 카운트로 합쳐진다. 실패 트레이스를 승격하면 입력·도구 출력·LLM 응답이 fixture로 묶인 hermetic 케이스가 되고, 구 코드에서 실패하고 수정 코드에서 통과해야 신뢰되는 fail-to-pass 계약이 붙는다. 저장은 Postgres(pgvector), ClickHouse, Redis, MinIO가 나눠 맡는다.

무엇과 다른가

기존 eval 도구는 사람이 데이터셋을 작성하는 것을 전제한다. 질문을 만들고 이상적인 답을 쓰고 제품이 바뀔 때마다 갱신해야 하며, 그 데이터셋은 무엇이 깨질지에 대한 추측이다. Tracely는 실패한 실행의 입력·도구 호출·모델 응답을 그대로 테스트로 고정한다. 품질 점수, 실패 클러스터, 제안 수정, CI 판정, 추세, 알림은 모두 트레이스에서 파생된다. CI 재생은 기록된 fixture에 대고 오프라인으로 돌기 때문에 API 키도 모델 비용도 들지 않는다.

어떻게 쓰나

전체 스택은 Docker Compose로 한 번에 뜬다. ClickHouse, Postgres, Redis, MinIO가 함께 기동하고 마이그레이션이 실행되며 기본 프로젝트와 ingest 키(tracely_dev_key)가 시드된다. 트레이스·클러스터·케이스·게이트까지 채워지므로 빈 화면이 아니라 데이터가 있는 상태로 시작한다. 호스트 포트는 웹 3001, 백엔드 8000이 기본이고 TRACELY_WEB_PORT, TRACELY_BACKEND_PORT로 바꾼다. backend/worker/frontend는 소스 볼륨 마운트로 돌아 대부분의 수정은 재시작만으로 반영되지만 Celery 워커는 핫 리로드되지 않는다. Railway로도 같은 스택을 배포할 수 있고 첫 배포에서 마이그레이션과 시딩이 실행되며 SESSION_SECRET 설정이 필요하다.

전제와 한계

Docker와 Docker Compose가 전제다. 로컬 개발에는 uv와 Node 20+, pnpm이 추가로 필요하다. 트레이스는 OTLP로 들어와야 한다. CI 게이트는 tracely gate가 0이 아닌 종료 코드를 반환하고 커밋 상태와 PR 코멘트를 갱신하는 방식으로 동작한다. 알림은 게이트 실패, 라이브 대화의 판정 실패, 처음 보는 실패 모드, 임계치 초과를 트리거로 삼아 캔버스 위 흐름으로 정의된다.

관련 논문 2

유사 도구