AIエージェントはどうテストする？
Eval・ログ・再現性・失敗分析の基本

AIエージェントを作って、期待した答えが返ってきた。

それだけで、

「このAgentは正しく動いている」

と言えるでしょうか。

Agentは、通常のソフトウェアより少し評価が難しくなります。

なぜなら、

• どのToolを使うか
• どの順番で処理するか
• 何回試すか
• 途中で方針を変えるか
• どの情報をContextへ入れるか

を、実行ごとに変える可能性があるからです。

同じ質問を与えても、

毎回まったく同じ経路を通るとは限りません。

そこで重要になるのが、

Eval（Evaluation）

です。

① Outcome
最終的に仕事を完了したか

② Behavior
適切なTool・手順・境界を守ったか

③ Trace / Log
途中で何が起きたか追跡できるか

④ Regression
変更後も以前できた仕事を維持できるか

1. なぜAgentは普通のテストだけでは足りないのか

通常の関数なら、

input
↓
function
↓
output

という形で、

入力Aなら出力Bになる

と確認できます。

しかしAgentでは、

Goal
↓
判断
↓
Tool
↓
結果
↓
再判断
↓
別のTool
↓
State更新
↓
完了

という複数ステップを進みます。

しかも途中経路が一つとは限りません。

Anthropicは、Agentが複数TurnにわたりToolを使い、Stateを書き換え、中間結果へ適応するため、単発のLLMより評価が複雑になると説明しています。

つまりAgentでは、

正解したか

だけでなく、

どう正解したか

を見る必要があります。

2. これはコードのUnit Testとは別の話

CORE SPECには既に、

「AIコーディングでテスト・デバッグがなぜ必要か」

を扱う記事があります。

そちらで確認する対象は、

AIが書いたコード
↓
Unit Test
Lint
Type Check
Integration Test

です。

今回評価する対象は違います。

Agentそのもの
↓
どのToolを選んだ？
何回実行した？
途中で何を判断した？
目的を達成した？

です。

つまり、

コードをテストする

ことと、

コードを書くAgentを評価する

ことは別です。

もちろんCoding Agentでは、最終成果物をUnit Testで評価することもあります。

しかしそれはAgent Evalの一部です。

3. Evalとは何か

Evalとは、

Agentへ課題を与え、期待する結果や行動基準に照らして評価する仕組み

です。

たとえばCustomer Support Agentなら、

Task
「注文をキャンセルしたい」

に対して、

Outcome

• キャンセルできたか

Behavior

• 正しい注文を確認したか
• 必要なToolだけ使ったか
• Policyを守ったか

Safety

• 本人確認前に操作していないか

などを見ます。

つまりEvalは、

一つの点数を付けるもの

とは限りません。

複数の基準からAgentを見る仕組み

です。

4. Task・Trial・Graderを分けて考える

Agent Evalを理解するうえで便利なのが、

• Task
• Trial
• Grader

という整理です。

AnthropicもAgent Evalでこの区分を使用しています。

Task

Agentへ与える一つの課題です。

「このRepositoryのテスト失敗を修正する」

Trial

同じTaskを実際に一度実行した結果です。

Agentは毎回同じ挙動をするとは限らないため、

同じTaskを複数回試すことがあります。

Task A

Trial 1 → 成功
Trial 2 → 成功
Trial 3 → 失敗

Grader

結果を評価する仕組みです。

たとえば、

Tests passed?
Security policy followed?
Correct tool used?
Final answer acceptable?

などです。

この3つを分けると、

Agent Evalを設計しやすくなります。

5. Agentは一回成功しただけでは判断しにくい

LLMを使うAgentには非決定性があります。

同じ入力でも、

• 別のToolを選ぶ
• 別の順序で調査する
• 異なる文章を生成する

ことがあります。

そのため、

1回成功
=
常に成功

とは限りません。

Anthropicも、モデル出力が実行ごとに変動するため、同じTaskを複数Trialで評価することを推奨しています。

たとえば、

20回実行

18回成功
2回失敗

という結果なら、

単純な、

PASS

より多くのことが分かります。

