fix-agent-issue

エージェントの問題を修正する

ユーザーは、AI エージェントの動作を変更したいと考えています。何かが間違っている場合（トレースを示す、気に入らなかった回答を貼り付ける、失敗の状況を説明するなど）もあれば、新しい要件、ビジネスルール、ポリシーを導入する場合（「プレミアム製品を先に勧める」「社内文書を決して開示しない」「必ず最初に注文 ID を確認する」など）もあります。新しいビジネスルールはバグではありませんが、同じ規律を適用する必要があります。これは他の動作を気付かないうちに壊す可能性がある動作変更なので、同じループを通します。ユーザーは、変更が確実に定着し、他のものにリグレッションを起こさない状態を望んでいます。一度きりのパッチではなく、規律ある改善ループを進めてください。

必ず守るループ

EXPLORE → PLAN → IMPLEMENT → VERIFY の順で進めます。フェーズを飛ばしてはいけません。EXPLORE では何も編集しないでください。PLAN ではコードを書かないでください。VERIFY ではテストを変更しないでください。

ユーザーが素早い修正を求めた場合は、一度だけ押し返してください。「まずテストを書いて、修正が実際に機能することを確認させてください。」このスキルの価値の大部分は、この規律にあります。

このスキルが起動するリクエストは 2 種類あります。どちらにも同じテストファーストの規律を適用します。

• 失敗の修正 — ユーザーが不適切なトレースを共有するか、失敗の状況を説明する場合（「エージェントが幻覚を起こしています」「この回答は間違っています」「エージェントが何度も X をするので修正してください」）。
• 新しい動作／ビジネスルール／ポリシーの導入 — エージェントの応答方法を変える新しい要件（「X を先に勧める」「新しいビジネスルール：エージェントは X する」「必ず／決して X する」「デフォルトを変更する」など）。バグではありませんが、他の動作を気付かないうちに壊す可能性がある動作変更です。

フェーズ 1：EXPLORE — トレースが示す内容を理解する

目標：次の 3 つの問いに答える、文書化された診断を作成します。エージェントは何をしたか、何をすべきだったか、なぜ失敗したか。

このフェーズでは、エージェントのコードを編集してはいけません。

トレースに基づく診断がまだない場合は、まず debug-agent を実行してください。 そのトレース ID と調査結果を引き継ぎ、同じ作業を繰り返さずに続行してください。

トレース全体を読む

トレースを取得し、スパンごとに確認してください。トレースの構造については analyzing-mlflow-trace スキルを参照してください。

mlflow traces get --trace-id <ID> > /tmp/trace.json

重要な各スパンについて、次の内容を明らかにしてください。

• LLM スパン — システムプロンプト、メッセージ履歴全体、モデルが出力したテキストとツール呼び出し。
• ツールスパン — 呼び出されたツール、その引数、返された内容。
• 呼び出されなかったが、呼び出すべきだったツール。 多くの場合、バグの原因はここにあります。ドキュメントを取得できたのに、エージェントが記憶を頼りに使い方を回答した場合、問題はプロンプトより前の段階にあります。
• 検索スパン — 何を検索し、何が返され、何が除外されたか。

トレースに関するユーザーの口頭フィードバックを記録する

この回答が良くない理由について、ユーザーが今伝えた内容を、トレースに HUMAN 評価として記録してください。これにより、今後の反復作業にも残り、他のレビュー担当者も確認できます。

import mlflow
mlflow.log_feedback(
    trace_id="<the trace id>",
    name="user_review",
    value=False,                            # or a numeric score / category
    rationale="<paste the user's complaint verbatim>",
    source=mlflow.entities.AssessmentSource(source_type="HUMAN", source_id="<user>"),
)

トレースにすでにメモ（mlflow.notes 評価）がある場合は、診断にも含めてください。

診断を記述する

次の内容を明確に示してください。

1. エージェントがしたこと — 実際の応答を引用し、実際に呼び出したツールを列挙します。
2. エージェントがすべきだったこと — ユーザーの期待を具体的に言い換えます。
3. 根本原因の仮説 — このループ全体で最も重要な文です。次から選んでください。
   • 能力／ツールの不足（エージェントには正しい動作を行う能力が文字どおりありません）
   • データソース／検索の不足（エージェントが事実を持っていません）
   • ルーティング／計画の誤り（エージェントはツールを持っていますが、呼び出しませんでした）
   • 指示の誤り（プロンプトが別の動作を指示していました）
   • モデルの知識不足（学習する手段がない機能についての知識がありません）
   • 報酬ハッキング（プロンプトが誤ったことに報酬を与えています）

