failproofai 1.0.1-beta.0 → 1.0.1

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

@@ -0,0 +1,300 @@
+---
+title: "評価スイート"
+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` が未設定の場合、パイプラインは完全に no-op になります。
+
+セッションは時間の経過とともに**複数の終端評価を蓄積できます**。各 `agent_end` イベント（およびダッシュボードからの手動再評価）ごとに新しい評価行が追記されます。これは再開された会話を評価するサポート方式です。ユーザーがエージェントを終了し、後で戻ってさらにイベントを送信し、再度エージェントを終了すると、更新された完全なトランスクリプトに対して2回目の評価が実行されます。ダッシュボードは最新の評価をヘッドラインとして表示し、以前の評価は折りたたみ可能なタイムラインとして表示します。あるセッションに対して評価が実行中の間、そのセッションの追加 `agent_end` イベントは無視されます。実行中の評価が完了した後の次のイベントで、通常どおり新しい評価がエンキューされます。
+
+アイドル状態フォールバックは再開されたセッションでも再び動作します。以前の終端評価後に新しいイベントが届き、その後セッションが `inactivity_timeout_secs` を超えてアイドル状態になった場合、新しい評価がエンキューされます。
+
+一時的な障害（5xx、429、タイムアウト、ネットワークエラー）は `EVALUATOR_MAX_ATTEMPTS` に達するまで指数バックオフで再試行されます。4xx レスポンスは終端扱いです。Observability は水平スケールされた複数のサーバーインスタンスで安全に実行できます。同じセッションが同時に2回ディスパッチされないようにワークが分割されます。
+
+---
+
+## 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": { ... } },
+    ...
+  ]
+}
+```
+
+### レスポンス形式
+
+**同期（done）:**
+
+```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` が未設定の場合、パイプラインは no-op のままです。
+
+上記のチューニングパラメータはオプションです。デフォルト値を変更する必要がある場合のみ、対応する環境変数をサーバーに設定してください。
+
+---
+
+## 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` ごとに最大 1 行（`completed_at` が最新のもの）が含まれます。セッションの評価タイムラインを現在のヘッドラインに折りたたむためにセッション一覧ページで使用されます。デフォルトは false（完全な履歴を返します）。 |
+| `GET` | `/evaluations/aggregate` | `evaluations:read` | フィルタリングされたスライスの評価ヘルスをロールアップします。総数、done/error/timeout の内訳、スコアキーごとの統計（任意の `scores` キーにわたる count/avg/min/max/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` ではそのID以前のイベントが返されます。`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` はオプションの `score_filters` パラメータを受け付けます。これにより `scores` オブジェクト内の数値で結果を絞り込めます。パラメータは `key:min..max` エントリのカンマ区切りリストです。どちらの境界も省略できます。複数のエントリは論理 AND で結合されます。指定したキーが存在しない行や非数値の行は除外されます。リクエストには最大 20 のフィルターエントリを含められます。超過した場合は HTTP 400 が返されます。
+
+例:
+```text
+# helpfulness が [0.5, 0.8] の範囲
+GET /evaluations?score_filters=helpfulness:0.5..0.8
+
+# tool_efficiency が最大 0.3（下限なし）
+GET /evaluations?score_filters=tool_efficiency:..0.3
+
+# helpfulness >= 0.5 かつ factuality >= 0.9
+GET /evaluations?score_filters=helpfulness:0.5..,factuality:0.9..
+```
+
+各 `/evaluations` レスポンスオブジェクトには以下のフィールドが含まれます:
+
+| フィールド | 型 | 備考 |
+|---|---|---|
+| `evaluation_id` | string (UUID) | この終端評価の標準識別子。各終端評価に新しい UUID が割り当てられます。1 つのセッションが複数持てます。 |
+| `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` と同じタイムスタンプ（書き込み一度のセマンティクス）。 |
+
+---
+
+## 権限
+
+| 権限 | 付与される操作 |
+|---|---|
+| `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`））。
+- **表示設定**: 表示するスコアキー、緑/黄/赤のヘルスしきい値、表示するパネル、セッションごとに最新の評価に折りたたむかどうか。
+
+各カードにはマッチするセッション数、done/error/timeout の内訳、各注目スコアの平均、小さなトレンドスパークラインが表示されます。ダッシュボードを開くとフルサイズのパネルが表示されます。**セッションで開く**をクリックすると、そのスライスに絞り込まれた状態でセッションページが開きます。メトリクスはサーバーサイドでマッチするセット全体にわたって計算されます（`GET /evaluations/aggregate` 経由）。そのため数値はサンプリングではなく正確です。
+
+![評価器の次元ごとの平均スコアバー、ツールの成功/エラー内訳、上位ツール、1 時間あたりのイベント数トレンドを含む評価ヘルスダッシュボード](/agenteye/images/dashboard-quality.png)
+
+**権限:** 閲覧には `dashboards:read` と `evaluations:read` の両方が必要です。作成と編集には `dashboards:write`、削除には `dashboards:delete` が必要です。ブートストラップ管理者はこれらすべてを自動的に受け取ります。
+
+---
+
+## トラブルシューティング
+
+**セッションは存在するが評価が作成されない。** サーバープロセスに `EVALUATOR_ENDPOINT` が設定されていること、サーバーと評価器が同じ `EVALUATOR_TOKEN` の値を共有していること、評価器の `/health` エンドポイントがサーバーから到達可能であることを確認してください。`EVALUATOR_ENDPOINT` が未設定の場合、パイプラインは no-op です。
+
+**処理中の評価が積み上がる。** `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: 無効なベアラートークン`。** サーバーの `EVALUATOR_TOKEN` が評価器サービスに設定された値と一致していません。両方が同一である必要があります。
+
+**非同期評価器が永遠に `pending` を返す。** サーバーは評価器が `done` または `error` を返すか、`EVALUATOR_MAX_POLL_DURATION_SECS`（デフォルト 1 時間）が経過するまで `GET /evaluate/{job_id}` をポーリングします。上限を超えると評価は `timeout` として記録され、インフライトキューから削除されます。評価器が正当にデフォルトより長い時間を必要とする場合は `EVALUATOR_MAX_POLL_DURATION_SECS` を増やしてください。
+
+---
+
+## 次のステップ
+
+- [評価器エージェントスキル](/ja/agenteye/evaluator-skill): コーディングエージェントに、実際のセッションに対して次元を設計し、このサービスを構築させる。
+- [Python SDK](/ja/agenteye/python-sdk): スコアリングをトリガーする `agent_end` イベントを送出する。
+- [API キー](/ja/agenteye/api-keys): `evaluations:read` と `evaluations:trigger` 権限。
+- [監査](/ja/agenteye/audits): Observability のもう一つの自動品質機能、ポリシーベースのレビュー。

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

@@ -0,0 +1,51 @@
+---
+title: "評価"
+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)
+
+*セッション詳細ビュー: サマリー、ディメンション別スコアバー、各スコアの根拠が実行のイベントタイムラインの隣に表示されます。*
+
+より精度の高い評価器をリリースした場合や、スコアリング前にクラッシュした実行を確認したい場合は、**再評価**ボタン（`evaluations:trigger` で制限）を使ってその場でセッションを再採点できます。新しい結果はタイムラインに追記され、以前のスコアも履歴として残ります。このボタンは **`/<org-slug>/sessions/<session-id>`** で確認できます。
+
+## フリート全体の品質トレンドを監視する
+
+1 件の低スコアはノイズに過ぎませんが、コホート全体の低下はシグナルです。保存済みダッシュボードを使えば、スコアをひと目で確認できるトレンドに変換できます。エージェント別・環境別に、今週と先週の平均有用性を比較するといった使い方も可能です。
+
+![品質ダッシュボード: 評価ディメンションごとの平均スコアバーと経時的なトレンド](/agenteye/images/dashboard-quality.png)
+
+*保存済みの品質ダッシュボードは注目するスコアキーのトレンドを表示するため、インシデントになる前の緩やかな低下を早期に発見できます。*
+
+ダッシュボードは **`/<org-slug>/dashboards`**（サイドバー → *analyze* → *dashboards*）にあり、組織全体で共有されます。各カードは対象セッションを集計し、セッション数・注目スコアの平均・トレンドのスパークラインを表示します。「Open in sessions」をクリックすると、任意の数値に対応する事前フィルタリング済みの実行に直接移動できます。閲覧には `dashboards:read` と `evaluations:read` の両方が必要です。
+
+## 評価器を一度接続する
+
+スコアリングはオプトイン方式で、Failproof AI Observability にスコアラーを指定するまでは完全にオフになっています。小さな HTTP サービスを一つ立ち上げ（Observability にはコピーして使える実用的なリファレンス実装が付属しています）、サーバーに 2 つの値を設定するだけで、以降のすべての実行が自動的に採点されます。詳細なウォークスルー・スコアリングの仕様・SDK は詳細ガイドに記載されています。
+
+どのディメンションを採点すべきか迷っている場合は、[evaluator agent skill](/ja/agenteye/evaluator-skill) を使えば、コーディングエージェントが実際のセッションをもとに最適なスコアディメンションを見つけ出し、サービスを構築・デプロイしてくれます。
+
+## 関連情報
+
+- [Evaluation suite](/ja/agenteye/evaluation-suite): 評価器の接続、スコアリングの仕様、SDK について。
+- [Evaluator agent skill](/ja/agenteye/evaluator-skill): コーディングエージェントにスコアのディメンション選定と評価器の構築を任せる。
+- [Sessions](/ja/agenteye/sessions): スコアが表示される実行単位のグリッド。
+- [Dashboards](/ja/agenteye/dashboards): 組織全体の品質トレンドを保存・共有する。
+- [Audits](/ja/agenteye/audits): セッションをまたいだ調査に対応する、Observability のもう一つの自動品質機能。

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

@@ -0,0 +1,167 @@
+---
+title: "Failproof AI オブザーバビリティ 評価エージェントスキル"
+description: "「エージェントの品質が不安定かもしれない」という状態から、コーディングエージェントが設計と実装の両方を担いながら、スコアリングサービスをデプロイするところまで到達できます。"
+---
+
+
+「エージェントの品質が不安定かもしれない」という状態から、コーディングエージェントが設計と実装の両方を担いながら、スコアリングサービスをデプロイするところまで到達できます。**Failproof AI オブザーバビリティ 評価スキル**（`agenteye-evaluator`）は*エージェントスキル*です。Claude Code や Codex などのコーディングエージェントがオンデマンドで読み込む、小さな命令のフォルダーです。このスキルは、エージェントが*あなたの*エージェントにとって追跡すべき品質軸を判断し、それをスコアリングする[評価サービス](/ja/agenteye/evaluation-suite)を作成・テスト・デプロイする方法を教えます。
+
+これはホスト型のスコアラーでも、アップロード先のレジストリでも、プラグインシステムでもありません。評価サービスは[Evaluation suite](/ja/agenteye/evaluation-suite)ガイドに記載のとおり、あくまでご自身のインフラ上で動作するHTTPサービスとして、あなた自身のものとして維持されます。このスキルは、エージェントがそれをうまく構築できるよう教えるだけです。スキルが行うことは、同じコードを自分で書けばすべて自分でも実現できます。
+
+---
+
+## 難しいのは、何をスコアリングするかを決めること
+
+SDKのサーフェスは小さく、デコレーターとふたつのモデルだけです。エージェントは[コントラクト](/ja/agenteye/evaluation-suite#http-contract)だけからでもそれを書くことができます。評価システムが失敗するのはそこではありません。失敗の原因は、間違ったものをスコアリングすることです。そして間違ったものをスコアリングする評価システムは、ないよりも悪い結果をもたらします。誰もが無視することを覚えてしまうダッシュボードを生み出すからです。
+
+だから、スキルの大部分はコードが存在する前の段階にあります。スキルはエージェントにあなたへのインタビューをさせます（「うまくいったセッションを説明してください。次に、うまくいかなかったものを」）。そして[`agenteye` CLI](/ja/agenteye/cli)を通じて実際のセッションを取得し、最初から最後まで読み込みます。この２つの側面は通常一致せず、そのギャップこそが重要です。あなたが測定したいと意図していることと、実際のトランスクリプトがサポートできることの差です。ある軸が残るのは、イベントから**算出可能**で、かつ**識別力がある**場合のみです。良いセッションでも悪いセッションでも0.9のスコアになるなら、何も教えてくれないため除外されます。
+
+返ってくるのは、コードが一行も書かれる前に、あなたが承認するための理由付きの2〜4軸の提案です。
+
+```mermaid
+flowchart TD
+    YOU["あなた: 'サポートボットの評価を作りたい'"] --> AGENT["コーディングエージェント（Claude Code / Codex）<br/>agenteye-evaluatorスキルを読み込む"]
+    AGENT -->|"インタビュー: 良い状態と悪い状態とは？"| YOU
+    AGENT -->|"agenteye --json sessions / events"| DATA["実際のセッション<br/>実際に起きていること"]
+    DATA --> DIMS["2〜4軸、あなたが承認"]
+    DIMS --> SVC["あなたの評価サービス<br/>agenteye-evaluator SDK"]
+    SVC --> SCORES["スコアがダッシュボードと<br/>agenteye evalsに表示される"]
+```
+
+---
+
+## 他の評価コンポーネントとの関係
+
+スコアリングに関するドキュメントは4つあり、順番に引き継ぎ合います。
+
+| ページ | 内容 | 参照するタイミング |
+|---|---|---|
+| **[Evaluations](/ja/agenteye/evaluations)** | 機能：セッショングリッドのスコア、ダッシュボード、再評価 | 自動スコアリングで何が得られるか知りたいとき |
+| **[Evaluation suite](/ja/agenteye/evaluation-suite)** | HTTPコントラクト、SDK、サーバー環境変数 | 評価サービスを自分で実装またはデバッグするとき |
+| **評価スキル**（このドキュメント） | スコアラーの設計と構築のための自然言語インターフェース | 「evalを作りたい」から動作するサービスまで進めたいとき |
+| **[CLIスキル](/ja/agenteye/cli-skill)** | `agenteye` CLIへの自然言語インターフェース | すでにあるスコアを*読み取りたい*とき |
+| **[Python SDKスキル](/ja/agenteye/python-sdk-skill)** | エージェントのインストルメント化への自然言語インターフェース | エージェントがまだセッションを出力していない — スコアリング対象がない |
+
+### CLIスキルとの違い：構築 vs. 読み取り
+
+ふたつのスキルは意図的に重複しないよう設計されており、両方インストールするのが通常の構成です。エージェントはあなたの質問内容に応じてどちらを使うか選択します。
+
+- **`agenteye-evaluator`**（このドキュメント）はスコアを*生成する*ものを構築します。初めてスコアが出るところでその役割を終えます。
+- **[`agenteye-cli`](/ja/agenteye/cli-skill)**はすでに存在するスコアを読み取ります（`agenteye evals`）。「今週、品質は下がったか？」がその問いであり、このスキルの問いではありません。
+
+---
+
+## 前提条件
+
+1. **`agenteye` CLIのインストールとログイン**（`pipx install agenteye`、その後`agenteye login`）。スキルはこれを2回使います。設計の元となる実際のセッションを取得するときと、最後にスコアが届いたことを確認するときです。ログインには`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     # 削除
+```
+
+手動でインストールする場合は、エージェントスキルは`SKILL.md`（とオプションの参照ファイル）を含むフォルダーにすぎないため、コピーするだけでも動作します。
+
+- **Claude Code**：`agenteye-evaluator/`フォルダーを`~/.claude/skills/`（全プロジェクト共通）または`<your-repo>/.claude/skills/`（そのリポジトリのみ）に置いてください。Claude Codeは自動で認識します。`/skills`リストで確認するか、evalについて質問してみてください。
+- **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
+あなた ▸ サポートボットの評価を作りたいんだけど。品質が不安定な気がする。
+
+エージェント ▸ 何かを書く前に：うまくいったセッションと、
+               うまくいかなかったセッションをそれぞれ説明してください。
+
+あなた ▸ 良い例：ドキュメントから回答できている。悪い例：でたらめなことを言う、
+         または諦めて「サポートに連絡してください」と言う。
+
+エージェント ▸ 実行中：agenteye --json sessions --status error --since 7d
+               5つのセッションを読み込み中、うち2つはあなたが問題と判断するもの。
+
+               あなたの言葉から「正確性」と「回避」が見えます。トランスクリプトは
+               回避については同意（5件中2件がサポートへの引き継ぎで終わっており、
+               model_response.contentで明確に確認できます）が、正確性については
+               イベントにグラウンドトゥルースが含まれていないため判定できません。
+
+               そこで、次の3つをスコアリングすることを提案します：
+                 - deflection      ルールベース、コスト低、2つのセッションを識別可能
+                 - tool_efficiency ルールベース、run-004のリトライループを検出
+                 - groundedness    LLMジャッジ：すべての主張が取得したドキュメントにあるか？
+
+               「正確性」にはグラウンドトゥルースが必要ですが存在しません。
+               「groundedness」がトランスクリプトで実際にサポートできる最も近い指標です。
+               この3つの名前でよいですか？後で変更すると履歴が分裂します。
+
+あなた ▸ はい
+
+エージェント ▸ このリポジトリに評価サービスが見当たりません。
+               ここにスキャフォールドしますか、それとも別の場所にありますか？
+```
+
+ここからエージェントは、まずルールベースの軸を書きます（無料、即時、決定論的）。そして、単純な評価システムをクラッシュさせる空のセッションや未完了のセッションを含む、実際にキャプチャされたセッションに対してテストします。主観的な軸にのみLLMジャッジを使います。[ディスパッチャーの制限](/ja/agenteye/evaluation-suite#configuring-the-server)（リクエストタイムアウト30秒、デプロイ全体で同時8リクエスト）を把握しているため、ジャッジが確実に収まらない場合は、5倍のコストでキャンセル・リトライが繰り返されるのを避けるため、`JobPending`で非同期処理を選択します。
+
+そしてデプロイし、2つのサーバー環境変数を設定し、`agenteye --json evals --session-id <id>`でスコアが実際に届いたことを確認します。スコアが届くことだけが唯一の証明です。
+
+---
+
+## 注意すべき点
+
+- **軸の名前はほぼ永続的です。** スコアのキーは任意の文字列であり、プラットフォームは送信された値をそのままトレンド表示します。つまり、後から誰かが悪い選択を修正することはありません。後から名前を変更すると履歴が分裂します。古いセッションは古いキーを保持し、トレンドが壊れます。だからこそスキルはコードを書く前に明示的な承認を求めます。そのプロンプトを真剣に受け止めてください。
+- **フィクスチャーは実際の本番トランスクリプトです。** 実際のセッションを元に設計するということは、それらをディスクに取得することを意味し、顧客データが含まれている可能性があります。スキルはgitにコミットする前に確認を求めます。不安な場合は`fixtures/`をリポジトリから除外し、各開発者が自分でセッションを取得するようにしてください。
+- **エージェントはすべてのトランスクリプトを読み取るサービスを作成・デプロイします。** CLIログインの権限の範囲内であなたとして動作しますが、本番データに触れる他のコードと同様に、評価サービスをレビューしてください。
+
+---
+
+## 次のステップ
+
+- **[Evaluation suite](/ja/agenteye/evaluation-suite)**：スキルが設定するHTTPコントラクト、SDK、サーバー環境変数。
+- **[Evaluations](/ja/agenteye/evaluations)**：スコアが届いた後に表示される場所。
+- **[CLIスキル](/ja/agenteye/cli-skill)**：スコアラーを構築するのではなく結果を読み取るための、姉妹スキル。
+- **[CLI](/ja/agenteye/cli)**：スキルが設計の元となるセッションデータのコマンドリファレンス。

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

@@ -0,0 +1,50 @@
+---
+title: "イベントストリーム"
+description: "エージェントが何かをした瞬間、それがすぐに見える。"
+---
+
+
+エージェントが何かをした瞬間、それがすぐに見える。イベントストリームは、本番環境で動くすべてのエージェントをリアルタイムで把握するための窓口です。待ち時間なし、ログのgrepなし、何が起きたのかを推測する必要もありません。
+
+![ライブのイベントストリーム：色分けされたイベント行がリアルタイムで流れ、環境・エージェント・セッション・イベントタイプ・フリーテキストでフィルタリング可能](/agenteye/images/events-stream.png)
+
+*組織内のすべてのエージェントからのすべてのイベントが、最新のものから順に、発生と同時に更新される。*
+
+## すべてのエージェントをリアルタイムで把握する
+
+エージェントが実行を開始したとき、モデルを呼び出したとき、ツールを起動したとき、フックを実行したとき、またはエラーが発生したとき——その瞬間にストリームの先頭に行が追加されます。組織内のすべてのエージェントのすべてのイベントを最新順で追い続けるため、古くなった情報ではなく、常に最新の状況を把握できます。
+
+つまり、どこかのサーバーでログファイルを`tail`する必要も、複数のマシン間でgrepする必要も、タイムスタンプを手動でつなぎ合わせる必要もありません。1つのページを開くだけで、すでに本番環境を監視しています。
+
+行はタイプごとに色分けされているので、1行1行を解読しなくても、ストリームをざっと眺めるだけで状況がわかります。各行には以下の情報が一目でわかります：
+
+- **タイプ**（色分け表示）：`agent_start`、`model_response`、`tool_use`、`hook_completed`、`error` など。
+- **何が起きたかの1行サマリー**。概要を把握するだけなら、詳細を開く必要はほとんどありません。
+- **そのステップのトークン数**。
+- **コンテキストウィンドウの使用率バッジ**（該当する場合）。プロンプトの肥大化やコンパクションが近づいていることを、問題が深刻になる前に視覚的に確認できます。
+
+ライブで監視することで、不正なデプロイ、暴走ループ、エラーの急増を翌日のログレビューではなく、発生した瞬間に検知できます。
+
+## 問題のある1つの実行を特定する
+
+何かがおかしいと感じたとき、大量のデータを流し見たいわけではありません。問題が起きた特定の実行を見つけたいのです。ストリームのフィルタリングは素早くできます：環境別、エージェント別、セッション別、イベントタイプ別、またはフリーテキストで絞り込めます。
+
+セッションIDやエージェントIDでフィルタリングすれば、最初のイベントから最後のイベントまで1つの実行を追えます。イベントタイプでフィルタリングすれば、特定の種類のアクティビティだけを表示できます——たとえば、組織全体の`error`をすべて1つのビューで確認するといった使い方ができます。フィルターを組み合わせることで、「すべての環境のすべてのエージェント」から「本番環境でエラーが出ているこのエージェント」まで、数クリックで絞り込み、そこから即座に対応できます。
+
+フリーテキスト検索を使えば、すでに手元にあるメッセージ、ツール名、またはIDから直接目的の情報にたどり着けるので、顧客からの報告を受けてから該当する実行を見つけるまで数秒で完了します。
+
+## 場所
+
+イベントストリームは組織のホーム画面です。サインインすると最初に表示されるのがこの画面で、`/<org-slug>/` でアクセスできます。到着した瞬間からトリアージを開始できます。
+
+その裏では、エージェントがSDKを通じてイベントを送信し、コレクターがそれをFailproof AI Observabilityサーバーに転送し、ストリームが自分たちで管理するインフラにイベントが届くたびにリアルタイムで表示します。生のトレイルではなく集計されたビューが必要な場合は、各実行のイベントがSessions上で1行にまとめられており、1クリックで確認できます。
+
+これはすべての観察用サーフェスが基盤とする生の情報源です。他の場所で数値がおかしいと感じたときは、このストリームで実際に何が起きたかを確認してください。
+
+## 関連情報
+
+- [Sessions](/ja/agenteye/sessions)：同じイベントを実行ごとに1行にまとめ、gitスタイルの実行グラフで表示。
+- [Telemetry](/ja/agenteye/telemetry)：エージェントが送信する内容と、イベントがストリームに到達するまでの仕組み。
+- [Error tracking](/ja/agenteye/error-tracking)：問題が発生したすべての事象を一元管理するトリアージ画面。
+- [Alerts](/ja/agenteye/alerts)：任意のしきい値をアラートルールに変換。
+- [CLI and agents](/ja/agenteye/cli-and-agents)：ターミナルから同じライブトレイルを確認。