AI DEVELOPMENT

DeepEvalでAIエージェントの失敗を
3つに分けて回帰テストする

公開日 2026.08.02 ／仕様確認日 2026.08.02 ／執筆・編集：テクヒカ編集部

AIエージェントのテストで厄介なのは、返ってきた文章だけを見ると成功に見えることです。在庫確認で別商品のSKUを検索したのに、もっともらしい個数を返す。空き時間を調べただけなのに、「予約しました」と答える。文章だけの採点では、どちらも見逃しかねません。

DeepEvalでは、最終回答、タスクの達成結果、ツール呼び出しを分けて評価できます。本稿はDeepEvalの機能紹介ではなく、AIエージェントの回帰テストをどの順番で組むかに焦点を絞りました。LLM評価の指標全体やRAG評価から確認したい場合は、DeepEvalの評価メトリクス選定ガイドが入口になります。

回答・完了・ツール使用を一つの点数にしない

AIエージェントは検索、計算、更新、送信など複数の操作を途中に挟みます。最終結果が同じでも、正しい経路を通ったかで安全性と再現性は変わります。

見かけの結果	内部で起きた失敗	必要な評価
正しい金額を回答	古い料金表を検索し、偶然同額だった	ツール、引数、参照元
予約完了と回答	空き照会だけで予約APIを呼んでいない	タスク完了
自然な調査結果	同じ検索を何度も繰り返した	ステップ効率
期待形式で出力	禁止された外部ツールを使用	ツール選択と順序

そこで最初の品質ゲートを3つに分けます。回答は必須項目や説明品質、タスク完了は依頼した操作のOutcome、ツール使用は選択・引数・出力・順序を判定します。プロンプトやモデル変更でテストが落ちたとき、どの層が壊れたかをログから追える分け方です。

6つのAgentic Metricsは、失敗位置で選ぶ

2026年8月2日時点の公式Metrics Introductionでは、主なAgentic MetricsとしてTask Completion、Argument Correctness、Tool Correctness、Step Efficiency、Plan Adherence、Plan Qualityの6種類が挙げられています。50種類以上ある指標を横断するより、エージェントのどこが壊れたかで3層に分けると選びやすくなります。

層	確認したいこと	主な指標
推論	妥当な計画を立て、その計画から逸脱しなかったか	Plan Quality、Plan Adherence
アクション	正しいツールと引数を選び、必要な順序で呼んだか	Tool Correctness、Argument Correctness
実行	依頼を完了し、無駄な手順を増やさなかったか	Task Completion、Step Efficiency

最初はTask CompletionとTool Correctnessを優先します。前者は依頼の完了、後者は道具の選択を見るため、結果と経路を分けられます。Plan QualityやStep Efficiencyは、正常系とトレースが安定してから追加するほうが判断しやすいです。

少数の失敗ケースをtraceとpytestへ落とす

DeepEvalのAgentic Metricsは、ライブラリを入れただけでは機能しません。Task Completionなどは実行全体のtraceを読み、そこからTaskとOutcomeを抽出します。手動計装では@observeで処理を囲み、必要に応じてupdate_current_traceやupdate_current_spanへ入出力とツール呼び出しを渡します。LangChainなどには公式のフレームワーク連携があります。

pip install -U deepeval

# テスト実行
deepeval test run test_agent.py

在庫確認エージェントなら、正常ケース、余計なツールを呼ぶケース、誤った引数を渡すケースを別々のテストにします。次はツール名と入力引数を完全一致で判定する最小構成です。

from deepeval import assert_test
from deepeval.metrics import ToolCorrectnessMetric
from deepeval.test_case import LLMTestCase, ToolCall, ToolCallParams


def test_inventory_agent_uses_expected_tool():
    case = LLMTestCase(
        input="商品SKU-102の在庫数を確認して",
        actual_output="在庫は12個です。",
        tools_called=[
            ToolCall(name="inventory_lookup", input_parameters={"sku": "SKU-102"})
        ],
        expected_tools=[
            ToolCall(name="inventory_lookup", input_parameters={"sku": "SKU-102"})
        ],
    )

    metric = ToolCorrectnessMetric(
        threshold=1.0,
        evaluation_params=[ToolCallParams.INPUT_PARAMETERS],
        should_exact_match=True,
    )
    assert_test(case, [metric])