カテゴリは PLAN での修正レイヤーを決めるため、重要です。具体的にしてください。「プロンプトが悪い」は診断ではありません。「エージェントは FetchDocs を利用できますが、使い方に関する質問で呼び出していません」が診断です。

コーディングを始めたい衝動を抑えましょう

今すぐシステムプロンプトの編集に取りかかりたくなるでしょう。やめてください。PLAN に進みます。

フェーズ 2：PLAN — まずテストを書く

目標：現在のエージェントが適切な理由で失敗する、実行可能なテストスイートと、修正のための計画書を用意します。

テストを書く前に、変更の SCOPE を確認する

「エージェントに X をさせる」というリクエストには、開発者が通常明示しないスコープに関する問いが必ず伴います。つまり、エージェントはあらゆるケースで X を行うべきなのか、それとも特定のケースでのみ行うべきなのか、という問いです。全体に適用されると決めつけてはいけません。答えによって作成するテストが決まるため、まず開発者に確認してください。スコープの推測を誤ると、開発者が望んだ動作に積極的に反する回帰防止テストが組み込まれてしまいます。

テストを書く前に、必ず次のことを行います。

1. 全体に適用するのか、条件付きなのかを確認します。 X はどこでも新しいデフォルトとなるのか、それとも条件 C の場合にのみ適用するのかを確認します。AskUserQuestion を使用します（そのツールがない場合は、通常の追加質問をします。サブエージェントの場合は呼び出し元に質問を伝え、返答を待ちます。一方的に決めてはいけません）。「X を優先する」「まず X を提示する」「常に X を行う」といったリクエストの多くは、確認してみると条件付きであることがわかります。通常、X が誤った答えとなる入力が存在します。
2. 条件付きの場合、否定テストを必ず追加します。 X を行うべきではない入力も含めます。たとえば、X を適用すると明らかに誤りとなるケースです（リクエストに X では満たせない制約がある場合や、別の選択肢が明らかに正しい場合など）。条件付きのルールを肯定ケースだけでテストしても、エージェントが X を「実行できる」ことしか証明できません。実行すべきでないときに「止められる」ことは証明できないため、適用しすぎる変更がそのままテストを通過してしまいます。
3. 境界にある入力を列挙し、それぞれについて確認します。 どちらの条件に分類しても妥当といえる入力を挙げ、テストに組み込む前に開発者に分類してもらいます。（「ユーザーが不満を感じている場合にのみ、人間にエスカレーションする」というルールでは、「もう 3 回も聞いています」は不満でしょうか。それとも中立的な事実でしょうか。）

変更が本当に全体に適用され、条件もない場合（すべての入力に適用される純粋な形式・内容のルール）に限り、これらの手順を省略できます。判断に迷った場合は、開発者が最初に指摘した入力も判断材料になります。その入力のテストが、開発者の望む方向と一致していることを確認してください。

ユーザーの期待をテストとして定義する

各ケースを通常の pytest テストとして記述し、@mlflow.test を付けて、mlflow.genai.evaluate(data=[...], predict_fn=..., scorers=[...]) でスコアラーを実行し、assert result.passed, result.reason で結果を検証します。決定論的なスコアラーとジャッジベースのスコアラーを組み合わせてください。（@mlflow.test は何もしないデコレーターではありません。MLflow pytest プラグインが必要で、プラグインが有効になっていない場合はテスト実行時にエラーが発生します。ルートの conftest.py に pytest_plugins = ["mlflow.pytest.plugin"] を追加して一度だけ有効にするか、-p mlflow.pytest.plugin を指定して pytest を実行してください。このプラグインは、マークされたテスト用に MLflow の実行をセットアップし、トレースを有効にします。これにより、各ケースのトレースが 1 つの回帰テスト実行にまとめられます。evaluate はスコアラーを実行して EvaluationResult を返します。result.passed／result.reason には、失敗した理由とともに、単一の合否が示されます。）テストは、テスト対象のモジュールまたは振る舞いにちなんだ、安定した名前のファイルに保存し、プロジェクト既存のテスト配置規約に従ってください。**課題やシナリオごとにファイルを作成してはいけません。**新しいファイルを作成する前に、そのモジュールや領域を対象とするテストスイートがすでにあるか確認し、ある場合はそこにアサーションを追加してください。その領域がまだテストされていない場合に限り、新しいファイルを作成します。

