메인 콘텐츠로 건너뛰기
이 가이드는 AgentEye의 전체 설정 과정을 안내합니다. 서버와 대시보드 배포, 에이전트 머신에 컬렉터 설치, Python 에이전트 코드 계측까지 단계별로 살펴봅니다.

AgentEye란?

AgentEye는 AI 에이전트를 위한 자체 호스팅 방식의 관측성 및 평가 플랫폼입니다. 에이전트가 수행하는 모든 작업을 실행 단계별로 기록하고, 완료된 각 실행의 품질을 자동으로 채점합니다. 이를 통해 프로덕션 환경에서 에이전트의 동작을 파악하고, 사용자가 문제를 경험하기 전에 회귀를 미리 감지할 수 있습니다. 데이터는 단방향으로 흐릅니다. 에이전트 코드가 Python SDK를 통해 이벤트를 발생시키면 → 경량 컬렉터 데몬이 이를 배치로 묶어 서버로 전송하고 → 이벤트와 분석 데이터는 ClickHouse에 저장됩니다(조직, 사용자, API 키, 대시보드, 저장된 쿼리 등 운영 상태는 Postgres에 저장) → 대시보드에서 모든 데이터를 탐색할 수 있습니다. 제공 기능:
  • 이벤트 — 모든 에이전트 실행의 단계별 원시 기록(도구 호출, 모델 호출, 훅, 오류).
  • 세션 — 실행당 하나의 행으로 집계된 이벤트. 각 세션은 자동으로 평가되고 채점됩니다.
  • 평가 — 직접 구성한 평가자 서비스가 생성한 품질 점수로, 수동 검토 없이도 품질 저하를 감지합니다.
  • 쿼리 & 대시보드 — 데이터에 대한 저장된 ClickHouse SQL을 공유 가능한 조직 범위의 대시보드로 시각화합니다.
  • 알림 & 인시던트 — 임계값 규칙을 기반으로 알림(이메일, Slack, 웹훅, 대시보드 내)을 발송하고, 트리아지를 위한 인시던트 워크플로우를 제공합니다.
  • CLI & AI 어시스턴트 — 터미널 클라이언트(agenteye)와 대시보드 내 어시스턴트를 통해 자연어로 질문할 수 있습니다.
이 모든 것을 자체 인프라에서 단일 Docker Compose 스택(이 가이드 기준), 프로덕션 Kubernetes 설치, 또는 단일 코로케이션 파드로 운영할 수 있습니다. 이 가이드에서는 Compose 스택을 처음부터 끝까지 설정합니다.

1단계: 인증

모든 AgentEye 아티팩트는 agenteye-enterprise GitHub 조직에서 배포됩니다. 엔터프라이즈 개발자는 GitHub PAT를 직접 생성할 수 있습니다. 정확한 단계와 필요한 권한은 enterprise-docs/github-token.md를 참고하세요.

2단계: 서버 및 대시보드 배포

서버는 컬렉터로부터 이벤트를 수신하고 이를 쿼리 가능하게 만들며, 대시보드는 데이터를 탐색하는 공간입니다. 수집된 이벤트와 분석 데이터는 ClickHouse(필수 분석 저장소)에 저장되고, Postgres는 조직, 사용자, API 키, 대시보드, 저장된 쿼리 등 운영 상태를 보관합니다. 공개된 Compose 파일 다운로드:
시크릿 설정: 기본 admin 자격증명으로 배포되지 않도록 .env 파일을 생성합니다. 최소한 ADMIN_KEYPOSTGRES_PASSWORD를 설정해야 합니다:
스택 시작:
이 명령은 필수 ClickHouse 분석 저장소와 선택적 Redis 캐시를 포함한 전체 스택을 서버 및 대시보드와 함께 실행합니다. 서버가 시작되려면 ClickHouse가 정상 상태여야 합니다. 이제 서버는 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 바이너리를 설치하므로 다른 환경에서는 실행되지 않습니다.
설정:
데몬 시작:
원샷 플러시로 연결 상태를 확인합니다(대기 중인 이벤트를 모두 전송한 후 종료):
Docker, systemd, launchd 설정은 enterprise-docs/collector-installation.md를 참고하세요.