Trial同士を独立させる

複数Trialを比較する場合は、実行条件も揃える必要があります。

たとえば前のTrialが残した、

• File
• Cache
• Database State
• 一時Data
• Resource消費

などが次のTrialへ残ると、AgentそのものではなくEnvironmentの差を測ってしまいます。

そのためEvalでは、

Trial
↓
Clean Environmentから開始
↓
実行
↓
評価
↓
EnvironmentをReset

という構成が重要になります。これは⑤ State設計や⑥ Sandbox隔離とも直結する重要なポイントです。

6. 「再現性」は毎回同じ答えという意味ではない

Agentにおける再現性は、毎回一字一句同じ回答を返すことではありません。

Model Version、Instruction、Tool、Eval Dataset、実行Environmentなどの条件を揃えたときに、

複数Trialを通して、期待する成功条件をどの程度安定して満たせるか

を見る考え方です。

たとえば旅行Agentなら、毎回同じHotelを提案する必要はありません。しかし、

• 予算内
• 指定地域
• 指定日
• 営業中

という成功条件は守る必要があります。

つまり、

Exact Same Output
ではなく

Stable Success Rate
+
Consistent Expected Behavior

を見る方がAgentらしい評価になります。

7. 最終結果を評価する

最も分かりやすいのが、

Outcome Evaluation

です。

たとえばCoding Agentなら、

Testが通ったか
Buildできたか
Bugが消えたか

です。

Research Agentなら、

必要な論点をカバーしたか
一次資料を使ったか
引用先が存在するか

などです。

ここでは、

Agentが最終的に仕事を完了したか

を見ます。

8. しかしOutcomeだけでは分からないことがある

たとえばAgentが、

正しいファイルを修正してTestを通したとします。

結果だけ見れば成功です。

しかしTraceを見ると、

関係ないファイルを変更
↓
失敗
↓
戻す
↓
別ファイルを変更
↓
Test成功

だったかもしれません。

あるいは、

必要な検索3回

で終わる仕事を、

検索30回

していたかもしれません。

つまり、

Outcomeは正しいが、Behaviorは改善できる

ケースがあります。

9. Trajectoryとは？

Agentが、

Goalから最終結果まで進んだ一連の行動を、

Trajectory（行動軌跡）

と呼ぶことがあります。

たとえば、

Goal

↓
Search Tool

↓
File Read

↓
Shell

↓
File Write

↓
Test

↓
Final Answer

という一連の流れです。

Anthropicは、AgentのTrialにおける出力・Tool Call・中間結果などの完全な記録をTranscript / Trace / Trajectoryとして整理しています。

Agent Evalでは、このTrajectoryを見ることが非常に重要です。

なお、Trajectory / Trace / Transcriptの用語境界はPlatformやFrameworkによって異なります。この記事では理解しやすくするため、

• Trajectory = Agentがたどった行動の流れ
• Trace = その実行を後から観測・分析できるよう記録したデータ

として区別します。

10. Traceとは何か

Traceは、

Agentが一回の仕事で何をしたかを時系列で記録したもの

です。

たとえばOpenAI Agents SDKでは、Tracingが標準で組み込まれており、

• Agent実行
• Model生成
• Function Tool Call
• Guardrail（入力・出力などを検査する制約）
• Handoff（別のAgentへ処理を引き継ぐこと）

などをSpan（Traceを構成する、個々の処理単位）として記録できます。

大まかには、

Trace

├ Model Call
├ Tool Call
├ Tool Result
├ Model Call
├ Handoff
├ Tool Call
└ Final Result

のように見られます。

Traceがあることで、

Agentの内部で何が起きたか

を後から調べられます。

このように処理をステップやノードに分解し、可視化して観測可能にするアプローチについては、「処理を可視化し、観測可能にするノード型設計」でも詳しく整理しています。

11. LogとTraceは同じなのか？

厳密には同じではありません。

Logは、

個々のイベントを記録したもの

として使われます。

10:00 search called
10:01 file read
10:02 test failed

一方Traceは、

一つのTask全体の流れを関連付けて見るもの

