agent-evaluation

MLflow によるエージェント評価

MLflow を使用して生成 AI エージェントを評価するための包括的なガイドです。このスキルは、評価ワークフロー全体、または個々の構成要素（トレース設定、環境構成、データセット作成、スコアラー定義、評価の実行）に使用できます。各セクションは、必要に応じて個別に利用できます。

⛔ 重要：MLflow API を必ず使用してください

カスタム評価フレームワークを作成しないでください。 MLflow のネイティブ API を必ず使用してください。

• データセット：mlflow.genai.datasets.create_dataset() を使用してください。カスタムのテストケースファイルは使用しないでください
• スコアラー：MLflow の組み込み機能、@scorer、または mlflow.genai.judges.make_judge() を使用してください。カスタム評価フレームワークは使用しないでください
• 評価：mlflow.genai.evaluate() を使用してください。カスタムの評価ループは使用しないでください
• スクリプト：用意されている scripts/ ディレクトリのテンプレートを使用してください。カスタムの evaluation/ ディレクトリは作成しないでください

理由： MLflow はすべて（データセット、スコアラー、トレース、結果）を実験で追跡します。カスタムフレームワークを使うとこの仕組みを回避してしまい、可観測性が失われます。

evaluation/eval_dataset.py などのカスタムファイルを作成しようと思ったら、そこで止めてください。代わりに scripts/create_dataset_template.py を使用してください。

目次

1. クイックスタート
2. ドキュメントへのアクセス手順
3. セットアップの概要
4. 評価ワークフロー
5. 参考資料

クイックスタート

⚠️ 再確認：このスキルの MLflow API を使用してください。カスタム評価フレームワークは作成しないでください。

セットアップ（前提条件）：MLflow 3.8+ をインストールし、環境を構成して、トレースを統合します

5 つのステップで進める評価ワークフロー（すべて MLflow API を使用）：

1. 把握：エージェントを実行し、トレースを確認して、目的を理解します
2. スコアラー：合意済みのスコアラー一式を登録します（まだ存在しない場合は、先に build-a-scorer を使用してください）
3. データセット：必ず既存のデータセットを先に探し、必要な場合にのみ新しく作成します 3.5. ドライラン：まず 3 つの質問で実行し、全件評価の前に、動作しないツールや誤設定されたスコアラーを見つけます
4. 評価：データセットでエージェントを実行し、スコアラーを適用して、結果を分析します

対象範囲： このスキルが担当するのは、評価の実行（登録、データセット、実行、分析）です。スコアラー一式の設計（評価基準、コードによるチェック・組み込み機能・LLM ジャッジのいずれを使うか）は、build-a-scorer スキルの担当です。両者の境界は、基準一式が確定し、各基準に採用する実装が選択された時点です。

コマンドの表記規則

MLflow と Python のコマンドには、必ず uv run を使用してください。

uv run mlflow --version          # MLflow CLI commands
uv run python scripts/xxx.py     # Python script execution
uv run python -c "..."           # Python one-liners

これにより、適切な依存関係がそろった正しい環境でコマンドを実行できます。

重要：CLI の出力を保存する場合は、stderr と stdout を分けてください。

CLI コマンドの出力をファイルに保存して解析する場合（JSON、CSV など）、ログと構造化データが混在しないよう、必ず stderr を別にリダイレクトしてください。

# Save both separately for debugging
uv run mlflow traces evaluate ... --output json > results.json 2> evaluation.log

ドキュメントへのアクセス手順

MLflow のドキュメントには、必ず llms.txt を通じてアクセスしてください。

1. 次の URL から開始します：https://mlflow.org/docs/latest/llms.txt
2. llms.txt で、具体的なプロンプトを使って目的のトピックを検索します
3. llms.txt に別のドキュメントへの参照がある場合は、その URL を使って WebFetch を実行します
4. WebSearch は使用せず、まず llms.txt を使って WebFetch を実行してください

これはすべてのステップに適用されます。特に次の項目が対象です。

• データセットの作成（llms.txt から GenAI データセットのドキュメントを読みます）
• スコアラーの登録（スコアラー API について MLflow のドキュメントを確認します）
• 評価の実行（mlflow.genai.evaluate API の使い方を理解します）

