評価スイート

注意: スコアの次元はご自身が定義します。評価器はお好きな数値キーを返せます。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 が [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..

​

権限

​

結果の閲覧

• /sessions/<id>: イベントタイムラインと、セッションのスコアおよびディスパッチ試行からのエラーを表示する右ペイン。キーに evaluations:trigger 権限がある場合、エクスポートボタンの横に再評価ボタンが表示されます。agent_end を送出しなかったセッションや、新しい評価器をデプロイした後にスコアを更新する際に便利です。ダッシュボードは新しい結果をポーリングし、届いた時点で右ペインを更新します。
• /sessions: フィルタリング可能なセッション一覧グリッド。スコア列で各セッションの評価ステータスとスコアを一目で確認できます。
• /dashboards: 保存済みの評価ヘルスビュー（以下のダッシュボードを参照）。

​

ダッシュボード

• フィルター: セッションページと同じコントロール（環境、ステータス、エージェント、ローリング時間ウィンドウ、スコア範囲フィルター（key:min..max））。
• 表示設定: 表示するスコアキー、緑/黄/赤のヘルスしきい値、表示するパネル、セッションごとに最新の評価に折りたたむかどうか。

​

トラブルシューティング

​

次のステップ

• 評価器エージェントスキル: コーディングエージェントに、実際のセッションに対して次元を設計し、このサービスを構築させる。
• Python SDK: スコアリングをトリガーする agent_end イベントを送出する。
• API キー: evaluations:read と evaluations:trigger 権限。
• 監査: Observability のもう一つの自動品質機能、ポリシーベースのレビュー。