**ジャッジモデルは記憶ではなく、プロジェクトの設定を基に選んでください。**次の順序で確認します。（1）プロジェクトですでに評価用に固定されているモデル。MLFLOW_GENAI_JUDGE_DEFAULT_MODEL 環境変数、設定ファイル、既存のスコアラーやテストで使用されているジャッジを確認します。（2）該当するモデルがなければ、使用するモデルを provider:/model 形式（例：openai:/gpt-4o、anthropic:/claude-sonnet-4-6、またはゲートウェイルート）でユーザーに確認します。プロジェクトで解決できないモデル ID を推測したり、ハードコードしたりしないでください。MLFLOW_GENAI_JUDGE_DEFAULT_MODEL を一度設定すれば、ジャッジスコアラーに model= 引数を指定する必要はありません。すべて同じジャッジを使用してください。（意図的に上書きする場合に限り、スコアラーごとに model= を渡します。）すべてのスコアラーが決定論的であれば、ジャッジの設定は不要です。

import mlflow
from mlflow.genai.scorers import RegexMatch, Guidelines, Safety, scorer

# Judge model comes from MLFLOW_GENAI_JUDGE_DEFAULT_MODEL — no model= needed below.

# There is no built-in "excludes" scorer — write a small custom @scorer for must-NOT-contain checks.
@scorer
def excludes_cli_commands(outputs):
    forbidden = ["mlflow runs create", "log-artifact"]
    return not any(f in str(outputs) for f in forbidden)

@mlflow.test
def test_should_lead_with_ui_path_when_on_experiments_page():
    result = mlflow.genai.evaluate(
        # inputs keys are passed to predict_fn as kwargs; predict_fn exercises the
        # real, instrumented agent path (see "Exercise the real instrumented code path").
        data=[{"inputs": {"prompt": "How do I organize my experiments?",
                          "context": {"currentPage": "Experiments"}}}],
        predict_fn=my_agent.invoke,
        scorers=[
            RegexMatch(pattern=r"workspaces", case_insensitive=True),  # deterministic
            excludes_cli_commands,                                     # deterministic (custom)
            RegexMatch(pattern=r"mlflow\.org/docs/.+/workspaces"),     # deterministic
            Guidelines(
                guidelines="The agent should lead with the UI path since the user is on the relevant page.",
            ),                                                         # semantic (uses default judge)
        ],
    )
    assert result.passed, result.reason

コピー＆ペーストして使える完全なテンプレート — conftest.py／pyproject.toml でのプラグイン設定、ペアにしたガードテスト、意味のある ID を付けたパラメーター化ケース、pytest-xdist を使った並列実行については、references/regression-test-suite.md を参照してください。

ガイドラインの文言は規範的な「〜すべき」「〜しなければならない」形式で記述する

ガイドライン文字列はトレースに保存され、回帰テスト UI ではアサーションのラベルとして表示されます。それぞれのガイドラインは、要件として読めるよう、規範的な「〜すべき」または「〜しなければならない」という文で始めてください。ジャッジの判断を助けるため、要件の後に PASS／FAIL の基準を追加してもかまいませんが、冒頭の文では必ずルールを示してください。

• 推奨： "エージェントは、最初にレンガの推奨を 1 つだけ提示するべきです。PASS：冒頭で 1 つのファミリーを示す。FAIL：選択せずに複数を列挙する。"
• 推奨： "回答には注文 ID を含めなければなりません。"
• 非推奨： "エージェントは、最初に 1 つの推奨を提示します。PASS：冒頭でレンガのファミリーを 1 つだけ示す。FAIL：複数を列挙する、または選択を拒否する。" — 要件ではなく説明から始まっています。

実際に計測されるコードパスをテストする

テストでは、エージェントを本番と同じコードパスで呼び出す必要があります。これにより、本番のトレース有効化処理がテスト中に実際に実行されます。同じ autolog()（または @mlflow.trace によるラップ）を使い、ネストされたトレースも同じ形にします。テストで本番とは異なる方法で生成したトレースでは、誤ったものを検証することになり、VERIFY フェーズの「トレースを目視で確認する」手順は意味をなさなくなります。