should_exact_match=Trueは呼び出しリストを完全一致にし、evaluation_paramsへINPUT_PARAMETERSを加えると引数も照合対象になります。正常系と失敗系を混ぜず、止めたい事故ごとに期待するツールと引数を固定します。

Task Completionは「返事」ではなくOutcomeを見る

Task Completionは実行全体のtraceからTaskとOutcomeを抽出し、両者がどれだけ合っているかをLLM-as-a-Judgeで判定します。タスクは明示もできますが、指定しなければtraceから推定されます。予約、更新、送信、登録のように、自然な説明文を返しただけでは完了にならない処理に向く指標です。

たとえば「来週火曜の15時に会議を登録して」という依頼なら、カレンダーの空き確認だけでは未完了です。イベント作成ツールが成功し、対象日時と参加者が結果へ反映されて初めてOutcomeがTaskと一致します。ここでトレースがないと、最終文に「登録しました」と書かれたことしか見えません。

業務上のゴールが曖昧ならタスクを明示します。「候補を探す」と「予約を確定する」、「下書きを作る」と「送信する」は別タスクです。

Tool Correctnessは名前・引数・順序を分けて厳しくする

Tool Correctnessの基本スコアは、正しく使われたツール数を呼び出したツール総数で割って計算します。tools_calledとexpected_toolsの照合は基本的に決定的で、初期設定ではツール名が中心です。入力引数、出力、呼び出し順序、完全一致まで段階的に厳しくできます。available_toolsを渡した場合だけ、候補の中で最適なツールだったかをLLMが判定し、決定的スコアとの低いほうが最終スコアになります。

確認範囲	向いているケース	注意点
ツール名	検索と更新を取り違えていないか	誤ったIDでも合格し得る
入力引数	顧客ID、SKU、日時が重要な処理	正規化ルールを決める
出力	ツールの戻り値を正しく受けたか	時刻や乱数を固定しにくい
順序	確認後に更新する承認フロー	並列可能な処理まで縛らない
available_tools	複数の検索・計算手段がある	LLM判定が加わり非決定的になる

よくある失敗は、ツール名だけを一致させて安心することです。在庫照会ツールを呼んでいても、SKUが別商品なら業務上は事故です。反対に、日付表記の揺れまで完全一致にすると、意味は同じなのにテストが落ち続けます。更新系や送信系は厳格に、読み取り系は許容範囲を設けるなど、処理の危険度で基準を変えます。

G-Evalを足すのは、主観評価が必要なときだけ

G-Evalは、正確性、説明の分かりやすさ、口調、要約品質のように、決定的なルールへ落としにくい評価へ向きます。Task CompletionやTool Correctnessの代わりではなく、業務固有の品質を補う指標です。LLM-as-a-Judgeの設計そのものはLLM-as-a-Judgeの評価設計ガイドで詳しく整理しています。

criteriaだけを渡すと、評価時に手順が生成されるため、同じ出力でもスコアが揺れやすくなります。運用では一度criteriaから評価手順を作り、その内容をレビューしたうえでevaluation_stepsとして固定します。同一ケースを複数回実行し、合否が反転する境界へCIのしきい値を置かないことも重要です。

「禁止事項が一つでもあれば即失格」「必須項目がそろった場合だけ説明品質を採点」のように条件分岐を明示できるなら、DAGMetricのほうが管理しやすい場合があります。DAGも判断ノードではLLMを使えますが、到達した分岐へ固定スコアを割り当てられるため、G-Evalより採点経路を説明しやすくなります。

CIでは重大な失敗を独立gateにする

公式のMetrics Introductionは、指標を合計5個以内に抑え、システム共通指標を2〜3個、独自指標を1〜2個にする目安を示しています。エージェントの初期導入なら、Task CompletionとTool Correctnessを必須gateにし、必要な場合だけG-Evalを補助指標として足す構成が扱いやすいです。

平均点だけで合否を決めると、重大な未完了を高い文章品質で相殺してしまいます。たとえばTask Completionが不合格なら全体を失敗、Tool Correctnessは更新系だけ厳格、G-Evalは推移監視というように役割を分けます。API障害やレート制限で評価自体が実行できなかったケースも、品質低下と別の終了コードやログへ分離します。

