평가 Suite

참고: 점수 차원은 직접 정의합니다. 평가자는 원하는 숫자형 키를 반환할 수 있으며, Observability는 전송된 값을 저장, 추세 분석, 표시합니다.

​

개요

1. 점수화 서비스를 작성합니다. 세션 트랜스크립트를 읽고 점수를 반환하는 소규모 HTTP 서비스를 구축합니다. Observability에는 복사하여 사용할 수 있는 참조 구현이 포함되어 있습니다. SDK를 이용한 평가자 작성을 참조하세요.
2. Observability가 해당 서비스를 가리키도록 설정합니다. 서버 프로세스에 EVALUATOR_ENDPOINT(및 공유 EVALUATOR_TOKEN)를 설정합니다.
3. 점수가 기록되는 것을 확인합니다. 완료된 모든 세션은 자동으로 점수화되며, 결과는 세션 상세 페이지, 세션 그리드, 저장된 대시보드에 표시됩니다.

​

작동 방식

• 인라인으로 결과를 반환합니다: {"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}. 결과는 세션의 평가 타임라인에 추가됩니다. reasoning과 summary는 선택 사항입니다.
• 지연합니다: {"status":"pending", "job_id":"abc-123"}. 그러면 Observability는 평가자가 {"status":"done", ...} 또는 {"status":"error", "error":"..."}를 반환할 때까지 GET {EVALUATOR_ENDPOINT}/evaluate/abc-123을 호출합니다. 폴링 주기는 작업별로 설정됩니다: pending 응답에 next_poll_secs를 포함하여 재정의할 수 있으며, 그렇지 않으면 Observability는 GET /config의 default_poll_interval_secs 값을 사용하고, 그것도 없으면 서버는 EVALUATOR_POLLING_INTERVAL_SECS(기본값 10초)로 대체합니다. 모든 값은 [1초, 1시간] 범위로 제한됩니다.

​

HTTP 계약

• Observability 서버: 환경 변수 EVALUATOR_TOKEN
• 평가자 서비스: 동일한 방식으로 구성 (agenteye-evaluator SDK는 관례에 따라 EVALUATOR_TOKEN을 읽음)

​

평가자가 제공해야 하는 라우트

​

서버가 전송하는 EvalRequest 바디

{
  "schema_version": "1",
  "session_id":     "session-abc123",
  "agent_id":       "planner",
  "environment":    "production",
  "started_at":     "2026-05-10T12:00:00Z",
  "ended_at":       "2026-05-10T12:05:00Z",
  "events": [
    { "id": 1234, "ts": "...", "event_type": "agent_start", "payload": { ... } },
    ...
  ]
}

​

응답 형태

{
  "status": "done",
  "scores": { "helpfulness": 0.85, "tool_efficiency": 0.6 },
  "reasoning": {
    "helpfulness": "answered the question directly with citations",
    "tool_efficiency": "called list_files three times when one would have done"
  },
  "summary": "strong answer quality, weak tool selection"
}

{ "status": "pending", "job_id": "abc-123", "next_poll_secs": 30 }

{ "status": "error", "error": "model service unavailable" }

​

SDK를 이용한 평가자 작성

import os
from agenteye_evaluator import Evaluator, EvalRequest, EvalResponse

app = Evaluator(token=os.environ["EVALUATOR_TOKEN"])

@app.evaluator
def run(req: EvalRequest) -> EvalResponse:
    # Inspect req.events (the full session transcript) and return scores.
    tool_calls = sum(1 for e in req.events if e.event_type == "tool_use")
    return EvalResponse(
        scores={"tool_calls": float(tool_calls)},
        reasoning={"tool_calls": f"{tool_calls} tool invocations in the transcript"},
        summary="tight tool loop" if tool_calls < 5 else "agent looped on tools",
    )

​

평가자 실행

​

서버 구성

​

API 참조

​

점수 범위로 필터링: score_filters

# helpfulness in [0.5, 0.8]
GET /evaluations?score_filters=helpfulness:0.5..0.8

# tool_efficiency at most 0.3 (no lower bound)
GET /evaluations?score_filters=tool_efficiency:..0.3

# helpfulness >= 0.5 AND factuality >= 0.9
GET /evaluations?score_filters=helpfulness:0.5..,factuality:0.9..

​

권한

​

결과 보기

• /sessions/<id>: 이벤트 타임라인 + 세션의 점수와 디스패치 시도 오류를 보여주는 오른쪽 패널. 키에 evaluations:trigger 권한이 있으면 내보내기 버튼 옆에 재평가 버튼이 나타나며, agent_end를 전송하지 않은 세션이나 새 평가자를 배포한 후 점수를 새로 고칠 때 유용합니다. 대시보드는 새 결과를 폴링하고 결과가 도착하면 오른쪽 패널을 업데이트합니다.
• /sessions: 필터링 가능한 세션 그리드; 점수 열에는 각 세션의 평가 상태와 점수가 한눈에 표시됩니다.
• /dashboards: 저장된 평가 상태 뷰(아래 대시보드 참조).

​

대시보드

• 필터: 세션 페이지와 동일한 컨트롤: 환경, 상태, 에이전트, 롤링 시간 창, 점수 범위 필터(key:min..max).
• 표시 구성: 특성화할 점수 키, 녹색/주황색/빨간색 상태 임계값, 표시할 패널, 세션별 최신 평가로 축소할지 여부.

​

문제 해결

​

다음 단계

• 평가자 에이전트 스킬: 코딩 에이전트가 실제 세션을 바탕으로 차원을 설계하고 이 서비스를 구축하도록 합니다.
• Python SDK: 점수화를 트리거하는 agent_end 이벤트를 전송합니다.
• API 키: evaluations:read 및 evaluations:trigger 권한.
• 감사: 정책 기반 검토를 위한 Observability의 또 다른 자동화된 품질 기능.