です。

Task #123
 ├ Search
 ├ Read
 ├ Test
 └ Final

と考えると分かりやすいでしょう。

実装によって用語は異なりますが、

Agentを観測するうえでは、

点ではなく流れを見る

ことが重要です。

12. Google側でもTraceとEvalが分かれている

GoogleのAgents CLIでも、AgentのEvaluation（評価）とObservability（実行中に何が起きたかを外部から観測・分析できる仕組み）は別の機能として整理されています。

EvalではDatasetに対してAgentを実行し、

• Toolの選択
• ResponseのQuality
• Edge Case

などをMetricで評価できます。

一方Observabilityでは、OpenTelemetry（TraceやMetricなど観測データを扱うための標準仕様）ベースのTraceを使い、

• LLM Call
• Tool Execution
• Latency
• Error

などを追跡できます。

つまり、

Eval
期待通りだった？

Trace
何が起きた？

という役割分担です。

13. EvalとObservabilityはセットで考える

Agent Evalだけあっても、

失敗理由が分からなければ改善できません。

逆にTraceだけ大量に集めても、

何が良くて何が悪いかという基準がなければ判断できません。

そこで、

Eval
↓
失敗を発見
↓
Trace
↓
原因を見る
↓
修正
↓
Eval

という循環を作ります。

これはAgent開発の基本的な改善ループになります。

14. Graderにはいくつか種類がある

Agent Evalの評価方法は一つではありません。

Anthropicは、大きく、

• Code-based
• Model-based
• Human

などのGraderを組み合わせる方法を紹介しています。

Code-based Grader

コードで明確に判定できるものです。

Test passed?
File exists?
JSON schema valid?
Expected API called?

などです。

最も客観的に評価しやすい方法です。

Model-based Grader

LLMを使って、

• 回答品質
• 説明の分かりやすさ
• Policy遵守
• 根拠の十分さ

などを評価します。

いわゆる、

LLM-as-a-Judge（別のLLMを評価者として使い、回答品質などを判定する方法）

です。

Google Agents CLIにもLLM-as-a-Judgeを含む評価Metricが用意されています。

ただし、評価するLLM自身も完全ではありません。そのため、Model-based Graderだけに頼らず、Code-based Graderや、Human Evaluation（人間による評価）で定期的に校正しながら組み合わせます。

Human Evaluation

人間が直接、結果や行動を評価する方法です。

たとえば、

• 本当に役立つか
• 自然な提案か
• 業務として許容できるか
• ブランド基準を満たすか

などは、人間の判断が必要なことがあります。

15. Tool選択も評価できる

Agent Evalでは、

最終回答だけでなく、

正しいToolを使ったか

も評価できます。

たとえば、

ユーザー：
今日の株価を教えて

なのに、

Agentが検索Toolを使わず内部知識だけで答えたら問題です。

逆に、

簡単な文章要約なのに毎回Web Searchを使うなら、

無駄なTool Callです。

つまり、

正しいTool
正しいタイミング
正しい引数

までEvalの対象になります。

GoogleのEvaluation Guideでも、正しいTool CallやResponse Qualityを構造化されたEvalで確認できる仕組みが提供されています。

16. Agentでは「途中の失敗」も重要

最終結果だけ成功していても、

途中で、

• Permission Error
• Tool Error
• Hallucinated Tool（存在しないTool名や利用できないToolを呼ぼうとすること）
• Timeout
• Invalid Argument

が大量に発生しているかもしれません。

これらを放置すると、

モデル変更やTask変更で急に失敗しやすくなる可能性があります。

そこでTraceから、

どこで失敗した？
↓
どうRecoveryした？
↓
何回Retryした？

を見る意味があります。

17. Retry回数も品質になる

Agentは失敗からRecoveryできることがあります。

これは良い能力です。

しかし、

1回失敗
↓
修正
↓
成功

と、

20回失敗
↓
偶然成功

は同じではありません。

そこで、

• Tool Call数
• Retry数
• Token
• Latency
• Cost

も評価指標になり得ます。

つまりAgent Qualityには、

正しく終わること