誤更新、誤送信、権限越境などはPull Requestで実行し、長い会話や主観評価は夜間バッチへ分けます。評価モデル、費用、処理時間、変更日を記録すると回帰原因を追いやすくなります。

DeepEvalだけでは、本番監視の全体像は完成しない

DeepEvalは評価と回帰テストを担い、LangSmith、Arize Phoenix、Langfuseなどでトレースを集める構成が整理しやすいです。

確認したいこと	中心になる役割	候補
変更で品質が落ちたか	評価・回帰テスト	DeepEval
LangChain実行を追いたい	トレース、データセット、評価運用	LangSmith
OpenTelemetry系で観測したい	トレース解析、RAG・エージェント観測	Arize Phoenix
セルフホストも含めて履歴管理したい	トレース、プロンプト、評価管理	Langfuse

関連する実装判断は、LangSmithの実務ガイド、Arize Phoenixの導入ガイド、AIエージェント観測性ツールの比較、Agentic RAGの設計ガイドで整理しています。

DeepEvalが合うチーム、別の方法を選ぶチーム

DeepEvalが向いているケース

Pythonとpytestを中心に開発し、RAGやAIエージェントの重要ケースをコードで管理したいチームに向きます。ツール呼び出しやトレースをテスト対象へ含め、プロンプトやモデル変更による回帰をCIで検出したい場合にも相性があります。業務固有の採点基準をG-EvalやDAGMetricで作りたい開発者にも選択肢になります。

DeepEvalを急いで入れないほうがよいケース

ノーコードだけで評価を完結したい、LLM判定を一切使わず完全に固定ルールだけで採点したい、評価モデルのAPI費用や揺れを許容できない場合は向きません。また、欲しいものが本番トレースのダッシュボードだけなら、先に観測基盤を整えたほうが目的へ近づきます。テストデータの責任者や失敗時の対応ルールが決まっていない状態では、導入してもスコアを見るだけで終わります。

回帰テスト設計で迷いやすい4点

Task CompletionとTool Correctnessは両方必要ですか？

ツールを使うエージェントなら、原則として分けて確認したほうが原因を特定しやすくなります。Task Completionだけでは偶然の成功経路を見逃し、Tool Correctnessだけでは正しいツールを呼んだ後に処理が未完了でも合格し得ます。

Tool Correctnessで引数まで完全一致にすべきですか？

更新、送信、決済など誤操作の影響が大きい処理では厳格化する価値があります。一方、検索語や日付表記に許容可能な揺れがある処理まで完全一致にすると、意味上は正しい実行を落としやすいため、危険度に応じて設定を分けます。

G-Evalのスコアが毎回変わる場合、CIでどう扱いますか？

evaluation_stepsとrubricを固定し、同じケースを複数回走らせて変動幅を確認します。合否が反転する境界を避け、G-Evalを補助指標や推移監視として使い、重大な品質条件はTask Completion、Tool Correctness、DAGMetric、通常のassertなどへ寄せます。

LangChainのエージェントもDeepEvalでテストできますか？

できます。公式連携ではCallbackHandlerを実行時設定へ渡し、エージェント、モデル、ツール、Retrieverの呼び出しをトレースできます。deepeval test runはDeepEvalのpytestプラグインを有効にしてテストを実行します。

まず3つのgateを分け、落ちた理由を残す

回答が妥当でも、依頼が未完了なら失敗です。依頼を終えても、禁止したツールや誤った引数を使っていれば、同じく止めるべきです。回答、タスク完了、ツール使用を別々に判定して初めて、回帰の場所が見えます。

最初はTask CompletionとTool Correctnessを重要ケースへ入れ、失敗理由をCIに残します。説明品質や業務固有の主観基準が必要になった段階でG-Evalを足し、評価手順を固定します。指標の数よりも、失敗時に本当にリリースを止められる基準を運用できるかが重要です。

公式仕様は2026年8月2日に、Metrics Introduction、Task Completion、Tool Correctness、G-Eval、LLM Tracing、Unit Testing in CI/CDで確認しました。

← JOURNALに戻る｜ AI一覧を見る →

スポンサーリンクスポンサーリンク