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

​

어렵고도 중요한 부분: 무엇을 평가할지 결정하기

​

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

​

CLI 스킬과의 차이: 구축 vs. 읽기

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

​

사전 요구사항

1. agenteye CLI 설치 및 로그인 (pipx install agenteye, 이후 agenteye login). 스킬이 두 번 이를 활용합니다: 설계의 기반이 되는 실제 세션을 가져올 때, 그리고 마지막에 점수가 제대로 나타났는지 확인할 때. 로그인에는 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 로그인 권한 범위 내에서 여러분 대신 행동하지만, 프로덕션 데이터를 다루는 다른 코드처럼 평가자를 검토하세요.

​

다음 단계

• 평가 스위트: 스킬이 구성하는 HTTP 계약, SDK, 서버 환경 변수.
• 평가: 점수가 나타난 후 어디서 확인할 수 있는지.
• CLI 스킬: 스코어러를 구축하는 것이 아닌 결과를 읽기 위한 형제 스킬.
• CLI: 스킬이 기반으로 하는 세션 데이터 뒤의 명령어 레퍼런스.