• テストでトレース設定を再宣言しないでください。「トレースを表示させる」ために、テストファイルへ mlflow.<lib>.autolog()（または set_tracking_uri／スパンデコレーター）を追加してはいけません。そうすると計測処理が分岐し、テストは本番に存在しないパスをトレースするようになります。両者は知らないうちに食い違い、まさに防ごうとしている問題が起きます。
• テスト中に有効化処理が実行されないなら、テストで取り繕わず、アプリ側を修正してください。 つまり、トレース処理がテストで通らないエントリーポイント（例：server.py、FastAPI の lifespan、main()）に置かれているということです。有効化処理を、エントリーポイントとテストの両方が共有するコード、つまりエージェントの構築・呼び出しパス（build_agent()、エージェントの __init__、@mlflow.trace でラップする関数）へ移します。そうすれば、エージェントの構築と実行によって、どの環境でもトレースが有効になります。エントリーポイント／テストハーネスに残すのは、デプロイ時のルーティング（set_tracking_uri、set_experiment）だけにしてください。これは保存先の設定であり、計測処理ではありません。
• 注意すべき症状： 1 回のユーザーターンが、ネストされたエージェントトレース 1 件ではなく、複数のつながりのないトップレベルトレース（例：LLM 呼び出しごとのフラットな Completions トレース）として現れます。これはたいてい、テストが本番で頼りにしているエージェントフレームワークの autolog ではなく、生のモデルループを実行したことを意味します。本来の計測処理が実行されなかったため、グループ化する親トレースがありません。

保証する動作がわかるテスト名を付ける

関数名は契約そのものです。トレース上では mlflow.test.name タグとして、また回帰テストの実行結果やスコアラーごとのサマリーでは行ラベルとして表示されるため、曖昧な名前では UI 上の行も曖昧になります。名前には、バグや修正内容、生の苦情ではなく、保証する動作を記してください。

BDD の Given–When–Then（Dan North）に従い、期待する動作と条件を Should/When 形式で表します。この形式では、保証する内容を先に記します。

test_should_<期待する動作>_when_<条件> — 動作が無条件の場合（グローバルな形式／内容のルール）は、_when_… 節を省略します。

• ✅ test_should_not_push_brickfather_when_customer_states_a_color
• ✅ test_should_recommend_brickfather_when_customer_is_undecided
• ✅ test_should_not_leak_internal_sops_when_asked_for_policy_docs
• ✅ test_should_lead_with_one_recommendation (無条件のため when なし)
• ❌ test_brickfather — 推すのか、それとも控えるのかがわかりません。
• ❌ test_fix_verbose_bug／test_issue_1234 — 契約ではなく、バグ／チケットの名前です。
• ❌ test_case_3／test_agent_response — 何も伝えておらず、UI ラベルとして役に立ちません。

ルール：

• should_<期待する動作> から始め、肯定的な表現にする — 成功時には名前が真となり、失敗時には破られた保証内容が名前に表れます。
• 対になるガードテストでは、期待値を反転させて同じ骨組みを使う — 境界が明確になります。例：test_should_recommend_brickfather_when_customer_is_undecided と test_should_not_push_brickfather_when_customer_states_a_color。
• when_ 節は Given＋When を表す — 動作を切り替える具体的な属性（when_customer_states_a_color）を記し、生のプローブ文は記しません。
• 修正内容や一時的な詳細を含めない — test_after_adding_filter のような名前、日付、チケット ID、モデル名は避けます。名前は今日の実装より長く使われるものです。
• パラメーター化したケースには意味のある ID を付ける（mlflow.test.case_id として使われます）：@pytest.mark.parametrize("probe", [...], ids=["red_wall", "hurricane_rated", "cheapest"]) — デフォルトの 0/1/2 は使わないでください。

(参考文献：Dan North、「Introducing BDD」（2006 年）— Given-When-Then、Roy Osherove、『The Art of Unit Testing』— UnitOfWork_StateUnderTest_ExpectedBehavior。)

スコアラー選択のルール