だけでなく、

どのくらい効率よく終わるか

も含められます。

18. Agent Evalでは「成功条件」を先に決める

Evalを作るときに重要なのは、

Agentを動かしてから、

「なんとなく良さそう」

と評価しないことです。

先に、

何をもって成功とするか

を決めます。

たとえばCoding Agentなら、

必須
・既存Testが全部通る
・新しいBugを作らない
・指定範囲外を変更しない

望ましい
・変更File数が少ない
・不要なTool Callをしない

とできます。

この成功条件が、

Evalの基準になります。

19. Eval Datasetを作る

一つのTaskだけではAgent全体の品質は分かりません。

そこで複数のTaskをまとめた、

Eval Dataset

を用意します。

たとえばCustomer Support Agentなら、

Case 1：キャンセル
Case 2：返金
Case 3：配送遅延
Case 4：本人確認失敗
Case 5：Policy外の要求

などです。

Google Agents CLIでもDatasetを使って複数のEval Caseを実行し、Traceに対してMetricを適用する方式が提供されています。

20. Edge Caseを入れる

正常ケースだけでは不十分です。

Agentは、

予想外の状況で失敗しやすいからです。

たとえば、

Toolが失敗する
APIが遅い
情報が見つからない
User指示が曖昧
矛盾するデータがある
Permissionがない

などです。

つまりEval Datasetには、

うまくいくケースだけでなく、困るケース

も入れます。

また、Eval Datasetでは「やるべきケース」だけでなく、

「やるべきではないケース（不要なTool Callをしないか）」

も含めて両面でバランスを取ることが重要です。たとえば「検索Toolを使うべきケース」だけでなく、「すでに入力情報に含まれているため、Toolを使わずに直接答えるべきケース」もテストに含めることで、無駄なAPI呼び出しやコスト増加を防ぐことができます。

21. 実際の失敗をEvalへ戻す

AgentをProductionへ出すと、

想定していなかった失敗が起こります。

そこで、

Production Failure
↓
原因分析
↓
Eval Case化
↓
修正
↓
再評価

します。

Anthropicも、Evalは一度作って終わるものではなく、Productionの失敗をテストケースへ変換しながら積み重ねることで価値が増すと説明しています。

これはAgent開発で非常に重要です。

22. Regression Testとして使う

AgentのInstructionを修正した。

Modelを新しくした。

Tool Descriptionを変更した。

その結果、

問題Aは直った。

しかし問題Bが壊れた。

ということがあります。このように、変更によって以前できていたことができなくなる現象をRegression（リグレッション：機能退行）と呼びます。

そこで、過去に通過したテストケースを再度流すRegression Test（回帰テスト）として既存Evalを実行します。

変更前
Eval Dataset → 85%

↓

Agent変更

↓

Eval Dataset → 92%

ただし Case 17がRegression

と確認できます。

Evalは、

Agentを採点するためだけ

ではなく、

変更によって何が良くなり、何が壊れたかを見る仕組み

でもあります。

23. Model更新時にもEvalが必要になる

Claude、GPT、GeminiなどのModelは更新されます。

新しいModelの方がBenchmark上強くても、

自分のAgentで必ず良くなるとは限りません。

たとえば、

• Tool Callingの傾向
• Response Length
• Instruction Following
• Cost
• Latency

が変わる可能性があります。

そのため、

Model A
↓
同じEval Dataset

Model B
↓
同じEval Dataset

で比較する意味があります。

Agent時代には、

「最新Modelだから変える」

ではなく、

自分のTaskで良くなったか確認する

という運用が重要になります。

24. Traceを全部保存すればよいのか？

そう単純でもありません。

Traceには、

• User Input
• Model Output
• Tool Argument
• File Content
• API Result

など、機密情報が含まれる可能性があります。

OpenAI Agents SDKでも、TraceへModelやToolのInput / OutputなどのSensitive Dataを含めるか制御できる設定があります。

Google側でも、TraceとPrompt / ResponseのFull Content Loggingを分離し、どこへ内容を保存するかを設定できるようになっています。

つまりObservabilityでは、

