From Traces to Evaluation: An Autonomous MLflow Agent Harness for AI AgentOpsの翻訳です。

本書は著者が手動で翻訳したものであり内容の正確性を保証するものではありません。正確な内容に関しては原文を参照ください。

エージェント開発におけるギャップ

DatabricksではAIエージェントデプロイをわかりやすいものにします - モデルサービングエンドポイント、自動MLflowトレーシング、Unity Catalogインテグレーション。しかし、「デプロイされた」と「本番運用レベル」の間にはギャップが存在します:

あなた手にするもの:

サービングエンドポイントで動作し、ローカルでテストされたエージェントコード
MLflowに蓄積されるトレース
エンドポイントにアクセスするユーザー

あなたが持っていないもの:

システマティックな評価のカバレッジ
あなたのドメイン向けのカスタムスコアラー
プロダクションから開発へのフィードバックループ

MLflow 3の生成AI評価フレームワークはプリミティブを提供します - スコアラー、データセット、評価ラン - しかし、手動でこれらを組み合わせることはスケールしません。多数のテーストケース、ドメイン固有のスコアラー、Databricks環境で実際に実行されるスクリプトを必要とします。

このフレームワークは組み立てステップを自動化します。 プロダクションでのトレースをファーストクラスデータとして取り扱い、評価のディメンションを推定するために解析し、実行可能な評価データセットとカスタムスコアラーを生成し、完全に実行可能なMLflow評価スクリプトを出力します。この結果は「自動評価」ではありませんが、迅速かつ信頼できるスタート地点となります - プロダクションでの挙動をエンジニアが改善、拡張、運用可能にできる明確な評価ループへと変換します。

プロダクションエージェントでなぜ評価が重要なのか

デモで動作するエージェントの構築はわかりやすいものです。プロダクション環境で信頼を持って動作するエージェントの構築 - エッジケースへの対応、時間経過に伴う品質の維持、イテレーションごとの改善 - にはシステマティックな評価が必要です。

AIエンジニアにとっての課題:

フェーズ	評価なし	評価あり
開発	「動いているようだ」	定量化された品質ベースライン
イテレーション	「これの方がいいと思う」	計測された改善(あるいは退行)
モニタリング	「ユーザーが不満を述べている」	自動化された品質ゲート

ここでこのフレームワークがギャップの橋渡しをします: MLflowは評価プリミティブを提供し、豊富なエージェントの挙動を補足します - しかし、これらを実行可能な評価スイートに組み上げるには、手動かつ時間を必要とする作業を要します。このフレームワークは、この組み立てを自動化し、数日ではなく数分でトレースを実行可能なデータセット、スコアラー、スクリプトに変換します。

プロダクションレベルのエージェントで必要とされる評価

効果的な評価は単一指標や一回の実行ではありません - 協働する複数のコンポーネントから構成されるシステムです。

1. 評価データセット

評価データセットは、ユーザーが実際にどのようにエージェントとやりとりしたのかを表現します。これらのデータセットは、以下の組み合わせで構築できます:

実際の入力、出力、実行コンテキストをキャプチャするプロダクショントレース
既知のエッジケースや重要なワークフローをターゲットとしたキュレーション済みの例
観測されていない、あるいは攻撃的な私なりを検証するために設計された合成ケース

従来のMLと異なり、エージェント評価データセットは多くの場合ラベルづけが部分的です。正確な正解データよりも、期待値、ガイドライン、制約に依存し、現実的でスケーラブルな評価においては、トレースから派生したデータが特に重要なものとなります。

2. スコアラー

スコアラージャッジエージェントは、評価データセットに対してレスポンスを生成します。実際には、これは以下の組み合わせとなります:

組み込みのチェック (安全性、適切性など)
定性的評価基準のためのLLM-as-judgeスコアラー
構造化、ドメイン固有ルール向けのプログラムによるスコアラー
エッジケースの検証、スコアラーの調整、判断を違えた判定の訂正のためのヒューマンフィードバック

スコアラーは、エージェントにとって何が「良い」のかを定義し、本質的にはアプリケーション固有です。

3. 実行とトラッキング

評価は実行可能、繰り返し可能、時間経過と共にトラックされるべきです - 大光が自動で検知されるようにメトリクスとアーティファクトと共に記録されるべきです。これなしには、評価結果はアクション可能なものではなく、個人の見解の基づくものになってしまいます。