エージェントの構造を調べる

プロジェクトごとに構造は異なります。 思い込みに頼らず、動的に調査してください。

エージェントのエントリーポイントを見つける

# Search for main agent functions
grep -r "def.*agent" . --include="*.py"
grep -r "def (run|stream|handle|process)" . --include="*.py"

# Check common locations
ls main.py app.py src/*/agent.py 2>/dev/null

# Look for API routes
grep -r "@app\.(get|post)" . --include="*.py"  # FastAPI/Flask
grep -r "def.*route" . --include="*.py"

プロジェクトの構造を理解する

# Check entry points in package config
cat pyproject.toml setup.py 2>/dev/null | grep -A 5 "scripts\|entry_points"

# Read project documentation
cat README.md docs/*.md 2>/dev/null | head -100

# Explore main directories
ls -la src/ app/ agent/ 2>/dev/null

セットアップの概要

事前確認：既存の環境を使用する

セットアップを行う前に、MLFLOW_TRACKING_URI と MLFLOW_EXPERIMENT_ID がすでに設定されているか確認してください。

echo "MLFLOW_TRACKING_URI=$MLFLOW_TRACKING_URI"
echo "MLFLOW_EXPERIMENT_ID=$MLFLOW_EXPERIMENT_ID"

両方がすでに設定されている場合は、ステップ 1～2 を完全に省略してください。 環境は事前に構成されています。setup_mlflow.py を実行したり、.env ファイルを作成したり、これらの値を上書きしたりしないでください。ステップ 3（トレースの統合）と評価ワークフローに進んでください。

セットアップ手順（環境が事前構成されていない場合のみ）

1. MLflow をインストールする（バージョン >=3.8.0）
2. 環境を構成する（トラッキング URI と実験）
   • ガイド：references/setup-guide.md の手順 1～2 に従ってください
3. トレーシングを統合する（autolog と @mlflow.trace デコレーター）
   • ⚠️ 必須：トレーシングをセットアップするには、instrumenting-with-mlflow-tracing スキルを使用してください
   • ✓ 確認：実装後に scripts/validate_tracing_runtime.py を実行してください

⚠️ 評価の前にトレーシングが機能している必要があります。 トレーシングに失敗した場合は、作業を中断してトラブルシューティングしてください。

チェックポイント — 次に進む前に確認してください：

• MLflow >=3.8.0 がインストールされている
• MLFLOW_TRACKING_URI と MLFLOW_EXPERIMENT_ID が設定されている
• Autolog が有効で、@mlflow.trace デコレーターが追加されている
• テスト実行でトレースが作成される（トレース ID が None でないことを確認）

検証スクリプト：

uv run python scripts/validate_environment.py  # Check MLflow install, env vars, connectivity
uv run python scripts/validate_auth.py         # Test authentication before expensive operations

評価ワークフロー

ステップ 1：エージェントへのヒアリング（必須 — 省略しないでください）

ほかの作業を始める前に、ユーザーに次の質問をしてください。回答を得るまで先に進まないでください。

必須：

1. 「エージェントは何をしますか？目的を 1～2 文で説明してください。」
2. 「正しく実行する必要がある最も重要なことを 2～3 個挙げてください。」
3. 「すでに気づいている、よくある失敗パターンはありますか？」

回答の活用方法：

• generate_evals_df の agent_description パラメーターを作成する
• 評価の優先順位を設定する
• 品質基準がすでに明確か（ステップ 2 に進む）、それともまだユーザーと検討する必要があるか（ステップ 2 を参照し、build-a-scorer スキルを使用する）を判断する

自動モードで実行する場合： コードベース（SKILL.md、README、またはメインエントリーポイントの docstring）からエージェントの目的を読み取ってください。見つけた内容を提示し、先に進む前に確認を得てください。

範囲に関する注意： この 3 つの質問で明らかにするのは、エージェントが何であるかです。スコアラー一式を設計するには不十分です。（2）と（3）への回答が「良い回答」「正確であるべき」のように曖昧な場合は、そこからスコアラー名を考案しないでください。そのために build-a-scorer があります。

Step 2: 品質スコアラーを登録する

このステップでは、スコアラーを登録して実行します。スコアラーの設計、つまり重要な基準や、それぞれをコードチェック、組み込み機能、LLM ジャッジのどれで実装するのが最も効率的かの判断には、build-a-scorer スキルを使用します。

💡 ユーザーがまだスコアラー一式を用意していない場合は、まず build-a-scorer スキルを使用してください。 このスキルでは、基準ごとに実装方法（コードチェック、組み込み機能、make_judge）が選択され、集計後も保持される出力型を持つ、確認済みの3～5個の独立した基準が提示されます。その後、ここに戻って登録と実行を行ってください。

スコアラーがすでに実験に登録されている場合や、ユーザーから基準と実装方法の明示的なリストが提示された場合は、以下の登録に進んでください。

1. 実験に登録されているスコアラーを確認します。

   uv run mlflow scorers list -x $MLFLOW_EXPERIMENT_ID
   

重要：実験に登録されているスコアラーがある場合は、評価に必ず使用してください。

2. 合意済みの一式にある組み込みスコアラーを追加します

組み込みスコアラーについては、references/scorers.md を参照してください。一式で指定されていて、まだ登録されていないものを追加します。

3. 合意済みの一式にあるカスタムスコアラーを追加します

残りの基準は、make_judge()（LLM ジャッジ）または @scorer（決定論的なコードチェック）で実装します。API については references/scorers.md、結果を気付かないうちに壊す制約については references/scorers-constraints.md を参照してください。

合意済みの基準を実装するのではなく、この時点で基準を考案している場合は、そこで中断して build-a-scorer を使用してください。ユーザーが確認していない基準を持つスコアラーは、検証を通過しません。

⚠️ 重大 — スコアラーの戻り値： スコアラーは、LLM ジャッジに "yes" または "no"（あるいはブール値／数値）を返すよう指示する必要があります。戻り値が "pass" または "fail" の場合、_cast_assessment_value_to_float によって警告もエラーもなく None に変換され、results.metrics から除外されます。結果は単に表示されなくなります。安全な戻り値と機能しない戻り値の全一覧については、references/scorers-constraints.md の制約2を参照してください。

4. 必須：評価を行う前に、Python API を使って新しいスコアラーを登録します。

   from mlflow.genai.judges import make_judge
   from mlflow.genai.scorers import BuiltinScorerName
   import os
   
   scorer = make_judge(...)  # Or, scorer = BuiltinScorerName()
   scorer.register()
   

重要：登録前に、スコアラーの model パラメーターを設定する方法について、references/scorers.md →「Model Selection for Scorers」を参照してください。

⚠️ スコアラーは評価前に必ず登録してください。 登録されていないインラインスコアラーは mlflow scorers list に表示されず、再利用もできません。

5. 登録を確認します：

   uv run mlflow scorers list -x $MLFLOW_EXPERIMENT_ID  # Should show your scorers
   

Step 3: 評価データセットを準備する

作業の重複を防ぐため、必ず最初に既存のデータセットを確認してください。

1. データセットを検索します（必須）：

   uv run python scripts/list_datasets.py  # Lists, compares, recommends datasets
   uv run python scripts/list_datasets.py --format json  # Machine-readable output
   uv run python scripts/list_datasets.py --help  # All options
   

2. 確認結果をユーザーに提示します：

   • 見つかったすべてのデータセットとその特徴（サイズ、対象トピック）を示します
   • データセットが見つかった場合は、エージェントの種類に基づいて最も関連性の高い候補を強調します

3. 既存のデータセットについてユーザーに尋ねます：

   • 「既存の評価データセットが[N]件見つかりました。このうち1つを使用しますか？（y/n）」
   • はいの場合：使用するデータセットを尋ね、データセット名を記録します。Step 3.5 に進みます
   • いいえの場合：以下のフェーズAに進みます

新しいデータセットを作成する場合は、以下の2段階の方法を使用します。

---

Phase A: 動作確認（5つの質問 — 必ず最初に実施）

Step 1 の聞き取り回答をもとに、手作業で最小限の5問のデータセットを作成します。大規模な生成に取りかかる前に、パイプラインが最初から最後まで動作することを確認します。

import mlflow
from mlflow.genai.datasets import create_dataset

# Derive 5 representative questions directly from the agent's stated purpose
# and known failure modes identified in Step 1
sanity_records = [
    {"inputs": {"query": "<question 1 from interview>"}, "expected_response": "<expected answer>"},
    {"inputs": {"query": "<question 2 from interview>"}, "expected_response": "<expected answer>"},
    # ... 5 total
]

sanity_dataset = create_dataset(
    records=sanity_records,
    name="sanity-check-5q",
)

このデータセットで評価を実行し（Step 4 を参照）、次の説明を添えて結果をユーザーに提示します。

「これは動作確認です。5つの質問でパイプラインが正常に動作することは確認できますが、統計的に意味のある結果は得られません。適切な評価セットを生成するため、フェーズBに進みます。」

フェーズAがエラーなく完了してから、フェーズBに進んでください。

---

フェーズ B：適切な評価データセット（100 件以上の質問 — フェーズ A の合格後に実行）

一から質問を考案するのではなく、エージェントが実際に扱うコーパスから質問を生成します。Databricks を使用しているか、OSS MLflow を使用しているかによって方法が異なります。

Databricks の場合 — generate_evals_df を使用して、エージェントのドキュメントコーパスから質問を生成します。

from databricks.agents.evals import generate_evals_df, estimate_synthetic_num_evals
import mlflow

# agent_description comes from Step 1 interview answers
agent_description = "<agent purpose from interview>"

# docs_df: a Spark or pandas DataFrame with a "content" column containing
# the documents/chunks the agent retrieves from (e.g., your Vector Search index)
evals = generate_evals_df(
    docs=docs_df,
    num_evals=100,
    agent_description=agent_description,
)

# Merge into MLflow dataset — don't create a separate dataset
dataset = mlflow.genai.datasets.create_dataset(name="generated-evals-100q")
dataset.merge_records(evals)

生成前に適切な num_evals を見積もるには、次の手順を実行します。

recommended = estimate_synthetic_num_evals(docs_df)
print(f"Recommended num_evals: {recommended}")

データセットのサイズに関する目安：

• 30 件未満の質問：統計的に有意ではないため、結論を出すことは避けてください
• 50～100 件の質問：リグレッションの検出には十分で、ほとんどのエージェントに適しています
• 200 件以上の質問：モデルのバリアントを比較する場合や、複数の評価軸を採点する場合に推奨されます

OSS MLflow の場合 — RAGAS の TestsetGenerator を使用して、ドキュメントコーパスから生成します。

from ragas.testset import TestsetGenerator
from ragas.llms import LangchainLLMWrapper
from ragas.embeddings import LangchainEmbeddingsWrapper

generator = TestsetGenerator(
    llm=LangchainLLMWrapper(your_llm),
    embedding_model=LangchainEmbeddingsWrapper(your_embeddings),
)
testset = generator.generate_with_langchain_docs(docs, testset_size=100)
evals_df = testset.to_pandas()

# Convert to MLflow dataset schema and merge
import mlflow
records = [
    {"inputs": {"query": row["user_input"]}, "expected_response": row["reference"]}
    for _, row in evals_df.iterrows()
]
dataset = mlflow.genai.datasets.create_dataset(name="generated-evals-100q")
dataset.merge_records(records)

ドキュメントコーパスがない場合 — 本番環境のログまたは利用履歴から、代表的なクエリを 50～100 件ユーザーに提供してもらいます。これらは合成質問よりも現実に即しており、入手可能な場合は優先してください。

---

重要：データセットの確認を省略しないでください。新しいデータセットを作成する予定の場合でも、必ず最初に list_datasets.py を実行してください。これにより作業の重複を防ぎ、既存の評価データセットをユーザーに知らせることができます。

データセットガイドの全文： references/dataset-preparation.md を参照してください

チェックポイント — 次に進む前に確認してください：

• スコアラーが登録されている
• フェーズ A の健全性チェックに合格している（パイプラインがエンドツーエンドで実行される）
• フェーズ B のデータセットが 50 件以上の質問で作成されている（または既存のデータセットが選択されている）

ステップ 3.5：ドライラン（本評価の前に必須）

本評価を開始する前に、データセットから 3 件の質問を使って評価を実行します。これにより、ツールの故障、スコアラーの設定ミス、認証エラーを早期に検出でき、100 件の結果を気付かないうちに損なう事態を防げます。

上記のフェーズ A を完了している場合、パイプラインはすでに検証済みです。ドライランではスコアラーの出力だけに注目してください。

import mlflow

dataset = mlflow.genai.datasets.get_dataset(name="<your-dataset-name>")
dry_run_records = dataset.df.head(3)

本評価と同じラッパーおよびスコアラーを使用して、この 3 件のレコードに対し mlflow.genai.evaluate() を実行します。

各応答について、次の点を確認します：

1. ツール呼び出し — エージェントは何らかのツールを呼び出しましたか？検索が必要な質問に対してツールを一度も呼び出していない場合、ツールが正常に動作していない可能性があります（403 エラー、レート制限、認証情報の不足）。
2. 応答の品質 — 応答が空、または一般的な内容（「わかりません」「お役に立てません」など）になっていませんか？空の応答は無関係と評価され、本評価の結果を歪めます。
3. スコアラーの出力 — 3 件すべてのスコアが 0 または None になっていませんか？そうなっている場合、スコアラーの設定に誤りがあります（戻り値を確認してください — "pass"／"fail" は気付かないうちに None に変換されるため、代わりに "yes"／"no" を使用してください）。

続行の判断：

• ドライランでツールの故障または空の応答が見つかった場合： 停止してください。本評価に進む前に、根本原因（認証、ツール設定、検索）を修正します。インフラが正常に動作していない状態で本評価を実行しないでください。
• 3 件すべてのスコアラー出力が 0 または None の場合： 停止してください。スコアラーの戻り値をデバッグし、再登録してから続行します。
• ドライランに合格した場合： ユーザーに次のように報告します：「ドライランに合格しました（3 件すべての応答が空ではなく、ツールが呼び出され、スコアも 0 以外です）。本評価に進みます。」 その後、ステップ 4 に進みます。

重要な理由： ツールの故障（ドキュメントのスクレイピングでの 403 エラー、GitHub API のレート制限）により、エージェントの応答が空になり、スコアが 0 と評価されることがあります。すべてのツールが故障していたと判明するだけの 100 件の評価を実行すると、時間を浪費し、誤解を招く結果が得られます。ドライランなら 1 分もかからずにこうした問題を検出できます。

---

ステップ 4：評価を実行する

大規模なデータセット（質問 50 件以上）ですか？ スループットの最適化については、references/throughput-guide.md を参照してください。並列処理の環境変数、非同期の predict 関数、質問 200 件以上の評価に向けたデータセット分割について説明しています。

4a. 開始前に実行時間を見積もる

評価を開始する前に、所要時間をユーザーに伝えます。

1. データセットの質問数を数えます：

   import mlflow
   dataset = mlflow.genai.datasets.get_dataset(name="<your-dataset-name>")
   print(f"Dataset size: {len(dataset.df)} questions")
   

2. 所要時間を計算します — 各質問について、エージェントを1回実行し、評価スコアラーを1回実行します。

   • Opus クラスの評価モデル（例：claude-opus-4）：質問あたり約45～90秒
   • Sonnet クラスの評価モデル（例：claude-sonnet-4）：質問あたり約20～45秒
   • 質問ごとに複数のスコアラーを使う場合、時間は比例して増加します

   Estimated time = N questions × 30–60s per question ÷ parallelism factor (typically 4–8x)
   

3. 開始前にユーザーに伝えます：

   「このデータセットには質問が N 件あります。一般的な並列処理では質問あたり約30～60秒かかるため、評価には約 X～Y 分かかります。バックグラウンドタスクとして実行しますので、その間も作業を続けられます。完了したら結果をまとめてお知らせします。」

4b. 評価スクリプトを生成する

# Generate evaluation script (specify module and entry point)
uv run python scripts/run_evaluation_template.py \
  --module mlflow_agent.agent \
  --entry-point run_agent

生成されるスクリプトは、次の処理を行うラッパー関数を作成します。

• データセットの入力キーに一致するキーワード引数を受け取ります
• エージェントが必要とする追加の引数（llm_provider など）を渡します
• mlflow.genai.evaluate(data=df, predict_fn=wrapper, scorers=registered_scorers) を実行します
• 結果を evaluation_results.csv に保存します

⚠️ 重要：ラッパーのシグネチャはデータセットの入力キーと一致させる必要があります

MLflow は predict_fn(**inputs) を呼び出し、inputs 辞書の値をキーワード引数として展開します。

データセットのレコード	MLflow の呼び出し	predict_fn の定義
{"inputs": {"query": "..."}}	predict_fn(query="...")	def wrapper(query):
{"inputs": {"question": "...", "context": "..."}}	predict_fn(question="...", context="...")	def wrapper(question, context):

よくある間違い（誤り）：

def wrapper(inputs):  # ❌ WRONG - inputs is NOT a dict
    return agent(inputs["query"])

4c. バックグラウンドのサブエージェントとして起動する

メインセッションを引き続き利用できるよう、評価はバックグラウンドのサブエージェントとして実行します。run_in_background: true を指定して Agent ツールを使用します。

サブエージェントへの指示（以下をそのまま渡します）：

Run the agent evaluation and write results to scratchpad.

Steps:
1. cd <project-directory>
2. Run: uv run python run_agent_evaluation.py
3. When complete, write a summary to scratchpad/eval-results.md with:
   - Exit status (success or error message)
   - Path to results file (evaluation_results.csv)
   - Wall-clock time taken
4. Return only: "Evaluation complete. Results written to scratchpad/eval-results.md"

メインセッションでは、処理をブロックせずにスクラッチパッドファイルを確認して完了をポーリングします：

# Poll every 30s using Glob
# Glob("scratchpad/eval-results.md")
# When the file appears, read it and proceed to analysis

バックグラウンドエージェントの完了を待つために TaskOutput を使用しないでください。完全なトランスクリプト（約10,000～20,000トークン）がメインコンテキストに出力されます。

4d. 結果を分析する（評価完了後）

scratchpad/eval-results.md が作成されたら、分析を実行します。

# Pattern detection, failure analysis, recommendations
# Reads the CSV produced by mlflow.genai.evaluate() above
uv run python scripts/analyze_results.py evaluation_results.csv

スコアラーごとの合格率と改善案を含む evaluation_report.md が生成されます。

このスクリプトは、CSV の {scorer_name}/value 列と {scorer_name}/rationale 列を読み取ります。 下位互換性のため、mlflow traces evaluate のレガシー JSON 形式にも対応しています。

uv run python scripts/analyze_results.py evaluation_results.json  # legacy format
uv run python scripts/analyze_results.py evaluation_results.csv --output my_report.md  # custom output

参考資料

詳細なガイドは references/ にあります（必要に応じて読み込みます）。

• setup-guide.md - 環境のセットアップ（MLflow のインストール、トラッキング URI の設定）
• Tracing：instrumenting-with-mlflow-tracing スキルを使用します（autolog、デコレーター、セッション追跡、検証に関する権威あるガイド）
• dataset-preparation.md - データセットのスキーマ、API、作成、Unity Catalog
• scorers.md - 組み込みスコアラーとカスタムスコアラー、登録、テスト
• scorers-constraints.md - カスタムスコアラーに必要な CLI 要件（yes/no 形式、テンプレート）
• troubleshooting.md - フェーズ別の一般的なエラーと解決方法
• throughput-guide.md - 並列処理の環境変数、非同期 predict_fn、200 件以上の質問を含む評価向けのデータセット分割
• advanced-evaluation.md - 本番トレースのキュレーション、バージョンまたはプロンプトの比較、継続的評価の実行
• databricks-online-monitoring.md - Databricks で本番スコアラーを登録、開始、検証、サンプリング、管理
• prompt-optimization.md - GEPA で登録済みプロンプトを最適化し、ホールドアウトデータで評価して、条件付きで昇格

スクリプトには使い方の説明が含まれています。--help を指定して実行すると、使用方法を確認できます。