5단계: Python SDK 설치

에이전트 코드를 계측할 각 머신에 GitHub Releases에서 wheel 파일을 설치합니다.

6단계: 에이전트 계측

에이전트 코드에 이벤트를 추가합니다. 최소한 agent_startagent_end를 발생시켜야 합니다:
이벤트는 버퍼에 쌓이다가 500ms마다 $AGENTEYE_HOME/events/(또는 AGENTEYE_HOME이 설정되지 않은 경우 ~/.agenteye/events/)로 플러시됩니다. 컬렉터가 자동으로 이를 수집합니다. 전체 이벤트 API는 enterprise-docs/python-sdk.md를 참고하세요.

7단계: 대시보드에서 이벤트 확인

http://your-dashboard-host:3000을 열고 로그인합니다. AgentEye는 일회용 코드(또는 원클릭 매직 링크)를 이메일로 발송하므로 비밀번호를 관리할 필요가 없습니다. 단일 사용 코드를 이메일로 발송하는 AgentEye 로그인 화면 로그인 후 이벤트 페이지에서 수집된 모든 이벤트의 실시간 내역을 확인할 수 있습니다. session_id 또는 agent_id로 필터링하여 특정 실행을 상세 조회할 수 있습니다. 이벤트 유형별로 색상이 구분되고 환경, 에이전트, 세션으로 필터링 가능한 실시간 이벤트 스트림 세션 페이지는 해당 이벤트들을 실행당 하나의 행으로 집계합니다. AgentEye는 완료된 세션을 자동으로 평가하므로 모든 실행이 채점되고 수동 검토 없이도 품질 회귀를 감지할 수 있습니다. 최신 평가 점수는 각 행에서 한눈에 확인할 수 있습니다: 상태 배지와 평가 점수 배지가 표시된 실행별 세션 목록 세션 채점 방식 설정은 enterprise-docs/evaluation-suite.md를 참고하세요. 세션을 클릭하면 실행 그래프가 열립니다. 이는 에이전트, 도구, 훅, 모델 호출이 시간에 따라 어떻게 전개되었는지 git 스타일로 보여주는 뷰로, 병렬 서브 에이전트는 각자의 레인에 표시되고 오른쪽 패널에서 실행별 분석을 확인할 수 있습니다: 이벤트 타임라인 옆에 표시된 세션의 git 스타일 실행 그래프와 도구/모델/훅 분석 패널

8단계: 탐색, 시각화, 알림

이벤트가 흐르기 시작하면 분석 페이지에서 원시 활동 데이터를 인사이트로 변환할 수 있습니다. 에이전트 동작을 측정하고, 팀과 결과를 공유하며, 문제가 발생하는 즉시 알림을 받을 수 있습니다. 대시보드 페이지는 조직 범위로 적용되므로 주소 표시줄의 URL은 조직 슬러그(/<org>/…)로 시작합니다.
  • 쿼리 (/<org>/queries): 이벤트와 평가 데이터에 대한 저장된 재사용 가능한 쿼리 라이브러리(기본 프리셋 및 커스텀 쿼리)에서 시작하세요…
재사용 가능한 쿼리 그리드로 구성된 저장된 쿼리 라이브러리(기본 프리셋과 커스텀 쿼리 포함) …그런 다음 SQL 작성기에서 쿼리를 열어 수정하고 실시간 결과와 함께 실행합니다: 스키마 사이드바와 실시간 결과 그리드가 있는 SQL 쿼리 작성기에서 저장된 쿼리 실행 화면
  • 대시보드 (/<org>/dashboards): 쿼리를 라인, 바, 에어리어, 파이 타일로 고정하여 조직 전체가 공유하는 대시보드를 구성합니다.
저장된 쿼리로 구성된 대시보드: 시간당 이벤트 라인 차트, 유형별 오류 바 차트, 지연 시간 에어리어 차트, 모델별 토큰 차트
  • 알림 (/<org>/alerts): 임계값을 이메일, Slack, 웹훅, 대시보드 내 알림으로 통보하는 규칙으로 전환합니다. enterprise-docs/alerts.md를 참고하세요.

다음 단계