MLflow 3の生成AI評価が可能にすること

フレームワークに踏み込む前に、MLflow 3が何を提供するのかを理解することが重要です。

ファーストクラスデータとしてのトレース

Databricksモデルサービング上でのすべてのエージェントの呼び出しはトレースをキャプチャします - 入力、出力、レイテンシー、ツール呼び出し、検索結果がキャプチャされます。これらのトレースをクエリーすることができます:

import mlflow

# Find slow traces from production
slow_traces = mlflow.search_traces(
    filter_string="attributes.execution_time_ms > 5000",
    experiment_ids=["prod-support-agent"]
)

# Find failures
errors = mlflow.search_traces(
    filter_string="attributes.status = 'ERROR'"
)

LLM-as-judgeとコードベースのスコアラー

MLflow 3は、セットアップ不要から完全カスタムまでの4レベルのLLMベースの評価を提供します:

from mlflow.genai.scorers import Safety, RelevanceToQuery, Correctness

# Ready to use immediately
scorers = [Safety(), RelevanceToQuery(), Correctness()]

# Guidelines lets you define natural language criteria:
from mlflow.genai.scorers import Guidelines

policy_scorer = Guidelines(
    name="policy_compliance",
    guidelines=[
        "Response must reference official policy documents",
        "Response must not promise exceptions to stated policies"
    ]
)

# make_judge gives full control for complex evaluation:
from mlflow.genai.judges import make_judge

resolution_judge = make_judge(
    name="issue_resolution",
    instructions="""
    Evaluate if the customer's issue was resolved.
    User's messages: {{ inputs }}
    Agent's responses: {{ outputs }}

    Respond with exactly one of:
    - 'fully_resolved'
    - 'partially_resolved'
    - 'needs_follow_up'
    """
)

# Custom scorers use pure Python for programmatic checks:
from mlflow.genai.scorers import scorer

@scorer
def contains_citation(outputs: str) -> str:
    # Return pass/fail string
    return "yes" if "[source]" in outputs else "no"

期待値を伴う評価データセット

評価データセットには、正確なラベルではなく期待値を含めることができ、部分的な教師データを可能にします:

eval_data = [
    {
        "inputs": {"query": "What's your refund policy?"},
        "expectations": {
            "expected_facts": ["30-day window", "original payment method"],
            "guidelines": ["Must cite policy document"]
        }
    }
]

この構造によって、網羅的な正解データを必要とすることなしに定性的な挙動の評価を可能にします。

ギャップ: MLflow 3はパワフルなプリミティブを提供します - しかし、これらを包括的でドメイン固有の評価スイートに組み立てるには依然として手作業が必要です。チームはトレースを解析し、データセットを設計し、スコアラーを定義し、すべてを実行可能なスクリプトに繋ぎ合わせる必要があります。このオーバーヘッドは間違いなく、自律的な生成が重要となる部分です。

現実: 評価を適切に行うことは依然として困難です

適切なツールを手に入れたとしても、評価は依然としてエージェント開発においてもっと�投資されていない部分の一つであり続けています。

理由は馴染みのあるものです: 評価はユニットテストやドキュメント化のようなものです。誰でもその必要性には同意します。いくつかのチームは全体的にそれを実装します。さらに少数のチームは最新の状態に保ちます。

実際には、チームは以下の点で苦戦します:

プロダクションでの挙動からの代表的なテストケースの抽出
ドメイン固有のスコアラーの記述と維持
すべてのパーツの実行可能、繰り返す可能な評価パイプラインへの組み上げ

この工数は、初期投資、面倒で優先度を下げることは簡単です - 特にエージェントが「デモ」で動作しているように見える際には。

これが、エージェントハーネスフレームワーク(エージェント実行基盤)が評価セットアップの最も時間を要する部分を自動化しつつも、判定と改善をエンジニアや専門家に委ねることで対応するギャップなのです。

エージェントハーネスフレームワーク - トレースから実行可能な評価へ

このフレームワークはあなたのMLflowトレースから3つのアーティファクトを生成します:

アーティファクト	同梱物	使い方
評価データセット	プロダクショントレース + 合成エッジケースから生成されたテストケース	`mlflow.genai.evaluate()`への入力
カスタムスコアラー	ドメイン固有のLLMジャッジ + プログラム的なチェック	スコアラーリストとして評価に渡す
実行スクリプト	お使いのDatabricksワークスペースをターゲットにした完全なPythonスクリプト	`python run_eval.py`による実行

重要な制約: 生成されたすべてのアーティファクトは出力前に検証されます。スコアラーはコンパイルされます。データセットは期待されるスキーマと一致します。スクリプトはエラーなく実行されます。「推奨事項」ではなく、動作するコードのみを提供します。

データ戦略

このフレームワークはお手持ちのものに基づいて3つの戦略をサポートします:

戦略	使用条件	予測関数(predict_fn)が必要か
トレースから	既存のトレースあり、エージェントアクセスなし	No - 出力は事前計算
手動	キュレートされたエッジケースが必要、呼び出し可能なエージェントあり	Yes - 評価時にエージェントを呼び出し
ハイブリッド	最高のカバレッジ	両方のアプローチの組み合わせ

ほとんどのデプロイメントではトレースからでスタートし、開発環境や本番環境ですでにエージェントが生成したレスポンスを評価します。

置き換えではなくスタート地点

このフレームワークは、評価を完全に自動化しません - そして、これは意図的なものです。評価においては、あなた固有のユースケースで何が重要かに関して人間による判断が必要です。

提供するもの:

現実の本番環境での挙動に基づくトレースベースのベースライン
自動で特定されるパターンや失敗モード
初日から実行可能な評価コード

人間主体であり続けるもの:

テストケースやスコアラーの評価基準の改善
未観測のエッジケースの追加
評価結果に基づくイテレーション

成果物は継続的なループとなります: トレース → 生成された評価データセット → レビュー → 改善された評価データセット → エージェントの変更 → 新たなトレース。それぞれのサイクルでカバレッジと信頼性が向上します。

エージェントアーキテクチャ - エージェントハーネスパターン

長時間の生成タスクは予測可能な方法で失敗します: エージェントにおけるコンテキストの蓄積、単一パスで大量の問題を解こうとする、作業が完了する前に停止するなどです。

このフレームワークは、増分的実行から初期化を分離し、新規のコンテキスト、共有の永続化された状態で短期間のセッションを用いることで、Anthropicにおける長期間実行されるエージェントの効果的なハーネスに関する研究を参考にしています。

エージェントハーネスは、モデルを取り囲むオーケストレーション層であり、LLMでは管理できないもの(タスク分解、セッション境界、状態の引き継ぎ、障害復旧)を管理します。単一の長時間実行エージェントに依存する代わりに、ハーネスはチェックポイント化された状態を持つ境界付きセッションで作業を実行し、信頼性の高い進行と安全な再試行を可能にします。

Claude Agent SDKベースに構築

このフレームワークは、ツールを使用し、セッション間の状態を保持し、マルチステップのタスクを実行する自律エージェントの構築向けのAnthropicのフレームワークである、Claude Agent SDKを用いて構築されています。Claude Agent SDKは、信頼できる情報源としてファイルシステムを取り扱います。タスクは既存ファイルを調査し、増分的に変更を行い、出力を検証し、明示的に状態を永続化することで実行されます - これは人間のエンジニアが作業する様子を模しています。

なぜClaude Agent SDKなのか？

能力	使い方
ツール連携	MLflowトレースのクエリー、エクスペリメントのメタデータ、注釈、メトリクス向けのMCPツール
ファイルシステムへのアクセス	評価アーティファクトの読み書き。コードを繰り返し構築、検証するためにls、grep、diffのようなツールや構造化された編集の活用
セッション管理	ファイルベースの状態引き渡しによるセッションごとにフレッシュなモデルのコンテキスト
スキルシステム	コード生成前に検証されたMLflow 3.x APIパターンや既知の注意点をロード
ストリーミング実行	長期間の生成と検証におけるリアルタイムの進捗表示

Databricks連携: すべての推論はDatabricks基盤モデルAPIを通じてClaude Opus 4.5を通じて実行され、処理の実行やデータはワークスペース境界にとどまります。スキルファイル、プロンプト、データ、中間状態はUnity Calalogのボリュームに格納され、システムを監査可能、再現可能にし、Databricksの権限によって完全に管理されます。

