AgentEye란?
AgentEye는 AI 에이전트를 위한 자체 호스팅 방식의 관측성 및 평가 플랫폼입니다. 에이전트가 수행하는 모든 작업을 실행 단계별로 기록하고, 완료된 각 실행의 품질을 자동으로 채점합니다. 이를 통해 프로덕션 환경에서 에이전트의 동작을 파악하고, 사용자가 문제를 경험하기 전에 회귀를 미리 감지할 수 있습니다. 데이터는 단방향으로 흐릅니다. 에이전트 코드가 Python SDK를 통해 이벤트를 발생시키면 → 경량 컬렉터 데몬이 이를 배치로 묶어 서버로 전송하고 → 이벤트와 분석 데이터는 ClickHouse에 저장됩니다(조직, 사용자, API 키, 대시보드, 저장된 쿼리 등 운영 상태는 Postgres에 저장) → 대시보드에서 모든 데이터를 탐색할 수 있습니다. 제공 기능:- 이벤트 — 모든 에이전트 실행의 단계별 원시 기록(도구 호출, 모델 호출, 훅, 오류).
- 세션 — 실행당 하나의 행으로 집계된 이벤트. 각 세션은 자동으로 평가되고 채점됩니다.
- 평가 — 직접 구성한 평가자 서비스가 생성한 품질 점수로, 수동 검토 없이도 품질 저하를 감지합니다.
- 쿼리 & 대시보드 — 데이터에 대한 저장된 ClickHouse SQL을 공유 가능한 조직 범위의 대시보드로 시각화합니다.
- 알림 & 인시던트 — 임계값 규칙을 기반으로 알림(이메일, Slack, 웹훅, 대시보드 내)을 발송하고, 트리아지를 위한 인시던트 워크플로우를 제공합니다.
- CLI & AI 어시스턴트 — 터미널 클라이언트(
agenteye)와 대시보드 내 어시스턴트를 통해 자연어로 질문할 수 있습니다.
1단계: 인증
모든 AgentEye 아티팩트는agenteye-enterprise GitHub 조직에서 배포됩니다. 엔터프라이즈 개발자는 GitHub PAT를 직접 생성할 수 있습니다. 정확한 단계와 필요한 권한은 enterprise-docs/github-token.md를 참고하세요.
2단계: 서버 및 대시보드 배포
서버는 컬렉터로부터 이벤트를 수신하고 이를 쿼리 가능하게 만들며, 대시보드는 데이터를 탐색하는 공간입니다. 수집된 이벤트와 분석 데이터는 ClickHouse(필수 분석 저장소)에 저장되고, Postgres는 조직, 사용자, API 키, 대시보드, 저장된 쿼리 등 운영 상태를 보관합니다. 공개된 Compose 파일 다운로드:admin 자격증명으로 배포되지 않도록 .env 파일을 생성합니다. 최소한 ADMIN_KEY와 POSTGRES_PASSWORD를 설정해야 합니다:
http://localhost:8080에서, 대시보드는 http://localhost:3000에서 수신 대기 중입니다.
프로덕션 배포(커스텀 Postgres, TLS, 리버스 프록시)는 enterprise-docs/deployment.md를 참고하세요.
3단계: 컬렉터용 API 키 생성
각 컬렉터는 범위가 지정된 API 키로 인증합니다. 2단계에서 설정한ADMIN_KEY를 사용해 키를 생성합니다:
key 값은 직접 지정합니다. 이 값은 4단계의 컬렉터 설정에 사용됩니다. 전체 키 관리 방법은 enterprise-docs/api-keys.md를 참고하세요.
4단계: 컬렉터 설치
AI 에이전트가 실행되는 모든 머신에 컬렉터 데몬을 설치합니다. 바이너리 다운로드 (Linux x86_64):이 명령은 Linux x86_64 빌드를 다운로드합니다. macOS(Apple Silicon 또는 Intel), Linux arm64, Docker/systemd/launchd 설정은 collector-installation.md를 참고하세요. 각 플랫폼별 다운로드 방법이 나와 있습니다. 위 명령은 Linux 바이너리를 설치하므로 다른 환경에서는 실행되지 않습니다.설정:
5단계: Python SDK 설치
에이전트 코드를 계측할 각 머신에 GitHub Releases에서 wheel 파일을 설치합니다.6단계: 에이전트 계측
에이전트 코드에 이벤트를 추가합니다. 최소한agent_start와 agent_end를 발생시켜야 합니다:
$AGENTEYE_HOME/events/(또는 AGENTEYE_HOME이 설정되지 않은 경우 ~/.agenteye/events/)로 플러시됩니다. 컬렉터가 자동으로 이를 수집합니다.
전체 이벤트 API는 enterprise-docs/python-sdk.md를 참고하세요.
7단계: 대시보드에서 이벤트 확인
http://your-dashboard-host:3000을 열고 로그인합니다. AgentEye는 일회용 코드(또는 원클릭 매직 링크)를 이메일로 발송하므로 비밀번호를 관리할 필요가 없습니다.

session_id 또는 agent_id로 필터링하여 특정 실행을 상세 조회할 수 있습니다.



8단계: 탐색, 시각화, 알림
이벤트가 흐르기 시작하면 분석 페이지에서 원시 활동 데이터를 인사이트로 변환할 수 있습니다. 에이전트 동작을 측정하고, 팀과 결과를 공유하며, 문제가 발생하는 즉시 알림을 받을 수 있습니다. 대시보드 페이지는 조직 범위로 적용되므로 주소 표시줄의 URL은 조직 슬러그(/<org>/…)로 시작합니다.
- 쿼리 (
/<org>/queries): 이벤트와 평가 데이터에 대한 저장된 재사용 가능한 쿼리 라이브러리(기본 프리셋 및 커스텀 쿼리)에서 시작하세요…


- 대시보드 (
/<org>/dashboards): 쿼리를 라인, 바, 에어리어, 파이 타일로 고정하여 조직 전체가 공유하는 대시보드를 구성합니다.

- 알림 (
/<org>/alerts): 임계값을 이메일, Slack, 웹훅, 대시보드 내 알림으로 통보하는 규칙으로 전환합니다. enterprise-docs/alerts.md를 참고하세요.