見えること

だけでなく、

何を記録しないか

も設計する必要があります。

25. Logを残すこともSecurityの一部

第6回「AgentのSandboxと安全設計」では、Agentの安全設計を次の要素に分けて整理しました。

・Tool = 何ができるか
・Permission = 何を許可するか
・Sandbox / Execution Boundary = 実行系操作がどこまで影響できるか
・Human Approval = 重要な操作の前に人間の確認を入れるか
・Logging / Eval = 何が起きたかを記録・検証できるか

と整理しました。

もし問題が起きたとき、

Agentが何をしたのか

が分からなければ、

原因分析も改善もできません。

したがってLoggingは、

品質管理だけでなく、

監査性

にも関係します。

26. Evalは「Agentを縛る」ためだけではない

Evalというと、

Agentの行動を固定してしまうように感じるかもしれません。

しかしAgentの価値は、

状況に応じて柔軟に判断できることです。

そこで、

正しい経路を一つだけ強制する

のではなく、

許容できる結果と境界を定義する

ことが重要です。

たとえば、

Search → A → B → C

という一つの経路だけを正解にすると、

より良い方法をAgentが見つけても失敗扱いになります。

Anthropicも、AgentがEvalの想定以上に良い解決策を見つけるケースがあるため、評価設計そのものを見直す必要があると指摘しています。

27. 「良いAgent」は一つの数字では測れない

Agent Qualityには、

• Task Completion
• Accuracy
• Tool Selection
• Safety
• Cost
• Latency
• Reproducibility
• User Satisfaction

など複数の軸があります。

したがって、

Agent Score = 92点

だけでは、

何が良いのか分かりません。

むしろ、

Completion     95%
Tool accuracy  98%
Safety         100%
Median steps    7
Latency        12s

のように見る方が、改善につながります。

28. 最初から大規模なEval基盤は必要ない

Agent Evalと聞くと、

大規模なBenchmark基盤が必要に感じます。

しかし最初は、

重要なケースを数件作る

ところから始められます。

GoogleのAgents CLIでも、まず1〜2個の重要なEval Caseを作り、

Eval
↓
失敗確認
↓
修正
↓
再Eval
↓
Case追加

という反復的な進め方が案内されています。

つまり、

最初から1000ケース作る

必要はありません。

29. CORE SPECのAgent Evalループ

CORE SPECでは、Agent開発の評価を次のループで考えます。

① Expected Behavior
期待する行動を決める

↓

② Eval Case
代表的なTaskを作る

↓

③ Run
Agentを実行する

↓

④ Outcome
仕事を完了したか

↓

⑤ Trace
途中の行動を見る

↓

⑥ Failure Analysis
なぜ失敗したか

↓

⑦ Fix
Instruction / Tool / State / Architectureを修正

↓

⑧ Regression Eval
もう一度全ケースを確認

このループを回すことで、

Agentは徐々に安定していきます。

30. Agent設計は「作る」だけでは終わらない

ここまでのシリーズでは、

Agent
↓
Tool
↓
Architecture
↓
State
↓
Sandbox

を見てきました。

しかし、

これらを設計しただけでは、

本当に機能するか分かりません。

そこで最後に、

Evaluation

が必要になります。

Agent設計は、

構築 → 実行 → 観測 → 評価 → 改善

まで含めた循環です。

つまりEvalは、

最後に付け加えるテストではありません。

Agentを育てていくためのフィードバック機構

です。

まとめ

AIエージェントのEvalでは、

最終回答だけではなく、

Agentがどう行動したか

を見ることが重要です。

CORE SPECでは、

・Outcome（結果）
・Behavior（行動）
・Trace / Log（観測）
・Regression（退行防止）

の4つの観点で考えます。

そして、

• Task
• Trial
• Grader
• Trace
• Eval Dataset

を使いながら、

Agentの品質を確認します。

重要なのは、

一度成功したことではなく、期待する仕事を安定して任せられること。

です。

そのためには、

失敗を隠すのではなく、

失敗を観測し、Eval Caseへ変え、次の改善材料にする

ことが重要になります。