このフレームワークは、直接的なエージェントの挙動の改善ではなく、トレース駆動の評価インフラストラクチャの生成にフォーカスしており、ヒューマンフィードバックから学習するAgent BricksやDSPyのようなツールと補完関係にあります。

アーキテクチャ概要

エージェントフロー

なぜエージェントではなくセッション？

それぞれのセッションはフレッシュなモデルコンテキストで実行されますが、共有のファイルベースの状態に対して読み書きを行います。これによって、長期間実行されるエージェントの一般的な失敗モードであるエラーの集積、コンテキストのドリフト、不安定なリトライを回避しつつも、明示的な状態の引き継ぎを通じて継続性を保持します。

イニシャライザセッションはトレースを解析し、具体的なタスクプランを生成します。そして、それぞれのワーカーセッションは単一のタスクを実行し、結果を永続化して終了します。検証が失敗した場合には、「修正タスク」が追加され、以降のセッションでピックアップされます。進捗は増分的、明示的、再起動可能であるように設計されています。

なぜDatabricksジョブ？

このセッションベースのアーキテクチャは、インタラクティブなノートブックではなく、本質的にDatabricksジョブとの相性がいいです:

観点	インタラクティブノートブック	Databricksジョブ
コンテキスト	セルに跨って状態が集積	実行ごとにフレッシュな環境
実行	手動による監視が必要	無人実行
失敗からのリカバリー	手動での再起動	永続化された状態から自動リトライ
スケジューリング	アドホック	スケジュール、あるいはイベント駆動
モニタリング	コンソールの出力	ジョブUI、アラート、MLflowトレース

それぞれのセッションはUCボリュームに書き込まれること以外はステートレスなので、リトライは安全で決定論的です。失敗したタスクは、ワークフロー全体を再度実行することなしに再実行できます。

典型的なワークフロー:

MLflowエクスペリメントに対して夜間あるいは週次で実行するDatabricksジョブをスケジュール
イニシャライザが新規トレースを解析し、評価カバレッジを更新
ワーカーセッションが更新されたアーティファクトを生成して検証
エンジニアがUnity Catalogボリュームの出力をレビューし、必要に応じてスコアラーを改善

トレースの解析: スタート地点

イニシャライザセッションはテストケースを発明しません - MLflowトレースにキャプチャされた観測挙動から直接生成します。

以下に、現実のマルチエージェントデプロイメントからの代表的な抜粋を示します:

{
  "agent_type": "Multi-Genie Orchestrator - A LangGraph-based supervisor
                 that routes business questions to specialized Databricks
                 Genie agents",

  "trace_summary": {
    "total_analyzed": 30,
    "success_count": 25,
    "error_count": 5,
    "avg_latency_ms": 27000
  },

  "query_types_observed": [
    {"type": "sales_pipeline", "routing": "customer_sales"},
    {"type": "supply_chain", "routing": "supply_chain"},
    {"type": "system_info", "routing": "none (supervisor handles directly)"}
  ],

  "optimization_opportunities": [
    {
      "issue": "Suboptimal routing",
      "description": "Supervisor sometimes calls both genies when only one is needed",
      "impact": "5+ seconds wasted per unnecessary genie call"
    }
  ]
}

プロダクショントレースで非効率的なルーティングを確認できるので、フレームワークはこの挙動を継続、抑止するための専用のスコアラーであるefficient_routingを生成します。

イニシャライザセッションの出力(サマリー)

トレースの解析後に、イニシャライザは具体的な評価プランを生成します:

エージェントの理解:

タイプ: マルチエージェントスーパーバイザー(LangGraphベース)
目的: ビジネスインテリジェンスのクエリーに回答するために、特化された「Genie」エージェントのオーケストレーション
ドメイン: セールスパイプライン(customer_sales)とサプライチェーン(supply_chain)
モデル: Databricks上のClaude 3.7 Sonnet
I/O: {query: "..."}を受け取り、マークダウンテーブルを用いて{response: "..."}を返却

特定された評価ディメンション:

スコアラー	タイプ	根拠
Safety	Builtin	必須のベースライン - 有害なコンテンツがないこと
RelevanceToQuery	Builtin	レスポンスはビジネスの質問に対応すべき
correct_routing	Guidelines	クエリーのタイプに基づいて適切なGenieにルーティング
efficient_routing	Guidelines	不要なGenieを呼び出さない
data_presentation	Guidelines	テーブルは明確で適切に整形されていること
error_handling	Custom	エラーレスポンスの構造を検証

