Failproof AI Observability 평가자 에이전트 스킬

​

가장 어려운 부분은 무엇을 평가할지 결정하는 것입니다

​

다른 평가 구성 요소와의 관계

​

CLI 스킬 대비: 생성 vs 읽기

• agenteye-evaluator (이 문서)는 점수를 생성하는 것을 구축합니다. 처음으로 점수가 생성되면 역할이 끝납니다.
• agenteye-cli 는 이미 존재하는 점수를 읽습니다(agenteye evals). “이번 주 품질이 떨어졌나요?” 는 이 스킬이 답하는 질문이고, 이 문서의 스킬이 답하는 질문이 아닙니다.

​

사전 요구 사항

1. agenteye CLI가 설치되고 로그인된 상태 (pipx install agenteye, 이후 agenteye login). 스킬은 두 가지 용도로 CLI를 사용합니다: 설계 기반이 되는 실제 세션 가져오기, 그리고 마지막에 점수가 제대로 생성됐는지 확인하기. 로그인 계정에는 events:read 권한이 필요하고, 최종 확인을 위해 evaluations:read 권한도 필요합니다. CLI 스킬과 마찬가지로, 이메일로 전송되는 일회용 코드 로그인은 자동으로 완료할 수 없습니다.
2. 평가자가 실행될 공간. 평가자는 이미지로 빌드되어 장기 실행 서비스로 운영되므로, 임시 파일이 아닌 실제 저장소가 필요합니다. 평가자는 평가 대상 에이전트와 별도의 저장소에 운영되는 경우가 많습니다 — 스킬은 기존 저장소를 찾아보고, 새로 생성하기 전에 확인을 요청합니다.
3. agenteye-evaluator SDK 휠 — 에이전트가 pip 명령을 입력하기 전에 다음 섹션을 먼저 읽으세요.

​

입수 방법

​

스킬 설치

# Claude Code, 이 프로젝트에만 적용
npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code

# 모든 프로젝트 (~/.claude/skills/에 설치)
npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code -g --copy

# Codex 사용 시
npx skills add FailproofAI/skills --skill agenteye-evaluator -a codex

npx skills list -a claude-code           # 설치된 스킬 목록
npx skills update agenteye-evaluator     # 최신 버전으로 업데이트
npx skills remove agenteye-evaluator     # 제거

• Claude Code: agenteye-evaluator/ 폴더를 ~/.claude/skills/(모든 프로젝트) 또는 <your-repo>/.claude/skills/(해당 저장소 전용)에 배치하세요. Claude Code가 자동으로 인식합니다 — /skills 목록으로 확인하거나, 평가를 요청해 보세요.
• Codex (OpenAI): Codex도 동일한 SKILL.md를 읽습니다. 번들된 agents/openai.yaml에는 allow_implicit_invocation: true가 설정되어 있어, 작업 내용이 일치하면 Codex가 자동으로 스킬을 선택합니다. 명시적으로 호출하려면 $agenteye-evaluator를 사용하세요.

​

SDK는 공개 PyPI에 없습니다

경고: 에이전트가 SDK를 설치하기 전에 반드시 읽으세요.

​

사용 가능한 요청 예시

you   ▸ I want evals for our support bot. I think it's sometimes bad.

agent ▸ Before I write anything: describe a run that went well,
        and one that went badly.

you   ▸ Good: it answers from the docs. Bad: it makes stuff up,
        or gives up and says "contact support".

agent ▸ Running: agenteye --json sessions --status error --since 7d
        Reading 5 sessions, including two you'd call bad.

        Your words say factuality and deflection. The transcripts
        agree on deflection (2 of 5 end with a support hand-off,
        and it's plain in model_response.content), but factuality
        needs a ground truth your events don't carry.

        So I'd score three things:
          - deflection      rules, cheap, separates your two runs
          - tool_efficiency rules, catches the retry loop in run-004
          - groundedness    LLM judge: is every claim in the docs it retrieved?

        "factuality" would need ground truth we don't have; groundedness
        is the closest thing your transcripts can actually support.
        OK with those three names? Renaming later splits the history.

you   ▸ yes

agent ▸ No evaluator in this repo. Should I scaffold one here, or do
        you have one elsewhere?

​

주의 사항

• 지표 이름은 사실상 영구적입니다. 점수 키는 임의 문자열이고 플랫폼은 전송되는 모든 것의 추세를 추적하므로, 잘못된 선택을 사후에 교정할 방법이 없습니다. 나중에 이름을 바꾸면 히스토리가 분리됩니다: 이전 세션에는 이전 키가 유지되어 추세가 끊깁니다. 이것이 스킬이 코드를 작성하기 전에 명시적인 승인을 받는 이유입니다 — 그 프롬프트를 진지하게 받아들이세요.
• 픽스처는 실제 프로덕션 트랜스크립트입니다. 실제 세션을 기반으로 설계한다는 것은 세션을 디스크로 가져온다는 의미이며, 고객 데이터가 포함될 수 있습니다. 스킬은 git에 커밋하기 전에 확인을 요청합니다. 확신이 없다면 fixtures/를 저장소 밖에 두고 각 개발자가 직접 가져오도록 하세요.
• 에이전트가 모든 트랜스크립트를 읽는 서비스를 작성하고 배포합니다. CLI 로그인 권한 범위 내에서 여러분처럼 행동하지만, 프로덕션 데이터에 접근하는 다른 모든 코드와 동일하게 평가자를 검토하세요.

​

다음 단계

• Evaluation suite: 스킬이 구성하는 HTTP 계약, SDK, 서버 환경 변수.
• Evaluations: 점수가 생성된 후 표시되는 위치.
• CLI skill: 스코어러를 구축하는 대신 결과를 읽기 위한 형제 스킬.
• CLI: 스킬이 설계 기반으로 삼는 세션 데이터의 명령어 참조.