エージェントのオブザーバビリティに関する基本概念
エージェントの観測性と品質は、1つの繰り返しループを中心に構築されています。 エージェントの問題の発見、体系的な測定、修正、修正の確認、および再発防止のためのモニタリング。 このページのすべての概念は、そのループの1つのピースです。
このページでは、それぞれの要素とそれらの関係について説明します。
品質ループ
以下の各セクションは、このループ内のステージに対応しています。
トレースとスパン
トレース は、エージェントの1回の完全な実行（トップレベルの入力と出力、すべての中間ステップ（LLM呼び出し、リトリーバーのルックアップ、ツールの呼び出し）、レイテンシ、エラー）の構造化された記録です。トレースは、ループ内の他のすべてのステージにフィードされる生データです。
内部的には、トレースは スパン のツリー構造です。各スパンは 1 つの操作を表します。入力された内容、出力された内容、かかった時間、およびメタデータが記録されます。ルートスパンはエージェントのリクエスト全体を表し、子スパンはそのリクエスト中に発生したサブ操作を表します。
トレースは、Delta テーブルとして Unity Catalogに保存されます（推奨）。これにより、ガバナンスされたアクセス、SQL クエリー機能、およびエクスペリメントごとのストレージ上限なし（他のすべての UC テーブルと同じガバナンスモデル）が提供されます。保存後は、UI でトレースを探索したり、SQL でクエリーを実行したり、Genie Code を使用して自然言語で質問したりできます。
関連情報： エージェントの計装 · UIでのトレースの表示 · トレースの検索とクエリー
セッション
セッション とは、1つのマルチターン会話から関連するトレースをグループ化するタグです。各トレースに mlflow.trace.session を設定します。セッションのグループ化により、単なるターン単位ではなく、会話の品質をエンドツーエンドで評価できます。
評価：フィードバックと期待値
評価 は、トレースに添付される品質測定値です。次の2種類があります。
Type | 追加するユーザー | キャプチャされる内容 |
|---|---|---|
フィードバック | スコアラー、エンド ユーザー、ドメイン エキスパート | 品質の判定: 合格/不合格、数値スコア、または自由形式のコメント。例: 応答を安全ではないとマークする |
エクスペクテーション | ドメイン エキスパート | 特定の入力に対する正しい出力 — グラウンドトゥルース。例: 質問に対する期待される回答、応答に含める必要がある事実。 |
フィードバックは、日常的な品質作業における主要なシグナルであり、MLflow から価値を得るために期待値は必ずしも必要ありません。期待値はオプションですが、最も正確なスコアリングを可能にします。Correctness などのジャッジは、エージェントの応答を既知の正しい回答と比較します。
関連情報: 開発者の注釈 · 専門家のフィードバック · ユーザーフィードバックの収集
スコアラー
スコアラー とは、トレースを評価し、フィードバック評価を返す関数です。すべてのスコアラーは同じ契約に従います: トレースを受信する → 関連フィールドを抽出する → 評価する → Feedbackを返す。同じスコアラーがオフライン評価とライブの本番運用モニタリングの両方で機能します。品質ロジックを一度記述すれば、どこでも適用されます。
スコアラーの種類
Type | 評価方法 | 使用する場合 |
|---|---|---|
ビルトインのLLMジャッジ | 正確性、関連性、安全性、根拠、ガイドラインへの準拠などの一般的なディメンションに対応する、事前構築済みの LLM 駆動型評価者。 | カスタム コードを記述せずに、すぐに品質カバレッジを取得できます。 |
カスタムLLMジャッジ | 定義したカスタム評価プロンプトと採点基準を持つ LLM ジャッジ。 | 組み込みのジャッジではドメイン固有の基準をカバーできない場合や、きめ細かいスコアリング (数値グレード、カスタム カテゴリ) が必要な場合。 |
コードベースのスコアラー | 決定論的な Python 関数 — 完全一致、形式検証、レイテンシーチェック、ビジネスルール。 | 言語モデルを必要としない、正確で再現可能なロジックが必要です。 |
ジャッジとスコアラーの比較
ジャッジ (例: mlflow.genai.judges.is_correct) は特定の基準に基づいてテキストを評価しますが、トレースの読み取り方法は認識していません。 スコアラー はアダプターであり、トレースから関連フィールド (リクエスト、レスポンス、取得されたコンテキストなど) を抽出し、ジャッジやカスタムロジックに渡します。scorers=[Correctness()] で組み込みジャッジを直接使用すると、MLflow は自動的にそれをスコアラーでラップします。
関連情報: スコアラーの概要 · 組み込みジャッジ · カスタム LLM ジャッジ · コードベースのスコアラー
評価データセットとラン
評価データセット
evaluation dataset は、バージョン管理された厳選されたテストケースのコレクションです。各レコードには次のものが含まれます：
inputs：エージェントに送信する内容expectations（オプション） ：グラウンドトゥルースを必要とするスコアラーで使用される、正しい出力。
本番環境または開発環境から代表的なトレースを選択するか、ゼロからケースを作成するか、外部ソースからインポートして、データセットを構築します。データセットはバージョン管理されるため、テストスイートの時間の経過に伴う増加を追跡できます。
関連情報： 評価データセットの構築
評価ラン
評価ラン は、mlflow.genai.evaluate()を呼び出した結果です。データセットとスコアラーのリストを指定すると、次の処理が実行されます:
- データセット内のすべての入力でエージェントを実行し、トレースをキャプチャします。
- 各スコアラーをすべてのトレースに適用し、フィードバック評価を生成します。
- 個別のトレースとともに、集計された合格率とメトリクスを保存します。
評価ランを使用して、 今回の変更により品質が向上したかどうか を確認します。また、 他の部分に回帰（デグレ）が発生していないか を確認します。ランを並べて比較し、反復を通じた進捗を追跡します。評価ランは特殊なタイプの MLflow ランであり、 プログラムによるクエリの実行が可能です。
本番運用のモニタリング
本番運用のモニタリング では、ライブエージェントトラフィックに対してスコアラーが自動的に実行されるようにスケジュールを設定します。デプロイされたエージェントにスコアラーをアタッチすると、モニタリングサービスがローリングベースで受信トレースのスコアリングを行い、フィードバック評価を同じトレースに書き戻します。
フィードバック形式はオフライン評価と同一であるため、品質のトレンドを開発環境と本番環境の間で直接比較できます。本番運用モニタリングによりサイクルが完結します。ライブトラフィックにおける新たな障害が検知され、次の反復で修正するために評価データセットに追加されます。
関連情報: 本番運用のモニタリングの概要 · モニタリングの起動と構成
すべての要素を組み合わせる
各概念は、品質ループの特定のステージに対応しています：
ステージ | 主な概念 |
|---|---|
エージェントのトレース | トレース、スパン |
問題の検索 | トレース、セッション、UI、SQL クエリー、Genie Code による自然言語分析 |
フィードバックの収集とデータセットのキュレーション | 評価（フィードバック ＋ エクスペクテーション）、評価データセット |
スコアラーを記述し、エージェントを修正し、修正を評価します | スコアラー、評価のラン |
本番運用のモニタリング | 本番運用モニタリング、スケジュール済みスコアラー |
ループがそれらを接続します: 本番運用モニタリングで新しい障害ケースが特定される → それらをデータセットにキュレートする → スコアラーを作成または調整する → 評価して修正を確認する → 改善されたエージェントが本番運用に移行する → モニタリングで次の問題が監視される。
次のステップ
- エージェントの計装 — 数行のコードでエージェントにトレーシングを追加する
- 問題の観察と検出 — キャプチャされたトレースの探索と分析
- 評価データセットの構築 — トレースを構造化テストケースにキュレートします
- 評価をランする — データセットに対してエージェントをスコアリングします
- 本番運用モニタリングのセットアップ — ライブトラフィックにおける品質の低下を検出する