データ戦略: traces (predict_fnは不要)

既存のプロダクショントレースから入力と出力を抽出
計算済みのレスポンスを直接評価

作成されたタスクプラン (eval_tasks.json)

評価データセットの構築 - 5つのトレースサンプルから抽出
スコアラーの作成 - 6つのスコアラー(2つの組み込み、3つのガイドライン、1つのカスタム)
評価スクリプトの生成 - 計算済みの出力を用いたmlflow.genai.evaluate()
実行と検証 - 実行して記録されたメトリクスを検証

出力ファイル:

eval_tasks.json - ワーカーセッションのタスク一覧
state/analysis.json - 20個のOKなトレース、5個のERRORトレースによるトレース解析

生成された評価データセット

# From sessions/2025-12-19_093956/evaluation/eval_dataset.py
EVAL_DATA = [
    # Sales Pipeline Query - should route to customer_sales only
    # Status: OK but SUBOPTIMAL - called both genies unnecessarily
    {
        "inputs": {
            "query": "How's my pipeline just in the americas and by segment?"
        },
        "outputs": {
            "response": """Sales Pipeline for the Americas by Segment:

|    | company_size_segment__c   |   sum(pipeline_amount) |
|---:|:--------------------------|-----------------------:|
|  0 | ENT                       |                15999.6 |
|  1 | MM                        |                18003.1 |
|  2 | SMB                       |                26001.2 |"""
        },
        "metadata": {
            "source_trace": "tr-d45af7104661af36e7ccd1e81a76f2d8",
            "query_type": "sales_pipeline",
            "expected_routing": "customer_sales",
            "actual_routing": "customer_sales, supply_chain",
            "routing_optimal": False
        }
    },
    # ... more test cases
]

生成されたスコアラー

スコアラーは、あなたのエージェントのドメイン向けに仕立てられ、トレース解析から生成されます:

# From sessions/2025-12-19_093956/evaluation/scorers.py
from mlflow.genai.scorers import Guidelines, Safety, RelevanceToQuery

# Built-in scorers
safety_scorer = Safety()
relevance_scorer = RelevanceToQuery()

# Domain-specific: Correct routing for multi-agent orchestration
correct_routing_scorer = Guidelines(
    name="correct_routing",
    guidelines="""The agent should correctly route questions:
    1. Sales questions → customer_sales Genie
    2. Supply chain questions → supply_chain Genie
    3. System questions → Answer directly (no Genie call)
    4. Out-of-scope → Decline gracefully"""
)

# Performance: Identified from trace analysis showing suboptimal routing
efficient_routing_scorer = Guidelines(
    name="efficient_routing",
    guidelines="""The agent should minimize unnecessary Genie calls:
    1. Pure sales questions: Only customer_sales Genie
    2. Pure supply chain questions: Only supply_chain Genie
    3. Only multi-domain questions should call both Genies

    Unnecessary calls waste 5+ seconds each."""
)

def get_all_scorers():
    return [
        safety_scorer,
        relevance_scorer,
        correct_routing_scorer,
        efficient_routing_scorer,
        # ... additional scorers
    ]

評価結果

6セッション(イニシャライザの1つ、5つのワーカー)の後で、評価スイートは処理を成功させました。このフレームワークは成功を宣言する前にすべてを検証します:

{
  "validation_status": "passed",
  "metrics": {
    "Safety/mean": 1.0,
    "RelevanceToQuery/mean": 0.7,
    "correct_routing/mean": 0.5,
    "efficient_routing/mean": 0.9
  },
  "validation_checks": {
    "script_executes": true,
    "all_scorers_returned_values": true,
    "no_nan_scores": true
  }
}

MLflow UIにおける評価結果:

エージェントにスキルを与える - 検証されたAPIパターン

生成コードは多くの場合、古かったり間違ったAPIをターゲットにすることで失敗します。MLflowの生成AI評価インタフェースは急速に進化しており、古いブログ記事やQ&Aサイトの例は多くの場合不適切となります。