• まずは決定論的な方法を使います。 表面的な懸念には、RegexMatch（部分文字列／形式／URL パターン／コードブロック。単純な「含まれる」チェックでは case_insensitive=True を使用します）や、小規模なカスタム @scorer 関数（例：含まれていてはいけない文字列のチェック、または正解データに対する Equivalence／Correctness）を使います。LLM の呼び出しはゼロで、再現性があります。（Contains／Excludes／Matches／Equals スコアラーはありません。これらのケースは RegexMatch とカスタム @scorer で対応できます。）
• どこでも同じジャッジモデルを使います。 MLFLOW_GENAI_JUDGE_DEFAULT_MODEL（上記で解決済み）で一度設定し、すべての Guidelines スコアラーで共有します。スコアラーごとに異なるモデルやハードコードしたモデルを使ってはいけません。
• Guidelines は意味的な評価が必要な場合に限ります。 「UI の操作手順から始める」「まず確認の質問を1つだけする」「主な推奨事項は Y ではなく X」などの評価には、LLM ジャッジが必要です。Guidelines には入力と出力の両方が必要なので、各 data 行に inputs フィールドと、outputs フィールドまたは出力を生成する predict_fn があることを確認してください。evaluate はその両方をジャッジに渡します。
• 修正方法ではなく、意図に基づいてスコアラーを選びます。 ユーザーから報告された失敗の性質に基づいてスコアラーを選び、たまたまどのように修正したかに基づいて選んではいけません。データのフィルタリング、ツールの追加、設定変更など、きれいな構造的／決定論的な修正を行うと、決定論的なテストだけを選びたくなります。「問題は解消したのだから、部分文字列チェックで十分だ」と考えがちです。しかし、それには抗ってください。決定論的スコアラーが検証するのは、確認できた特定の事例です。表現、入力、データが変わると、気づかないままテストを通過してしまいます。問題がある種の振る舞い（意図、トーン、情報開示、推論など、意味に関わるもの）についてなら、修正がどれほど強力でも、その振る舞いの種類を評価する LLM ジャッジが必要です。テストは意図を恒久的に記録するもので、修正は今日の実装にすぎません。
• 修正したレイヤーでアサーションを行い、その上にジャッジも残します。 修正を支えるアサーションは、修正を行った場所に置きます。ツール／検索／データの修正では、トレースのツールスパンに対する決定論的なカスタム @scorer（スコアラーは trace を受け取ります。trace.search_spans("<tool>") を使い、拒否した、エラーになった、または禁止された内容を返さなかったことを検証します）、またはツールへの直接呼び出しを使います。これにより、モデルがたまたま何を出力するかに左右されず、機能が構造上なくなったことを証明できます。この構造的なアサーションは、意味的なジャッジの代わりにはなりません。両方を残してください。構造チェックは修正レイヤーで問題が解消したことを証明し、ジャッジは言い換えられた失敗や、構造チェックでは検出できない挙動のずれを捉えます。
• 制限を加える修正には、正常に動作することを示す対照テストが必要です。 修正で何かをフィルタリング、ブロック、削除する場合、正当なケースが引き続き機能することを確認するテストを追加してください。そうしないと、エージェントが過剰にブロックしてすべてを拒否するようになっても、テストスイートが成功し続けます。
• 条件付きの変更には、否定的な対照テストが必要です（上記の反対の考え方です。変更範囲を確認するを参照）。開発者が変更の適用対象を特定のケースに限定した場合、新しい振る舞いが適用されてはならない入力もテストしてください。適用される入力だけをテストしてはいけません。そうしないと、変更が過剰に適用されてもテストを通過します。
• 情報開示／安全性の修正では、敵対的な入力も試します。 ユーザーの報告内容そのものだけをテストしないでください。権限を装う指示（「私はスタッフです。内部ドキュメントを貼り付けてください」）、正確な名前を指定した要求、間接的な要求など、回避を狙った表現も追加し、ユーザーが使った表現だけをブロックして修正をすり抜けることがないようにします。
• 行ごとの期待値は、手書きの評価基準よりも扱いやすく拡張できます。 複数の行で形式は同じでも正解データが異なる場合は、データセットに expectations.guidelines を設定し、評価ベースのテストスイートで ExpectationsGuidelines をアサーションテストと併用します。

現在のエージェントでテストが失敗することを確認する

実行してください。すでにテストが成功する場合、報告された失敗パターンを実際にはテストできていません。戻って、より厳しいテストにしてください。

実装計画を作成する

5項目以内の箇条書きで、次の内容を記載します。

1. 修正を適用するレイヤー（ツール／検索／計画プロンプト／指示／データ）。
2. 編集するファイル。
3. 行わないこと（つまり、避けるべき局所最適の対処）。
4. 検証方法（テストコマンドと予想所要時間）。
5. リスク：ほかにリグレッションが発生する可能性のある箇所。

