failproofai 1.0.1-beta.1 → 1.0.1

package/.next/standalone/docs-old/ko/agenteye/evaluation-suite.mdx

@@ -0,0 +1,303 @@
+---
+title: "평가 Suite"
+description: "Failproof AI Observability는 완료된 모든 에이전트 실행을 자동으로 품질 점수화할 수 있습니다: 소규모 점수화 서비스를 제공하면 Observability가 나머지를 처리합니다."
+---
+
+
+Failproof AI Observability는 완료된 모든 에이전트 실행을 자동으로 품질 점수화할 수 있습니다: 소규모 점수화 서비스를 제공하면 Observability가 나머지를 처리합니다. 이를 통해 관심 있는 차원(유용성, 도구 효율성, 사실성, 안전성 등 원하는 항목을 선택)을 추적하고, 회귀를 조기에 감지하며, 에이전트나 환경을 한눈에 비교할 수 있습니다. 점수화는 선택 사항입니다: 서버에 `EVALUATOR_ENDPOINT`를 설정하기 전까지는 파이프라인이 아무것도 수행하지 않습니다.
+
+> **참고:** 점수 차원은 직접 정의합니다. 평가자는 원하는 숫자형 키를 반환할 수 있으며, Observability는 전송된 값을 저장, 추세 분석, 표시합니다.
+
+## 개요
+
+1. **점수화 서비스를 작성합니다.** 세션 트랜스크립트를 읽고 점수를 반환하는 소규모 HTTP 서비스를 구축합니다. Observability에는 복사하여 사용할 수 있는 참조 구현이 포함되어 있습니다. [SDK를 이용한 평가자 작성](#writing-an-evaluator-with-the-sdk)을 참조하세요.
+2. **Observability가 해당 서비스를 가리키도록 설정합니다.** 서버 프로세스에 `EVALUATOR_ENDPOINT`(및 공유 `EVALUATOR_TOKEN`)를 설정합니다.
+3. **점수가 기록되는 것을 확인합니다.** 완료된 모든 세션은 자동으로 점수화되며, 결과는 세션 상세 페이지, 세션 그리드, 저장된 대시보드에 표시됩니다.
+
+![평가 요약, 차원별 점수 바, 오른쪽 패널의 추론 텍스트가 포함된 세션 상세 보기](/agenteye/images/session-detail.png)
+
+*평가자를 구성하면 완료된 각 실행이 점수화되고 결과가 세션의 오른쪽 패널에 표시됩니다: 상단의 요약, 그 아래 추론이 포함된 차원별 점수 바.*
+
+---
+
+## 작동 방식
+
+```mermaid
+flowchart LR
+    ING["ingest /events<br/>agent_end"] --> SRV["Observability server"]
+    SRV -->|"POST /evaluate"| EV["Evaluator service"]
+    EV -->|"done or pending"| SRV
+    SRV -->|"poll GET /evaluate/{job_id}"| EV
+    EV -->|"done"| SRV
+    SRV --> RES["evaluations<br/>terminal results"]
+```
+
+Observability SDK가 세션에 대한 `agent_end` 이벤트를 전송하면, 서버는
+평가를 예약합니다. 그런 다음 전체 이벤트 트랜스크립트를 평가자 서비스에 POST하며,
+평가자 서비스는 다음 중 하나를 수행할 수 있습니다:
+
+- **인라인으로 결과를 반환합니다**: `{"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시간] 범위로 제한됩니다.
+
+`agent_end`를 전송하지 않는 세션(예: 충돌한 에이전트 프로세스)도 처리할 수 있습니다: 평가자의 `GET /config`는 `{"inactivity_timeout_secs": 1800}`을 반환할 수 있으며, Observability는 해당 시간 동안 유휴 상태인 세션을 평가합니다. 이 폴백을 비활성화하려면 해당 필드를 `null`로 설정하거나 생략하세요.
+
+`EVALUATOR_ENDPOINT`가 설정되지 않은 경우 파이프라인은 완전히 아무런 동작도 하지 않습니다.
+
+세션은 **시간이 지남에 따라 여러 개의 최종 평가를 누적**할 수 있습니다: 각 `agent_end` 이벤트(및 대시보드에서의 수동 재평가)는 새로운 평가 행을 추가합니다. 이는 재개된 대화를 평가하는 공식 방법입니다: 사용자가 에이전트를 종료하고 나중에 돌아와 더 많은 이벤트를 전송하고 에이전트를 다시 종료하면, 두 번째 평가가 전체 업데이트된 트랜스크립트에 대해 실행됩니다. 대시보드는 가장 최근 평가를 헤드라인으로 렌더링하고 이전 평가는 접을 수 있는 타임라인으로 표시합니다. 세션에 대한 평가가 실행 중인 동안, 해당 세션의 추가 `agent_end` 이벤트는 무시됩니다; 실행 중인 평가가 완료된 후 다음 이벤트가 평소와 같이 새로운 평가를 큐에 추가합니다.
+
+비활성 폴백은 재개된 세션에도 다시 적용됩니다: 이전 최종 평가 이후 새 이벤트가 도착하고 세션이 `inactivity_timeout_secs`를 초과하여 유휴 상태가 되면 새로운 평가가 큐에 추가됩니다.
+
+일시적인 오류(5xx, 429, 타임아웃, 네트워크 오류)는 `EVALUATOR_MAX_ATTEMPTS`까지 지수 백오프로 재시도됩니다; 4xx 응답은 최종 오류로 처리됩니다. Observability는 여러 수평 확장된 서버 인스턴스와 함께 안전하게 실행됩니다; 작업이 분산되어 동일한 세션이 동시에 두 번 처리되지 않습니다.
+
+---
+
+## HTTP 계약
+
+모든 인증된 라우트는 **베어러 토큰 인증**을 사용합니다. 양쪽에 동일한 값이 구성되어야 합니다:
+
+- Observability 서버: 환경 변수 `EVALUATOR_TOKEN`
+- 평가자 서비스: 동일한 방식으로 구성 (`agenteye-evaluator` SDK는 관례에 따라 `EVALUATOR_TOKEN`을 읽음)
+
+`EVALUATOR_TOKEN`이 설정되지 않은 경우 서버는 `Authorization` 헤더를 전송하지 않습니다; 평가자는 익명 요청을 수락할 수 있으며, 내부 전용 네트워크에서는 괜찮지만 공개 인터넷에서는 권장하지 않습니다.
+
+### 평가자가 제공해야 하는 라우트
+
+| 라우트 | 바디 / 파라미터 | 응답 |
+|---|---|---|
+| `GET /health` | 없음 | `{"status":"ok"}` (공개, 인증 없음) |
+| `GET /config` | 없음 | `{"inactivity_timeout_secs": <int> \| null, "default_poll_interval_secs": <int> \| omitted}` |
+| `POST /evaluate` | `EvalRequest` JSON | `{"status":"done", ...}` 또는 `{"status":"pending", "job_id":"..."}` |
+| `GET /evaluate/{id}` | 없음 | `/evaluate`와 동일한 응답 형태 |
+
+### 서버가 전송하는 `EvalRequest` 바디
+
+```json
+{
+  "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": { ... } },
+    ...
+  ]
+}
+```
+
+### 응답 형태
+
+**동기 (완료):**
+
+```json
+{
+  "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"
+}
+```
+
+`reasoning`(점수별 근거 맵)과 `summary`(전체 단락 서술)는 모두 선택 사항입니다. `reasoning`의 키는 `scores`의 키와 일치해야 합니다; 대시보드는 각 항목을 해당 점수 바 아래에 인라인으로 렌더링합니다. `scores`만 반환하는 이전 평가자는 변경 없이 계속 작동합니다; `reasoning`과 `summary`는 단순히 null로 읽히고 해당 UI 요소는 생략됩니다.
+
+**비동기 (지연):**
+
+```json
+{ "status": "pending", "job_id": "abc-123", "next_poll_secs": 30 }
+```
+
+`next_poll_secs`는 선택 사항입니다; 생략하면 서버는 `/config`의 평가자 `default_poll_interval_secs`로 대체하고, 그다음에는 자체 `EVALUATOR_POLLING_INTERVAL_SECS` 환경 변수로 대체합니다.
+
+**평가자 측 최종 오류:**
+
+```json
+{ "status": "error", "error": "model service unavailable" }
+```
+
+서버는 다른 2xx 바디를 프로토콜 오류로 처리하고 세션에 대한 최종 `error`를 기록합니다.
+
+---
+
+## SDK를 이용한 평가자 작성
+
+HTTP 계약을 직접 구현할 필요가 없습니다. `agenteye-evaluator`
+Python 패키지는 인증, 라우팅, 요청/응답 형태를 자동으로 처리하는 타입이 지정된 FastAPI 래퍼를 제공합니다.
+
+Failproof AI Observability는 트랜스크립트 형태에서 `helpfulness`, `tool_efficiency`, `factuality`를 점수화하는 **작동하는 참조 평가자**도 함께 제공합니다. 이를 시작점으로 복사하고 LLM 판단자, 규칙 엔진 등 품질 기준에 맞는 자체 로직으로 교체하세요.
+
+최소 실행 가능한 평가자:
+
+```python
+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",
+    )
+```
+
+`app` 인스턴스는 모든 ASGI 서버에서 실행되므로 `uvicorn module:app`으로 시작할 수 있습니다.
+
+비용이 많이 드는 작업을 지연해야 하는 평가자의 경우 대신 `JobPending`을 반환하고 `@app.job_lookup` 핸들러를 등록하세요; Observability 서버는 평가자가 최종 상태를 반환하거나 `EVALUATOR_MAX_POLL_DURATION_SECS` 제한(기본값 1시간)이 경과할 때까지 `GET /evaluate/{job_id}`를 폴링합니다.
+
+전체 API 참조, 비동기 패턴, 이벤트 스키마는 `agenteye-evaluator` SDK의 README에 문서화되어 있습니다.
+
+---
+
+## 평가자 실행
+
+평가자는 **사용자의 서비스**입니다 — Failproof AI Observability는 기본 평가자를 제공하지 않으므로, 자체 서비스를 실행하는 곳에서 구축하고 실행해야 합니다. 모든 ASGI 서버에서 실행됩니다(예: `uvicorn my_evaluator:app`); [HTTP 계약](#http-contract)의 `/health`, `/config`, `/evaluate` 라우트를 제공한 다음 서버가 해당 서비스를 가리키도록 설정합니다([서버 구성](#configuring-the-server) 참조).
+
+평가자에 접근할 수 있으면 `GET /health`는 `{"status":"ok"}`를 반환합니다. 에이전트가 엔드-투-엔드 실행을 완료한 후, 서버의 `GET /evaluations`는 `status: "done"` 및 평가자가 생성한 점수가 포함된 행을 반환합니다.
+
+---
+
+## 서버 구성
+
+서버 프로세스에 설정:
+
+| 환경 변수 | 의미 |
+|---|---|
+| `EVALUATOR_ENDPOINT` | 평가자의 기본 URL (`http://evaluator:9000`). 미설정 = 파이프라인 비활성화. |
+| `EVALUATOR_TOKEN` | 베어러 토큰. 평가자 서비스에 구성된 값과 동일해야 합니다. |
+| `EVALUATOR_WORKERS` | 서버 인스턴스당 워커 태스크 수 (기본값 2). |
+| `EVALUATOR_CLAIM_BATCH` | 워커 틱당 처리되는 행 수 (기본값 4). 배치는 **동시에** 처리됩니다; 평가자 엔드포인트의 실질적인 동시성은 `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`입니다. |
+| `EVALUATOR_POLL_IDLE_SECS` | 평가가 예정되지 않았을 때 디스패치 시도 사이에 워커가 대기하는 시간 (기본값 2초). |
+| `EVALUATOR_POLLING_INTERVAL_SECS` | 응답별 `next_poll_secs`도, 평가자의 `default_poll_interval_secs`도 설정되지 않은 경우 `GET /evaluate/{id}` 주기의 최종 대체값 (기본값 10초). |
+| `EVALUATOR_REQUEST_TIMEOUT_MS` | 요청별 타임아웃 (기본값 30000). |
+| `EVALUATOR_MAX_ATTEMPTS` | 이 횟수만큼 일시적 오류가 발생하면 결과가 최종 `error`로 기록됩니다 (기본값 5). |
+| `EVALUATOR_CONFIG_REFRESH_SECS` | `GET /config` 주기 (기본값 300). |
+| `EVALUATOR_MAX_POLL_DURATION_SECS` | 세션이 `timeout`으로 종료되기 전까지 폴링 큐에 머무를 수 있는 최대 실제 경과 시간 (기본값 3600초). 계속 `pending`을 반환하는 평가자를 방지합니다. |
+
+자동 점수화를 활성화하려면 서버에 `EVALUATOR_ENDPOINT`와 `EVALUATOR_TOKEN`을 모두 설정하고 서버를 재시작하여 변경 사항을 적용하세요. `EVALUATOR_ENDPOINT`가 설정되지 않으면 파이프라인은 아무런 동작도 하지 않습니다.
+
+위의 조정 항목은 선택 사항입니다; 기본값을 재정의해야 하는 경우에만 서버에 해당 환경 변수를 설정하세요.
+
+---
+
+## API 참조
+
+| 메서드 | 경로 | 필요한 권한 | 목적 |
+|---|---|---|---|
+| `GET` | `/evaluations` | `evaluations:read` | 최종 결과 조회. `session_id`, `agent_id`, `environment`, `status` (`done`/`error`/`timeout`), `ts_from`, `ts_to`, `cursor`, `limit`, `score_filters`, `latest_per_session`을 지원합니다. `limit` 기본값은 50이며 최대 200으로 제한됩니다(최대 1000으로 제한되는 `/events`와 다름). `environment`는 쉼표로 구분된 목록을 허용합니다(예: `environment=prod,staging`); 단일 값도 여전히 작동합니다. `latest_per_session=true`를 사용하면 응답에 `session_id`당 최대 한 행(`completed_at` 기준 가장 최근)이 포함되며, 세션 목록 페이지에서 세션의 평가 타임라인을 현재 헤드라인으로 축소하는 데 사용됩니다. 기본값은 false(전체 기록 반환)입니다. |
+| `GET` | `/evaluations/aggregate` | `evaluations:read` | 필터링된 슬라이스에 대한 집계된 평가 상태: 총 개수, 완료/오류/타임아웃 분류, 점수 키별 통계(임의 `scores` 키에 대한 개수/평균/최솟값/최댓값/p50), 시간 버킷별 타임라인. `/evaluations`와 **동일한 필터 파라미터**에 `featured_keys`(추세를 볼 점수 키의 CSV)와 `latest_per_session`이 추가됩니다. 대시보드 기능을 지원합니다; 메트릭은 샘플링 없이 전체 일치 집합에 대해 정확합니다. |
+| `GET` | `/evaluations/environments` | `evaluations:read` | `evaluations` 테이블의 고유한 환경 값. 평가 읽기 가능 데이터로 범위가 지정된 필터 드롭다운을 채우는 데 사용됩니다. |
+| `GET` | `/evaluation-jobs` | `evaluations:read` | 진행 중인 평가에 대한 가시성. `status` (`pending`/`polling`)로 필터링합니다. |
+| `GET` | `/events` | `events:read` | 세션의 원시 이벤트 스트리밍. `session_id`, `agent_id`, `event_type` (CSV), `environment` (CSV), `ts_from`, `ts_to`, `cursor`, `limit`, `order`를 지원합니다. `order`는 `desc`(최신순, 기본값) 또는 `asc`(오래된 순)이며; 인식할 수 없는 값은 `desc`로 대체됩니다. 응답의 `next_cursor`(이벤트 id)를 통해 커서 페이지네이션: 다음 페이지를 가져오려면 `cursor`로 다시 전달하세요; `asc`의 경우 다음 페이지는 해당 id 이후의 이벤트이고, `desc`의 경우 그 이전의 이벤트입니다. `limit` 기본값은 50이며 최대 1000으로 제한됩니다. |
+| `GET` | `/sessions/:session_id/export` | `events:read` | 이 세션에 대해 평가자가 받을 정확한 JSON 바디를 `session-<id>.json`이라는 이름의 다운로드 가능한 첨부 파일로 반환합니다. 오프라인 테스트를 위해 프로덕션 세션을 `agenteye-evaluator`로 재현하는 데 유용합니다. 바이트는 평가자 파이프라인이 전송하는 것과 바이트 단위로 동일합니다. |
+| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | 세션에 대한 새로운 평가를 큐에 추가합니다; 이전 평가 존재 여부와 관계없이 실행됩니다. 새 결과는 이전 결과를 덮어쓰는 것이 아니라 세션의 평가 타임라인에 **추가**되므로, 이전 점수는 기록으로 계속 표시됩니다. 큐에 추가되면 `202`를 반환하고, 알 수 없는 세션이면 `404`, 평가가 이미 진행 중이면 `409`를 반환합니다. 새 평가자를 배포한 후 또는 `agent_end`를 전송하지 않은 세션에 사용합니다. |
+
+### 점수 범위로 필터링: `score_filters`
+
+`GET /evaluations`는 `scores` 객체 내부의 숫자 값으로 결과를 좁히는 선택적 `score_filters` 파라미터를 허용합니다. 이 파라미터는 `key:min..max` 항목의 쉼표로 구분된 목록입니다; 어느 쪽 경계도 생략할 수 있습니다. 여러 항목은 논리 AND로 결합됩니다. 명명된 키가 없거나 숫자가 아닌 행은 제외됩니다. 요청에는 최대 20개의 필터 항목이 포함될 수 있으며, 이를 초과하면 HTTP 400이 반환됩니다.
+
+예시:
+```text
+# 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..
+```
+
+각 `/evaluations` 응답 객체에는 다음 필드가 있습니다:
+
+| 필드 | 타입 | 참고 |
+|---|---|---|
+| `evaluation_id` | string (UUID) | 이 최종 평가의 정규 식별자. 각 최종 평가는 새로운 UUID를 받으며; 단일 세션은 여러 개를 가질 수 있습니다. |
+| `id` | string (UUID) | `evaluation_id`와 동일한 값을 가지는 하위 호환성 별칭. |
+| `session_id` | string | 이 평가가 실행된 세션. 세션은 타임라인에 여러 평가를 가질 수 있습니다. |
+| `agent_id` | string | 세션을 생성한 에이전트를 식별합니다. |
+| `environment` | string | 세션에서 복사된 환경 레이블. |
+| `status` | enum | `"done"`, `"error"`, `"timeout"` 중 하나. |
+| `scores` | object \| null | 평가자가 반환한 점수. |
+| `reasoning` | object \| null | 평가자가 반환한 선택적 점수별 근거 맵. 키는 일반적으로 `scores`의 키와 일치합니다. 대시보드는 각 항목을 점수 바 아래에 렌더링합니다. |
+| `summary` | string \| null | 평가자가 반환한 선택적 전체 단락 서술. 대시보드는 이를 점수별 분류 위에 평가의 헤드라인으로 렌더링합니다. |
+| `error` | string \| null | `"error"` / `"timeout"`일 때만 채워집니다. |
+| `attempt_count` | integer | 디스패치 시도 횟수 (≥ 1). |
+| `duration_ms` | integer \| null | 마지막 시도의 지속 시간. |
+| `completed_at` | string (ISO 8601 UTC) | 최종 결과가 기록된 시간. 결과는 `completed_at` 기준으로 정렬됩니다(최신순). |
+| `created_at` | string (ISO 8601 UTC) | `completed_at`과 동일한 타임스탬프를 가집니다(쓰기 1회 시맨틱). |
+
+---
+
+## 권한
+
+| 권한 | 부여 대상 |
+|---|---|
+| `evaluations:read` | 평가 결과 목록 조회, 대시보드에서 점수 보기, 대시보드 상태 메트릭 로드. |
+| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` 또는 대시보드의 재평가 버튼을 통해 세션에 대한 평가를 수동으로 큐에 추가. |
+| `dashboards:read` | 저장된 대시보드 보기 (메트릭을 로드하려면 `evaluations:read`도 필요). |
+| `dashboards:write` | 대시보드 생성 및 편집. |
+| `dashboards:delete` | 대시보드 삭제. |
+
+부트스트랩 관리자(`ADMIN_KEY`, `ADMIN_EMAIL`)는 이 모든 권한을 자동으로 받습니다.
+
+---
+
+## 결과 보기
+
+- **`/sessions/<id>`**: 이벤트 타임라인 + 세션의 점수와 디스패치 시도 오류를 보여주는 오른쪽 패널. 키에 `evaluations:trigger` 권한이 있으면 내보내기 버튼 옆에 **재평가** 버튼이 나타나며, `agent_end`를 전송하지 않은 세션이나 새 평가자를 배포한 후 점수를 새로 고칠 때 유용합니다. 대시보드는 새 결과를 폴링하고 결과가 도착하면 오른쪽 패널을 업데이트합니다.
+- **`/sessions`**: 필터링 가능한 세션 그리드; 점수 열에는 각 세션의 평가 상태와 점수가 한눈에 표시됩니다.
+- **`/dashboards`**: 저장된 평가 상태 뷰(아래 [대시보드](#dashboards) 참조).
+
+![세션별 평가 상태 필과 색상으로 구분된 점수 배지(helpfulness, factuality, tool_efficiency, safety, coherence)가 있는 세션 그리드](/agenteye/images/sessions-list.png)
+
+*세션 그리드는 각 실행의 평가 상태와 점수를 한눈에 보여줍니다; 빨간색/주황색/녹색 배지로 낮은 점수가 눈에 띄게 표시됩니다.*
+
+---
+
+## 대시보드
+
+**대시보드** 페이지(`/dashboards`)를 통해 평가 필터 조합을 이름이 지정된 재사용 가능한 뷰로 저장하고 해당 평가 슬라이스의 상태를 한눈에 모니터링할 수 있습니다. 대시보드는 **조직 전체에서 공유**됩니다; `dashboards:read` 권한이 있는 모든 사람이 동일한 세트를 볼 수 있습니다.
+
+각 대시보드에는 다음이 고정됩니다:
+
+- **필터**: 세션 페이지와 동일한 컨트롤: 환경, 상태, 에이전트, 롤링 시간 창, 점수 범위 필터(`key:min..max`).
+- **표시 구성**: 특성화할 점수 키, 녹색/주황색/빨간색 상태 임계값, 표시할 패널, 세션별 최신 평가로 축소할지 여부.
+
+각 카드에는 일치하는 세션 수, 완료/오류/타임아웃 분류, 각 특성화된 점수의 평균, 소형 추세 스파크라인이 표시됩니다. 대시보드를 열면 전체 크기 패널이 표시되며; **"세션에서 열기"**를 누르면 정확히 해당 슬라이스로 미리 필터링된 세션 페이지로 이동합니다. 메트릭은 전체 일치 집합에 대해 서버 측에서 계산됩니다(`GET /evaluations/aggregate` 사용), 따라서 숫자는 샘플링이 아닌 정확한 값입니다.
+
+![평가자 차원별 평균 점수 바, 도구 성공/오류 분류, 상위 도구, 시간당 이벤트 추세가 있는 평가 상태 대시보드](/agenteye/images/dashboard-quality.png)
+
+**권한:** 보기에는 `dashboards:read`와 `evaluations:read` 모두 필요합니다; 생성 및 편집에는 `dashboards:write`가 필요합니다; 삭제에는 `dashboards:delete`가 필요합니다. 부트스트랩 관리자는 이 모든 권한을 자동으로 받습니다.
+
+---
+
+## 문제 해결
+
+**세션은 존재하지만 평가가 생성되지 않습니다.** 서버 프로세스에 `EVALUATOR_ENDPOINT`가 설정되어 있는지, 서버와 평가자가 동일한 `EVALUATOR_TOKEN` 값을 공유하는지, 평가자의 `/health` 엔드포인트가 서버에서 접근 가능한지 확인하세요. `EVALUATOR_ENDPOINT`가 설정되지 않으면 파이프라인은 아무런 동작도 하지 않습니다.
+
+**진행 중인 평가가 쌓입니다.** `GET /evaluation-jobs`를 조회하여 진행 중인 큐를 확인하세요. 각 행의 `attempt_count`, `next_attempt_at`, `last_error`를 검사하세요. 일반적인 원인: 평가자 서비스에 접근할 수 없거나 5xx를 반환하는 경우(백오프로 재시도), 잘못된 `EVALUATOR_TOKEN`(401은 최종 오류), 또는 무기한 `pending`을 반환하는 비동기 평가자(아래 참조).
+
+**세션이 완료되었지만 최종 평가가 없습니다.** `GET /evaluation-jobs?status=polling`을 조회하세요; 결과가 아직 진행 중일 수 있습니다. 작업이 `pending` 상태에 멈춰 있으면 서버가 평가자에 접근하는 데 문제가 있는 것입니다; 평가자가 실행 중이고 `EVALUATOR_TOKEN`이 일치하는지 확인하세요.
+
+**`HTTP 401 from evaluator: invalid bearer token`.** 서버의 `EVALUATOR_TOKEN`이 평가자 서비스에 구성된 값과 일치하지 않습니다. 두 값이 동일해야 합니다.
+
+**비동기 평가자가 계속 `pending`을 반환합니다.** 서버는 평가자가 `done` 또는 `error`를 반환하거나 `EVALUATOR_MAX_POLL_DURATION_SECS`(기본값 1시간)가 경과할 때까지 `GET /evaluate/{job_id}`를 폴링합니다. 제한에 도달하면 평가는 `timeout`으로 기록되고 진행 중인 큐에서 제거됩니다. 평가자가 기본값보다 더 긴 시간이 실제로 필요한 경우 `EVALUATOR_MAX_POLL_DURATION_SECS`를 늘리세요.
+
+---
+
+## 다음 단계
+
+- [평가자 에이전트 스킬](/ko/agenteye/evaluator-skill): 코딩 에이전트가 실제 세션을 바탕으로 차원을 설계하고 이 서비스를 구축하도록 합니다.
+- [Python SDK](/ko/agenteye/python-sdk): 점수화를 트리거하는 `agent_end` 이벤트를 전송합니다.
+- [API 키](/ko/agenteye/api-keys): `evaluations:read` 및 `evaluations:trigger` 권한.
+- [감사](/ko/agenteye/audits): 정책 기반 검토를 위한 Observability의 또 다른 자동화된 품질 기능.

package/.next/standalone/docs-old/ko/agenteye/evaluations.mdx

@@ -0,0 +1,50 @@
+---
+title: "평가(Evaluations)"
+description: "품질 문제가 사용자 불만으로 접수되기 전에 먼저 알 수 있습니다."
+---
+
+품질 문제가 사용자 불만으로 접수되기 전에 먼저 알 수 있습니다. 자체 채점 서비스를 한 번만 연결하면 Failproof AI Observability가 완료된 모든 실행을 자동으로 평가합니다. 따라서 유용성 저하나 환각 급증이 고객이 느끼기 전에 자동으로 표시됩니다.
+
+![점수 열이 있는 세션 그리드: 각 실행에 평가 상태 배지와 유용성, 사실성, 도구 효율성에 대한 색상 코딩 배지가 표시됩니다](/agenteye/images/sessions-list.png)
+
+*세션 그리드의 모든 실행에 점수가 표시되며, 빨간색·황색·녹색 배지 덕분에 트랜스크립트를 하나도 열지 않아도 문제 있는 실행이 바로 눈에 띕니다.*
+
+## 수동 샘플링 중단
+
+이전에는 일부 실행만 무작위로 점검하며 나머지도 괜찮을 거라 기대했을 것입니다. 이제는 완료된 모든 세션이 종료되는 즉시 원하는 기준, 즉 유용성·도구 효율성·사실성·안전성 등 여러분의 품질 기준에 따라 자동으로 채점됩니다. 점수 키는 여러분이 직접 정의하고, Failproof AI Observability는 평가기가 반환하는 모든 값을 저장·추적·표시합니다. 채점되지 않고 넘어가는 실행은 없으며, 지원 티켓을 통해 회귀를 뒤늦게 파악하는 일도 없어집니다.
+
+점수는 **`/<org-slug>/sessions`**(사이드바 → *observe* → *sessions*)의 세션 그리드에 행마다 배지 묶음으로 표시됩니다. 기준에 미달한 실행만 보고 싶다면 점수 범위로 그리드를 필터링하세요. 예를 들어 유용성 0.5 미만으로 필터링하면 검토할 가치가 있는 실행만 정확히 불러올 수 있습니다. 점수 조회에는 `evaluations:read` 권한이 필요합니다.
+
+## 낮은 점수의 원인 파악
+
+숫자는 실행이 부진했음을 알려주고, 세션 페이지는 그 이유를 알려줍니다. 실행을 열면 오른쪽 패널 상단에 핵심 요약이 나타나고, 각 항목별로 평가기가 제공한 근거와 함께 막대 그래프가 표시됩니다. 덕분에 "사실성 점수가 0.4"에서 "어떤 주장이 틀렸는지"까지 몇 초 만에 확인할 수 있습니다.
+
+![세션 오른쪽 패널: 상단에 평가 요약, 그 아래에 항목별 점수 막대와 근거 설명이 전체 이벤트 타임라인 옆에 표시됩니다](/agenteye/images/session-detail.png)
+
+*세션 상세 보기: 요약, 항목별 점수 막대, 각 점수의 근거가 실행 이벤트 타임라인 바로 옆에 표시됩니다.*
+
+더 정밀한 평가기를 배포했거나, 채점 전에 중단된 실행을 다시 확인해야 한다면? **재평가(re-evaluate)** 버튼(`evaluations:trigger` 권한 필요)을 사용하면 세션을 즉시 재채점하고 최신 결과를 타임라인에 추가합니다. 이전 점수는 기록으로 계속 확인할 수 있습니다. **`/<org-slug>/sessions/<session-id>`**에서 찾을 수 있습니다.
+
+## 전체 플릿의 품질 추세 모니터링
+
+실행 하나의 낮은 점수는 노이즈일 수 있지만, 전체 코호트가 하락하면 명확한 신호입니다. 저장된 대시보드는 점수를 한눈에 파악할 수 있는 추세로 변환해줍니다. 에이전트별·환경별로 이번 주와 지난주의 평균 유용성을 비교할 수 있습니다.
+
+![품질 대시보드: 평가 항목별 평균 점수 막대와 시간에 따른 추세 그래프](/agenteye/images/dashboard-quality.png)
+
+*저장된 품질 대시보드는 주요 점수 키의 추세를 보여주므로, 서서히 하락하는 추세가 장애로 번지기 훨씬 전에 명확하게 인지할 수 있습니다.*
+
+대시보드는 **`/<org-slug>/dashboards`**(사이드바 → *analyze* → *dashboards*)에 위치하며 조직 전체가 공유합니다. 각 카드는 관련 세션을 집계하여 세션 수, 각 주요 점수의 평균, 추세 스파크라인을 표시합니다. "세션에서 열기"를 클릭하면 해당 숫자의 기반이 되는 사전 필터링된 실행으로 바로 이동합니다. 조회에는 `dashboards:read` 및 `evaluations:read` 권한이 필요합니다.
+
+## 평가기 한 번만 연결하기
+
+채점은 옵트인 방식이며, Failproof AI Observability에 채점기를 연결하기 전까지는 완전히 비활성화 상태입니다. 소형 HTTP 서비스를 하나 실행하고(Observability에서 복사할 수 있는 참조 구현을 제공합니다), 서버에 두 가지 값을 설정하면 이후 모든 실행이 자동으로 채점됩니다. 전체 안내, 채점 계약, SDK는 상세 가이드에서 확인할 수 있습니다.
+
+어떤 항목을 채점해야 할지 모르겠다면? [평가기 에이전트 스킬](/ko/agenteye/evaluator-skill)을 사용하면 코딩 에이전트가 여러분의 세션을 분석해 점수 항목을 결정하고 서비스를 빌드·배포합니다.
+
+## 관련 문서
+
+- [평가 suite](/ko/agenteye/evaluation-suite): 평가기 연결, 채점 계약, SDK.
+- [평가기 에이전트 스킬](/ko/agenteye/evaluator-skill): 코딩 에이전트가 점수 항목을 선택하고 평가기를 빌드합니다.
+- [Sessions](/ko/agenteye/sessions): 점수가 표시되는 실행별 그리드.
+- [Dashboards](/ko/agenteye/dashboards): 조직 전체의 품질 추세를 저장하고 공유합니다.
+- [Audits](/ko/agenteye/audits): 세션 간 조사를 위한 Observability의 또 다른 자동 품질 기능.

package/.next/standalone/docs-old/ko/agenteye/evaluator-skill.mdx

@@ -0,0 +1,167 @@
+---
+title: "Failproof AI Observability 평가자 에이전트 스킬"
+description: "코딩 에이전트가 설계와 구현을 모두 담당하여, '에이전트 품질이 가끔 떨어지는 것 같다'는 막연한 생각을 실제 배포된 스코어링 서비스로 만들어 드립니다."
+---
+
+
+코딩 에이전트가 설계와 구현을 모두 담당하여, *"에이전트 품질이 가끔 떨어지는 것 같다"* 는 막연한 생각을 실제 배포된 스코어링 서비스로 만들어 드립니다. **Failproof AI Observability 평가자 스킬** (`agenteye-evaluator`)은 *Agent Skill*입니다. Claude Code나 Codex 같은 코딩 에이전트가 필요할 때 불러오는 소규모 지침 폴더로, 에이전트에게 *여러분의* 에이전트에서 추적할 가치가 있는 품질 지표를 파악하고, 그 지표를 평가하는 [평가자 서비스](/ko/agenteye/evaluation-suite)를 작성·테스트·배포하는 방법을 가르칩니다.
+
+이 스킬은 호스팅된 스코어러도, 업로드 레지스트리도, 플러그인 시스템도 **아닙니다**. 여러분의 평가자는 [Evaluation suite](/ko/agenteye/evaluation-suite) 가이드에 설명된 대로, 여러분의 인프라에서 운영되는 HTTP 서비스로 완전히 여러분의 소유입니다. 이 스킬은 에이전트가 그것을 잘 만들 수 있도록 가르칠 뿐이며, 스킬이 하는 모든 작업은 여러분이 직접 동일한 코드를 작성해서도 할 수 있습니다.
+
+---
+
+## 가장 어려운 부분은 무엇을 평가할지 결정하는 것입니다
+
+SDK 인터페이스는 간단합니다 — 데코레이터 하나와 모델 두 개 — 그리고 에이전트는 [계약](/ko/agenteye/evaluation-suite#http-contract)만으로도 이를 작성할 수 있습니다. 평가자가 실패하는 원인은 거기에 있지 않습니다. 실패의 원인은 잘못된 것을 측정하기 때문입니다. 잘못된 것을 측정하는 평가자는 없는 것보다 나쁩니다. 모두가 무시하게 되는 대시보드를 만들어낼 뿐입니다.
+
+그래서 이 스킬의 대부분은 코드가 작성되기 전 단계에 할애됩니다. 스킬은 에이전트가 여러분을 인터뷰하도록 합니다(*"잘 동작한 실행을 설명해 주세요. 이제 잘못된 실행을 설명해 주세요"*). 그런 다음 [`agenteye` CLI](/ko/agenteye/cli)를 통해 실제 세션을 가져와 처음부터 끝까지 읽습니다. 이 두 가지는 대개 서로 다른 그림을 보여주는데, 그 차이가 핵심입니다: 여러분이 측정하려는 것과 실제 트랜스크립트에서 지원 가능한 것 사이의 간극입니다. 이벤트에서 **계산 가능**하고 **변별력이 있는** 경우에만 지표로 살아남습니다 — 좋은 실행과 나쁜 실행 모두에서 0.9를 기록한다면, 아무것도 알려주지 못하므로 제외됩니다.
+
+결과물은 2~4개 지표와 그 근거가 담긴 제안서로, 코드 한 줄이 작성되기 전에 여러분의 승인을 받습니다.
+
+```mermaid
+flowchart TD
+    YOU["you: 'I want evals for my support bot'"] --> AGENT["coding agent (Claude Code / Codex)<br/>loads the agenteye-evaluator skill"]
+    AGENT -->|"interview: what does good vs bad look like?"| YOU
+    AGENT -->|"agenteye --json sessions / events"| DATA["your real sessions<br/>what actually happens"]
+    DATA --> DIMS["2-4 dimensions, you sign off"]
+    DIMS --> SVC["your evaluator service<br/>agenteye-evaluator SDK"]
+    SVC --> SCORES["scores land in the dashboard<br/>and agenteye evals"]
+```
+
+---
+
+## 다른 평가 구성 요소와의 관계
+
+평가(scoring)를 다루는 문서는 네 가지이며, 순서대로 서로 연결됩니다:
+
+| 페이지 | 내용 | 참조 시점 |
+|---|---|---|
+| **[Evaluations](/ko/agenteye/evaluations)** | 기능: 세션 그리드의 점수, 대시보드, 재평가 | 자동 평가가 무엇을 제공하는지 알고 싶을 때 |
+| **[Evaluation suite](/ko/agenteye/evaluation-suite)** | HTTP 계약, SDK, 서버 환경 변수 | 직접 평가자를 구현하거나 디버깅할 때 |
+| **평가자 스킬** (이 문서) | 스코어러 설계 *및* 구현을 위한 자연어 진입점 | "평가를 원한다"는 생각에서 실행 중인 서비스까지 가고 싶을 때 |
+| **[CLI skill](/ko/agenteye/cli-skill)** | `agenteye` CLI를 위한 자연어 진입점 | 이미 보유한 점수를 *읽고* 싶을 때 |
+| **[Python SDK skill](/ko/agenteye/python-sdk-skill)** | 에이전트 계측을 위한 자연어 진입점 | 에이전트가 아직 세션을 내보내지 않아 평가할 대상이 없을 때 |
+
+### CLI 스킬 대비: 생성 vs 읽기
+
+두 스킬은 의도적으로 겹치지 않으며, 둘 다 설치하는 것이 일반적인 구성입니다 — 에이전트는 여러분의 요청에 따라 적절한 스킬을 선택합니다:
+
+- **`agenteye-evaluator`** (이 문서)는 점수를 *생성하는* 것을 구축합니다. 처음으로 점수가 생성되면 역할이 끝납니다.
+- **[`agenteye-cli`](/ko/agenteye/cli-skill)** 는 이미 존재하는 점수를 읽습니다(`agenteye evals`). *"이번 주 품질이 떨어졌나요?"* 는 이 스킬이 답하는 질문이고, 이 문서의 스킬이 답하는 질문이 아닙니다.
+
+---
+
+## 사전 요구 사항
+
+1. **`agenteye` CLI가 설치되고 로그인된 상태** (`pipx install agenteye`, 이후 `agenteye login`). 스킬은 두 가지 용도로 CLI를 사용합니다: 설계 기반이 되는 실제 세션 가져오기, 그리고 마지막에 점수가 제대로 생성됐는지 확인하기. 로그인 계정에는 `events:read` 권한이 필요하고, 최종 확인을 위해 `evaluations:read` 권한도 필요합니다. CLI 스킬과 마찬가지로, 이메일로 전송되는 일회용 코드 로그인은 **자동으로 완료할 수 없습니다**.
+2. **평가자가 실행될 공간.** 평가자는 이미지로 빌드되어 장기 실행 서비스로 운영되므로, 임시 파일이 아닌 실제 저장소가 필요합니다. 평가자는 평가 대상 에이전트와 별도의 저장소에 운영되는 경우가 많습니다 — 스킬은 기존 저장소를 찾아보고, 새로 생성하기 전에 확인을 요청합니다.
+3. **`agenteye-evaluator` SDK 휠** — 에이전트가 `pip` 명령을 입력하기 전에 다음 섹션을 먼저 읽으세요.
+
+---
+
+## 입수 방법
+
+이 스킬은 Failproof AI의 공개 스킬 컬렉션에 게시되어 있습니다:
+
+**[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-evaluator/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-evaluator)
+
+저장소는 공개되어 있으며 스킬 자체에는 별도의 인증 정보가 필요 없습니다 — 스킬은 여러분이 로그인한 세션으로 `agenteye` CLI를 구동하고 *여러분의* 저장소에 코드를 작성할 뿐입니다. 이 스킬은 별도 폴더로 제공되며 `pipx install agenteye` 패키지에는 포함되어 있지 **않으니**, 그곳에서 찾지 마세요.
+
+## 스킬 설치
+
+가장 빠른 방법은 [`skills`](https://skills.sh) CLI를 사용하는 것입니다. 폴더를 가져와 에이전트가 찾는 위치에 배치해 줍니다:
+
+```bash
+# 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
+```
+
+이후 다른 스킬과 동일하게 관리합니다:
+
+```bash
+npx skills list -a claude-code           # 설치된 스킬 목록
+npx skills update agenteye-evaluator     # 최신 버전으로 업데이트
+npx skills remove agenteye-evaluator     # 제거
+```
+
+수동으로 설치하고 싶으신가요? Agent Skill은 `SKILL.md`(및 선택적 참조 파일)가 포함된 폴더에 불과하므로, 복사해서 사용해도 됩니다:
+
+- **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를 설치하기 전에 반드시 읽으세요.
+
+스킬은 공개되어 있지만, 스킬이 구동하는 SDK는 그렇지 않습니다. `agenteye-evaluator`는 비공개 릴리스 아티팩트로만 제공되며, `agenteye`와 달리 공개 PyPI에서 **이름이 등록되어 있지 않습니다** — 따라서 `pip install agenteye-evaluator`를 그냥 실행하면 프로덕션 트랜스크립트를 읽는 서비스에 알 수 없는 패키지가 설치될 수 있습니다. 이는 오타의 문제가 아니라 공급망 보안 문제입니다.
+
+스킬은 이를 알고 있으며, 적용 가능한 첫 번째 단계부터 순서대로 설치를 시도합니다: AgentEye 저장소 내부라면 모노레포 소스, 그렇지 않으면 GitHub Releases의 비공개 릴리스 휠(접근 권한 필요), 둘 다 접근할 수 없으면 **즉흥적으로 처리하는 대신 Failproof AI 담당자에게 휠을 문의하라고 안내하고 중단합니다**.
+
+따라서 에이전트가 공개 PyPI에서 `pip install agenteye-evaluator`를 바로 제안한다면, 스킬이 로드되지 않은 것입니다. 즉시 중단하고 스킬이 설치되어 있는지 확인하세요.
+
+---
+
+## 사용 가능한 요청 예시
+
+실제 진행 과정은 막연한 요청으로 시작해서 코드 작성이 아닌 승인된 설계로 끝납니다:
+
+```text
+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?
+```
+
+여기서부터 에이전트는 규칙 기반 지표를 먼저 작성합니다(비용 없음, 즉각적, 결정적). 그런 다음 빈 세션이나 중단된 세션처럼 단순한 평가자를 충돌시킬 수 있는 실제 캡처된 세션에 대해 테스트하고, 주관적인 지표에만 LLM 판정을 사용합니다. 에이전트는 [디스패처의 제한 사항](/ko/agenteye/evaluation-suite#configuring-the-server) — 30초 요청 타임아웃과 배포 전체에서 동시 8건 처리 — 을 알고 있으므로, 판정이 안정적으로 완료되기 어렵다면 비용을 5배로 늘려가며 취소와 재시도를 반복하는 대신 `JobPending`으로 비동기 처리합니다.
+
+이후 배포를 완료하고, 두 개의 서버 환경 변수를 설정하며, `agenteye --json evals --session-id <id>`로 점수가 실제로 생성됐는지 확인합니다. 점수 생성이 유일한 증거입니다.
+
+---
+
+## 주의 사항
+
+- **지표 이름은 사실상 영구적입니다.** 점수 키는 임의 문자열이고 플랫폼은 전송되는 모든 것의 추세를 추적하므로, 잘못된 선택을 사후에 교정할 방법이 없습니다. 나중에 이름을 바꾸면 히스토리가 분리됩니다: 이전 세션에는 이전 키가 유지되어 추세가 끊깁니다. 이것이 스킬이 코드를 작성하기 전에 명시적인 승인을 받는 이유입니다 — 그 프롬프트를 진지하게 받아들이세요.
+- **픽스처는 실제 프로덕션 트랜스크립트입니다.** 실제 세션을 기반으로 설계한다는 것은 세션을 디스크로 가져온다는 의미이며, 고객 데이터가 포함될 수 있습니다. 스킬은 git에 커밋하기 전에 확인을 요청합니다. 확신이 없다면 `fixtures/`를 저장소 밖에 두고 각 개발자가 직접 가져오도록 하세요.
+- **에이전트가 모든 트랜스크립트를 읽는 서비스를 작성하고 배포합니다.** CLI 로그인 권한 범위 내에서 여러분처럼 행동하지만, 프로덕션 데이터에 접근하는 다른 모든 코드와 동일하게 평가자를 검토하세요.
+
+---
+
+## 다음 단계
+
+- **[Evaluation suite](/ko/agenteye/evaluation-suite)**: 스킬이 구성하는 HTTP 계약, SDK, 서버 환경 변수.
+- **[Evaluations](/ko/agenteye/evaluations)**: 점수가 생성된 후 표시되는 위치.
+- **[CLI skill](/ko/agenteye/cli-skill)**: 스코어러를 구축하는 대신 결과를 읽기 위한 형제 스킬.
+- **[CLI](/ko/agenteye/cli)**: 스킬이 설계 기반으로 삼는 세션 데이터의 명령어 참조.

package/.next/standalone/docs-old/ko/agenteye/event-stream.mdx

@@ -0,0 +1,50 @@
+---
+title: "이벤트 스트림"
+description: "에이전트가 무언가를 하는 순간, 바로 확인할 수 있습니다."
+---
+
+
+에이전트가 무언가를 하는 순간, 바로 확인할 수 있습니다. 이벤트 스트림은 프로덕션의 모든 에이전트를 실시간으로 파악할 수 있는 창구입니다. 기다릴 필요도, 로그를 grep할 필요도, 방금 무슨 일이 일어났는지 추측할 필요도 없습니다.
+
+![실시간 이벤트 스트림: 색상으로 구분된 이벤트 행이 실시간으로 업데이트되며, 환경·에이전트·세션·이벤트 유형·자유 텍스트로 필터링 가능](/agenteye/images/events-stream.png)
+
+*조직 내 모든 에이전트의 모든 이벤트가 최신순으로 표시되며, 발생하는 즉시 업데이트됩니다.*
+
+## 모든 에이전트를 실시간으로 파악
+
+에이전트가 실행을 시작하거나, 모델을 호출하거나, 도구를 실행하거나, 훅을 실행하거나, 오류가 발생하면 해당 행이 발생하는 즉시 스트림 상단에 나타납니다. 조직 내 모든 에이전트의 모든 이벤트를 최신순으로 추적하므로, 오래된 정보가 아닌 현재 상태를 항상 파악할 수 있습니다.
+
+특정 서버에서 로그 파일을 tail하거나, 여러 머신에 걸쳐 grep하거나, 타임스탬프를 수작업으로 맞출 필요가 없습니다. 페이지 하나만 열면 이미 프로덕션을 모니터링하고 있는 것입니다.
+
+행은 유형별로 색상이 구분되어 있어, 모든 줄을 파싱하지 않아도 스트림을 한눈에 파악할 수 있습니다. 각 행에서 다음 정보를 즉시 확인할 수 있습니다:
+
+- **유형**: 색상으로 구분된 `agent_start`, `model_response`, `tool_use`, `hook_completed`, `error` 등.
+- **한 줄 요약**: 무슨 일이 있었는지 파악하기 위해 굳이 열어볼 필요가 거의 없습니다.
+- **해당 단계의 토큰 수**.
+- **컨텍스트 윈도우 사용률 배지**: 해당하는 경우 표시되어, 프롬프트 증가나 임박한 컴팩션을 문제가 되기 전에 미리 파악할 수 있습니다.
+
+실시간으로 모니터링하면 잘못된 배포, 무한 루프, 오류 폭발을 다음 날 로그 리뷰가 아닌 발생하는 순간에 포착할 수 있습니다.
+
+## 문제가 된 그 실행 찾기
+
+뭔가 이상해 보일 때, 엄청난 양의 데이터를 전부 뒤질 필요는 없습니다. 오류가 발생한 단 하나의 실행만 찾으면 됩니다. 스트림은 빠르게 필터링됩니다. 환경, 에이전트, 세션, 이벤트 유형, 또는 자유 텍스트로 필터링할 수 있습니다.
+
+세션 ID나 에이전트 ID로 필터링하면 첫 번째 이벤트부터 마지막 이벤트까지 하나의 실행을 추적할 수 있습니다. 이벤트 유형으로 필터링하면 특정 종류의 활동만 격리할 수 있습니다. 예를 들어 조직 전체의 모든 `error`를 한 화면에서 볼 수 있습니다. 필터를 중첩해 "모든 곳의 모든 것"에서 "프로덕션에서 오류가 나는 이 에이전트"로 몇 번의 클릭만으로 좁힌 다음, 발견한 내용에 따라 바로 조치를 취할 수 있습니다.
+
+자유 텍스트 검색으로 이미 알고 있는 메시지, 도구 이름, ID를 바로 찾아낼 수 있어, 고객 신고가 정확한 실행으로 이어지는 데 몇 초밖에 걸리지 않습니다.
+
+## 위치
+
+이벤트 스트림은 조직의 홈 화면입니다. 로그인하면 `/<org-slug>/`에서 가장 먼저 보이는 화면이 바로 이벤트 스트림이므로, 도착하는 순간부터 트리아지를 시작할 수 있습니다.
+
+이면에서는 에이전트가 SDK를 통해 이벤트를 내보내고, 수집기가 이를 Failproof AI Observability 서버로 전송하며, 스트림이 여러분이 관리하는 인프라에 도착하는 대로 이벤트를 추적합니다. 원시 로그 대신 집계된 뷰를 원한다면, 각 실행의 이벤트가 Sessions에서 단일 행으로 접혀 표시되며 클릭 한 번으로 확인할 수 있습니다.
+
+이벤트 스트림은 다른 모든 관측 화면이 기반으로 삼는 원시 진실의 원천입니다. 다른 곳에서 숫자가 이상해 보인다면, 실제로 무슨 일이 있었는지 확인하는 곳은 바로 이 스트림입니다.
+
+## 관련 항목
+
+- [Sessions](/ko/agenteye/sessions): 동일한 이벤트를 실행 단위의 한 행으로 집계하며, git 스타일의 실행 그래프를 제공합니다.
+- [Telemetry](/ko/agenteye/telemetry): 에이전트가 전송하는 내용과 이벤트가 스트림에 도달하는 방식.
+- [Error tracking](/ko/agenteye/error-tracking): 모든 오류를 한 곳에서 트리아지할 수 있는 화면.
+- [Alerts](/ko/agenteye/alerts): 임계값을 알림 규칙으로 전환.
+- [CLI and agents](/ko/agenteye/cli-and-agents): 터미널에서 동일한 실시간 추적.