これを防ぐために、このフレームワークはAnthropicのスキルメカニズムを採用しています - いかなるコードを記述する前にエージェントには、検証されたタスク固有の知識が提供されます(Anthropicの発表: 「Equipping agents for the real world with Agent Skills」をご覧ください。)。スキルは制約が課せられた参照レイヤーとして動作し、エージェントがトレーニング時の仮定に頼るのではなく既知の正しいパターンに従うようにします。

フレームワークは、すべての評価アーティファクトを生成するために検証されたMLflow 3.1+のインタフェースを含むスキルファイルをロードします(スキルの詳細に関してはこちらのGithubリポジトリをご覧ください)。

よくある間違いを防ぐ

.claude/skills/mlflow-evaluation/references/GOTCHAS.md から:

よくある間違い	正しいパターン
mlflow.evaluate()	mlflow.genai.evaluate()
{"query": "..."} (フラット)	{"inputs": {"query": "..."}} (ネスト)
def predict_fn(inputs):	def predict_fn(**inputs): (unpacked kwargs)
Guidelines(guidelines="...")	Guidelines(name="...", guidelines="...")
from mlflow.metrics	from mlflow.genai.scorers

検証されたインタフェース

CRITICAL-interfaces.mdから:

# Scorer function signature (verified for MLflow 3.1+)
from mlflow.genai.scorers import scorer
from mlflow.entities import Feedback

@scorer
def my_scorer(
    inputs: dict,       # What was sent to the agent
    outputs: dict,      # What the agent returned
    expectations: dict  # Ground truth (optional)
) -> Feedback | bool | int | float:
    return Feedback(value=True, rationale="Explanation")

事前にこれらのスキルをロードすることで、エージェントはトレーニングデータにある古いパターンではなく現在のMLflow APIにマッチする評価コードを生成します。

なぜこれが重要なのか

検証されたインタフェースなしには、生成されたコードは初回実行で大抵失敗します:

間違ったインポートパス(MLflow 2.x vs 3.x)
必須パラメーターの欠如(Guidelinesには名前とガイドラインの両方が必要)
間違った関数のシグネチャ(predict_fnはアンパックされたkwargsを受け取る)

スキルシステムは実行時ではなく生成時にこれらをキャッチします。

Databricksで始める

このフレームワークは、ローカルあるいはインタラクティブなノートブックとDatabricksジョブの両方で実行するように設計されています。完全なセットアップ手順、設定の詳細、サンプルはGithubリポジトリで文書化されています:

GitHub: https://github.com/alexmillerdb/mlflow-eval-agent

前提条件(サマリー)

Databricksワークスペース
MLflow 3.1+
MLflowエクスペリメントに記録されたトレースを持つエージェント

実行手順(概要)

イニシャライザセッションがプロダクショントレースを解析し、タスクプランを生成
ワーカーセッションが評価データセット、スコアラー、実行可能なスクリプトを生成
評価ステップが評価を実行し、結果を検証
出力がsessions/{タイムスタンプ}/evaluation/に書き込まれる

生成された評価は、お使いのDatabricksワークスペースに対して直接実行でき、トラッキングと比較のために結果がMLflowに記録されます。

ステップバイステップの手順 - ローカル開発、Databricksデプロイメント、ジョブの設定 - に関してはリポジトリのREADMEをご覧ください。

サマリー

観点	手動のアプローチ	本フレームワーク
初回の評価スイートまでの時間	1-3日	< 2時間
プロダクションからのテストケースの生成	ほとんど行われない	標準
初回実行でコンパイルされるスコアラー	約60%	> 95%
実際の失敗モードに対するカバレッジ	アドホック	システマティック

価値は単なるスピードだけではありません - 繰り返し可能なシグナルです。評価の維持を困難にする初期の主導の作業を排除することで、MLflowトレースは信頼を持って評価のフィードを生成し、評価は現実のギャップ、対抗に直面することになり、エンジニアは修正箇所や次に改善することにフォーカスできるようになります。

評価をアドホックなタスクではなく、トレース駆動のインフラストラクチャに変換することで、このフレームワークは、チームがすでに頼りにしているMLflowとDatabricksのプリミティブを用いることで、エージェント挙動のシステマティックな計測を、プロダクションにおいて実践的なものにします。

はじめてのDatabricks

はじめてのDatabricks

Databricks無料トライアル

Databricks無料トライアル