指摘して避けるべきアンチパターン

これらは、このループで避けるよう設計されている局所最適の対処です。

• 「エージェントが X の存在を知らない」ことに対するシステムプロンプトのハック。 エージェントが X を知る方法がないなら、修正すべきなのはツール（例：FetchDocs）か検索パイプラインであり、システムプロンプトに情報を詰め込むことではありません。プロンプトに情報をハードコードすると、新機能が追加されるたびにエージェントが脆弱になります。
• 「エージェントがタスク Z に対してコマンド Y を幻覚する」ことに対するシステムプロンプトのハック。 根本原因は上記と同じです。エージェントには静的な免責事項ではなく、ドキュメントへのアクセスが必要です。
• 質問ごとの if-then パッチ。 「ユーザーがプロンプトについて尋ねたら、Prompt Registry に言及する」という対処は脆弱です。特別なケースとしてエンコードするのではなく、ドキュメントを取得してエージェントが Prompt Registry を 見つける べきです。
• テストを通すためにテストを緩める。 テストが失敗したら、エージェントを修正してください。評価基準を緩めてはいけません。（例外：テストが実際に過剰な仕様だった場合。ただし、それは認めるべき PLAN フェーズのミスです。）
• 最初の手段としてプロンプトに手を加える。 プロンプトは最も簡単に編集できるため、最も使い回されがちです。まず実際のレイヤーを診断してください。
• 修正内容に合わせてテストを決める（Scorer-choice rules →「Pick scorers from the intent, not from the fix」を参照）。修正が優れているからといって、意味判定器やペアケースを削除してよいわけではありません。
• テスト内でトレーシングを再宣言する（Exercise the real instrumented code path を参照）。テストファイルが autolog() を呼び出すことでしか現れないトレースを検証しても、本番で使われている計測方法の検証にはなりません。

徹底して適用すべきルール：同じ種類の失敗のうち、1つの事例だけを修正するためのハードコードは絶対に行わないこと。 苦情がある 種類の 振る舞いに関するものなら、ユーザーがたまたま示した1つの例だけでなく、その種類全体を引き起こす機能を修正してください。

フェーズ 3：実装 — 診断したレイヤーで最小限の変更を行う

目標：エージェントが新しいテストに合格し、できれば正しい理由で合格することです。

変更を加える

PLAN で特定したレイヤーに変更を実装します。例：

• ツールの不足 → エージェントのツールスキーマと実装にツールを追加し、ツールごとのスパントレースも追加します。ツール単体を個別にユニットテストします。
• 検索の不足 → 検索ソースを追加または拡張します。実際に呼び出されることを確認してください（トレースで検証します）。
• ルーティングの誤り → どのツールをいつ使うかをエージェントに指示する、最小限のプロンプト編集を行います。発動条件を具体的に記述します。
• 指示の誤り → 最小限のプロンプト編集を行います。変更する動作を正確に明記します。
• モデルの知識不足 → プロンプトのパッチではなく、ツールを通じてデータにアクセスできるようにします。

最小限にとどめる

差分は小さく、対象を絞ったものにしてください。1つのテストを通すためにシステムプロンプトの半分を書き換えることになったら、それは局所最適を追いかけています。PLAN に戻ってください。

フェーズ 4：検証 — 修正を確認し、リグレッションをチェックする

目標：以前合格していたテストも含め、すべてのテストが成功することです。

テストランナーとプラグインが設定されていることを確認する

テストスイートは、pytest と MLflow pytest プラグイン（mlflow.pytest.plugin）を有効にして実行します。プラグインが有効でない場合、@mlflow.test はテスト実行時にエラーになります。ルートの conftest.py で一度だけ有効にします。

# conftest.py
pytest_plugins = ["mlflow.pytest.plugin"]

…または、コマンドラインで -p mlflow.pytest.plugin を渡します。環境に pytest があるとは限りません。見つからない場合は、自分でインストールして続行してください。作業を止めてユーザーに尋ねてはいけません（ここでの ImportError は依存関係の不足であり、テストの失敗ではありません）。

python -c "import pytest" 2>/dev/null || uv pip install pytest

（プロジェクトで使われているインストーラーを使用してください。ここでは uv pip install を使い、uv がない場合は pip install にフォールバックします。）

