jwuthri-cloud/Tracely-ai

Trace-native CI/CD for AI agents: grade production traces, cluster failures, freeze them into replayable regression tests, and block PRs that regress. Self-hostable.

Tracely – AI 에이전트 관측성 및 회귀 테스트

정의 – Tracely는 프로덕션에서 AI 에이전트(LLM 기반 봇, 도구 사용 어시스턴트, 멀티 에이전트 시스템)의 실행을 모니터링하는 자체 호스팅 플랫폼으로, 발견한 모든 실패를 결정적 회귀 테스트로 전환하고 동일한 버그를 다시 유발하는 풀 리퀘스트를 차단합니다. OpenTelemetry 스타일 트레이스를 수집하고, 내장 평가자로 평가하며, 유사한 실패를 클러스터링하고, CI에서 정확히 기록된 입력/출력을 재생하여 이를 수행합니다.

주요 구성 요소

수집 서비스 – 모든 언어에서 OTLP/HTTP 트레이스를 수신하고, 원시 스팬을 ClickHouse/Postgres에 저장하며 에이전트별 필드(에이전트 ID, 대화 ID, 턴, 단계)를 인덱싱합니다.
평가자/심판 – 경량 검사(모델 없음) 및 LLM 기반 심판으로 실행, 턴 또는 스팬을 점수화합니다. 판정은 트레이스 테이블에 컬럼으로 다시 기록됩니다.
실패 클러스터링 – 구조적 시그니처와 의미적 임베딩으로 실패한 실행을 그룹화하여, 개수와 제안된 평가자를 포함한 단일 이슈를 생성합니다.
회귀 케이스 – 실패한 트레이스를 한 번의 클릭으로 격리된 테스트 케이스로 승격: 모든 입력, 도구 호출 및 LLM 출력이 픽스처로 저장되고, "실패-통과" 계약이 첨부되며, 선택적 어서션이 정의됩니다.
CI 게이트 – CLI(tracely gate/tracely simulate/tracely replay)가 GitHub Actions에서 스위트를 실행하고, 실패 시 0이 아닌 종료 코드를 반환하며, 커밋 상태와 PR 댓글을 게시합니다.
알림 흐름 – "when-then" 규칙(예: 게이트 실패, 새 실패 유형 발생, 비율 임계값 초과)을 위한 비주얼 빌더. 작업은 Slack, 이메일, 웹훅, LLM 단계 또는 Python 표현식이 될 수 있습니다.
대시보드 및 뷰 – 트레이스 타임라인, 계층적 워터폴, "Fleet" 픽셀 아트 오피스 뷰, 시간 경과 트렌드, 심판 보정 화면, 자연어로 평가자, 시나리오, 케이스 및 알림을 생성할 수 있는 앱 내 어시스턴트.

사용 방법

계측 – tracelyai-sdk(또는 모든 OTLP 익스포터)로 에이전트를 계측합니다. SDK는 OpenAI/Anthropic/Google/Mistral 호출, 도구 사용, 토큰 사용, 지연 시간 등을 자동 캡처합니다.
실행 – 프로덕션에서 서비스를 실행; Tracely는 각 대화를 트레이스로 저장합니다.
탐지 – 평가자가 실행을 실시간으로 평가하고, 실패는 자동으로 클러스터링됩니다.
승격 – 한 번의 클릭으로 실패를 회귀 케이스로 승격합니다.
배포 – PR 워크플로에 Tracely GitHub Action을 추가; 게이트가 케이스 픽스처를 오프라인으로 재생(API 키 없음, $0 비용)하고 버그가 재발하면 PR을 차단합니다.
모니터링 – 대시보드에서 실패 수, 게이트 통과율, 지연/비용 트렌드를 보여주고, 인간 검토에 대해 심판을 보정할 수 있습니다.

설치 및 배포

제공된 버튼으로 Railway 또는 Railyard에 원클릭 배포.
전체 Docker-Compose 스택(backend, worker, frontend, ClickHouse, Postgres, Redis, MinIO) – docker compose --profile demo up은 사전 채워진 트레이스, 클러스터, 케이스 및 게이트로 데모를 실행합니다.
사용자 지정 인프라의 경우 deploy/railway 및 deploy/eks 가이드를 참조하세요; 스택은 단일 Kubernetes 네임스페이스에서 실행됩니다.

일반적인 워크플로 스니펫

import tracely_sdk as tracely
tracely.init(
    endpoint="http://localhost:8000",
    api_key="tracely_dev_key",
    service_name="support-agent",
    env="prod",
    instrument="auto",
)

with tracely.trace(agent="support-agent", conversation="conv-1"):
    client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Where is order ORD-4471?"}],
    )

SDK는 모든 메타데이터와 함께 GENERATION 스팬을 기록합니다. 그런 다음 Tracely가 이를 평가하고, 실패를 클러스터링하며, 회귀 케이스로 전환할 수 있습니다.

중요성 전통적인 LLM 평가는 프로덕션 입력과 정확히 일치하지 않는 수작업 테스트 세트에 의존합니다. Tracely는 이 모델을 뒤집습니다: 실제 실패 실행이 테스트가 되어 완벽한 충실도를 보장하고, CI에서 모델 호출 비용이 0이며, 회귀를 자동으로 차단합니다. 이는 AI 에이전트를 위한 관측성과 지속적 통합을 연결합니다.

링크

웹사이트: https://tracely-ai.com
문서: https://doc.tracely-ai.com
PyPI SDK: tracelyai-sdk
GitHub Actions: .github/actions/tracely-gate

jwuthri-cloud/Tracely-ai

Tracely – AI 에이전트 관측성 및 회귀 테스트

관련