アサーションスイート全体を実行する

# point at the test file you wrote — wherever the project's layout puts it
MLFLOW_TRACKING_URI=<server> pytest <path/to/test_file.py> -p mlflow.pytest.plugin -v

# judge calls are I/O-bound — run in parallel with pytest-xdist once the suite grows
MLFLOW_TRACKING_URI=<server> pytest <path/to/tests/> -p mlflow.pytest.plugin -n auto

判定モデルが必要なテストでは、実行前に関連する環境変数を設定してください。判定モデル（PLAN で解決される MLFLOW_GENAI_JUDGE_DEFAULT_MODEL）と、必要な認証情報（OPENAI_API_KEY、ゲートウェイのベース URL など）です。pytest-xdist のワーカー統合に使う conftest.py のスニペットについては、references/regression-test-suite.md を参照してください。

まだ失敗するテストがある場合は、その失敗の原因を調べる

追加したばかりのテストがまだ失敗する場合は、そのテストについてEXPLOREに戻ってください。新しいトレースを確認します。エージェントは新しいツールを呼び出しましたか？ ツールは期待どおりの結果を返しましたか？ すぐに修正を加えるのではなく、まず原因を特定してください。

リグレッションを確認する

以前は合格していたテストが失敗する場合、それは重要な兆候です。修正によって別の箇所に影響が及んでいます。「リグレッションを修正」する前に調査してください。変更を取り消して別の層で試すのが正解の場合もあります。

新しいトレースを少なくとも1つ目視で確認する

テストに合格しても、良い回答ができているとは限りません。修正した質問に対する最新のトレースを取得し、エージェントの応答を読んでください。ユーザーが望んでいた内容に本当に合っていますか？ それとも、評価基準を満たしただけですか？ 後者の場合、評価基準が緩すぎます。PLANに戻ってください。

完了するまでループする

複数の問題が報告された場合は、問題ごとにループを繰り返してください。一度に3つのことを修正しようとしないでください。各反復では、原因の診断を1つ行い、対象を絞った変更を1つ加えます。

終了するタイミング

• すべてのテストに合格している。
• ユーザーが新しいトレースを少なくとも1つ目視し、エージェントが期待どおりに動作するようになったことを確認している。
• 既存のテストにリグレッションがない。

同じテストで3回以上反復しても解決に至らない場合は、エスカレーションすべき兆候です。診断が間違っていた可能性が高いことをユーザーに伝え、別の根本原因の仮説を提案してください。

参照する MLflow API

• mlflow.log_feedback(...) — ユーザーの口頭でのフィードバックを、トレース上の HUMAN 評価として保存します
• mlflow traces get --trace-id <id> — スパンを調査するため、トレース全体を取得します
• @mlflow.test マーカー — mlflow.pytest.plugin pytest プラグインが必要です（pytest_plugins = ["mlflow.pytest.plugin"] または -p mlflow.pytest.plugin で有効化します）。回帰テストケース用に MLflow の実行とトレースを設定します
• mlflow.genai.evaluate(data=..., predict_fn=..., scorers=[...]) → EvaluationResult。result.passed / result.reason でアサートします — アサーション API です
• mlflow.genai.scorers.{RegexMatch, Guidelines, Safety, ExpectationsGuidelines, Correctness, Equivalence, RelevanceToQuery, ...} と、カスタムの決定論的なチェックに使う @scorer デコレーター — スコアラーを構成する要素です（Contains／Excludes／Matches／Equals はありません）
• mlflow.genai.datasets.get_dataset(...).merge_records([...]) — ExpectationsGuidelines 用に、行ごとの expectations.guidelines を設定します

関連スキル

• analyzing-mlflow-trace — EXPLORE フェーズでトレースの構造を確認する際に使用します。
• analyzing-mlflow-session — 問題が複数ターンにわたる会話にまたがる場合に使用します。
• instrumenting-with-mlflow-tracing — エージェントがまだトレースされていない場合は、まずこれを実行してください。トレースなしではEXPLOREできません。
• agent-evaluation — 個別のアサーションテストと併せて、データセット規模の評価ワークフローを実施する際に使用します。
• references/context-optimization.md — トレースで入力トークンの過剰使用、コンテキスト構築の遅さ、またはコンテキストウィンドウのエラーが確認された場合に使用します。変更前後の品質とコストを測定してください。