前言

第一週我們完成了 Trace 相關的基礎建設。

目前平台已經可以回答：

Agent 執行過程中發生了什麼？

透過 Trace Viewer，我們可以看到一次 Agent 執行中的：

user_input
llm_response
tool_call
tool_result
final_answer

這解決了「看不見過程」的問題。

但只看見過程還不夠。

接下來第二週要處理另一個問題：

Agent 到底有沒有完成任務？

這就是 Agent Evaluation 要處理的事情。

今天要完成什麼？

Day 8 是第二週的開場篇，今天先不寫程式，而是把後面幾天會用到的 Evaluation 概念講清楚。

會完成：

1. 說明為什麼 Agent 需要 Evaluation。
2. 定義什麼是 eval dataset。
3. 定義什麼是 test case。
4. 定義 success rate。
5. 定義 format accuracy。
6. 定義 latency。
7. 說明本系列會先使用小型測試集。

今天先不做：

• 建立 cases.json。
• 實作 batch runner。
• 實作 evaluator。
• 製作 evaluation dashboard。

這些從 Day 9 開始逐步實作。

為什麼只手動測試不夠？

在開發 Agent 時，我們很容易用手動方式測試。

例如輸入幾個問題：

請計算 135 * 28
請簡單介紹 AI Agent
請用 JSON 格式回傳計算結果

如果這幾題看起來都正常，就會覺得 Agent 應該可以用了。

但這種方式有幾個問題。

1. 測試案例太少

手動測三題、五題，只能代表這幾個例子剛好成功。

它不能代表 Agent 在更多情境下都穩定。

2. 每次測試條件不一致

今天可能測這三題，明天改 prompt 後又測另外五題。

這樣很難判斷：

是 Agent 真的變好了？
還是只是今天測的題目比較簡單？

3. 沒有留下可比較的結果

如果沒有固定測試集，就很難比較不同版本。

例如：

baseline prompt
improved prompt
retry enabled
schema validation enabled

這些版本到底哪個比較穩，需要在同一組測試案例上比較才公平。

4. 很難量化改善幅度

我們可能覺得改完 prompt 後「好像比較穩」。

但工程上需要更具體的數字：

成功率從 70% 提升到 85%
格式錯誤從 5 次下降到 1 次
平均延遲從 1.2 秒增加到 1.8 秒

這些數字才有辦法支撐後面的分析。

Agent Evaluation 是什麼？

Agent Evaluation 可以先理解成：

用一組固定測試任務，重複測量 Agent 的表現。

它的基本流程會像這樣：

Eval Dataset
  -> Agent Runner
  -> Agent Output
  -> Evaluator
  -> Evaluation Result

白話一點：

準備測試題目
  -> 讓 Agent 一題一題執行
  -> 收集每題答案
  -> 自動判斷 pass / fail
  -> 統計整體表現

Evaluation 的重點不是證明 Agent 永遠正確。

它比較像一個檢查流程，幫助我們回答：

• Agent 在目前測試集上的成功率是多少？
• 哪些任務類型比較容易失敗？
• 失敗是答案錯，還是格式錯？
• 改 prompt 之後是否真的改善？
• 加 retry 之後成功率是否提升？
• 成本和延遲是否跟著增加？

這些問題都需要 Evaluation 才能回答。

Eval Dataset 是什麼？

Eval dataset 是一組固定測試案例。

它的角色有點像一般軟體測試裡的 test suite。

例如我們可以準備一組測試任務：

case_001：請計算 135 * 28
case_002：請計算 72 + 19
case_003：請回答台灣的首都是哪裡
case_004：請用 JSON 格式回傳 10 + 5 的結果
case_005：請簡短說明什麼是 AI Agent

每次修改 Agent 後，都用同一組 dataset 測一次。

這樣才有辦法比較不同版本的差異。

如果今天測 baseline prompt，明天測 improved prompt，兩者都要跑同一組 eval dataset。

否則數據就不公平。

Test Case 是什麼？

Eval dataset 裡面的每一筆資料，就是一個 test case。

一個最小 test case 通常會包含：

input
expected
grading_method
task_type

先用概念表示：

{
  "id": "case_001",
  "input": "請計算 135 * 28",
  "expected": "3780",
  "grading_method": "contains",
  "task_type": "calculation"
}

這裡每個欄位的意義是：

今天先理解這個格式就好。

Day 9 會正式設計 cases.json，並建立前 5 筆 test cases。

評測指標一：Success Rate

第一個最直覺的指標是 success rate，也就是任務成功率。

公式很簡單：

success_rate = passed_cases / total_cases

假設有 20 筆測試案例：

通過 16 筆
失敗 4 筆

那 success rate 就是：

16 / 20 = 80%

這個指標可以快速回答：

Agent 在目前測試集上整體表現如何？

但 success rate 也有缺點。

如果只看成功率，我們不知道失敗原因是什麼。

例如同樣是 80% 成功率，可能代表：

版本 A：主要失敗在計算錯誤
版本 B：主要失敗在 JSON 格式錯誤
版本 C：主要失敗在工具呼叫失敗

所以 success rate 是必要指標，但不能只看它。

評測指標二：Format Accuracy

第二個重要指標是 format accuracy，也就是格式正確率。

很多 Agent 任務不只要求答案正確，還要求輸出格式固定。

例如：

請用 JSON 格式回傳答案，格式必須包含 answer 欄位。

理想輸出是：

{
  "answer": 3780
}

但 Agent 可能回傳：

答案是 3780。

這個回答對人類來說看得懂，但對系統來說可能是失敗。

因為後續程式如果要解析 JSON，這段文字就不能直接使用。

所以我們需要 format accuracy：

format_accuracy = valid_format_cases / format_required_cases

這個指標可以回答：

Agent 的輸出是否足夠穩定，能被程式接著處理？

這也是後面 Guardrails 會處理的重要問題。

評測指標三：Latency

第三個指標是 latency，也就是執行延遲。

Agent 不只要答對，也要在合理時間內完成。

尤其 Agent 可能會有多個步驟：

LLM response
tool call
tool result
retry
final answer

每多一個步驟，都可能增加延遲。

Latency 可以先用最簡單方式定義：

latency = 任務結束時間 - 任務開始時間

例如：

case_001 latency: 1.2s
case_002 latency: 0.8s
case_003 latency: 2.1s

之後可以統計：

average_latency = 所有案例 latency 總和 / total_cases

這個指標在後面比較 retry 時會很重要。

因為 retry 可能讓成功率上升，但也可能讓平均延遲變高。

評測指標四：Task Type Accuracy

除了整體成功率，也應該看不同任務類型的表現。

例如 eval dataset 裡可能有幾種任務：

calculation
keyword_qa
json_output
tool_use

如果只看整體成功率是 80%，還不夠。

我們更想知道：

calculation: 90%
keyword_qa: 85%
json_output: 50%
tool_use: 75%

這樣才知道 Agent 的弱點在哪裡。

如果 json_output 特別差，代表後面應該優先處理 structured output 或 schema validation。

如果 tool_use 特別差，代表工具選擇或 tool input 可能需要改善。

評測指標五：Failure Type

嚴格來說，Failure Type 會在第三週更完整處理。

但 Day 8 先建立概念。

Agent 失敗時，不應該只記錄：

failed

而是要盡量記錄它為什麼失敗。

常見類型包括：

這些分類會讓後面的改善更有方向。

例如：

如果主要是 format_error，就加 schema validation。
如果主要是 tool_error，就改善 tool input 或 tool guardrail。
如果主要是 wrong_answer，就檢查 prompt 或資料來源。

本系列先使用小型測試集

Evaluation 聽起來可以做得很大，例如：

• 大型 benchmark。
• 多模型比較。
• LLM-as-a-Judge。
• RAG groundedness。
• 多輪 Agent 任務。

但這些不是第二週的目標。

為了讓 30 天能穩定完成，本系列先使用小型測試集。

初期目標是 10 到 20 筆 test cases，任務類型包含：

• 基本問答。
• 關鍵字回答。
• 計算任務。
• JSON 格式輸出。
• 簡單工具使用。

這樣安排有幾個好處：

• 測試資料容易理解。
• 評分規則容易實作。
• 可以快速跑完整流程。
• 後面比較 prompt 或 retry 時有固定基準。

等 MVP 完成後，再考慮加入更複雜的評測。

Evaluation 和 Trace 的關係

第一週做的 Trace，不會在第二週被丟掉。

相反地，Trace 會成為 Evaluation 的重要補充。

Evaluation 可以告訴我們：

case_003 failed

Trace 可以進一步告訴我們：

case_003 為什麼 failed？

例如：

Eval Result:
case_004 failed
reason: expected JSON, but got plain text

搭配 trace 後，我們可以看到：

user_input:
請用 JSON 格式回傳 135 * 28 的答案

llm_response:
{
  "type": "tool_call",
  "tool_name": "calculator",
  "tool_input": "135 * 28"
}

tool_result:
3780

final_answer:
The result is 3780

這時候就能判斷：

工具計算是正確的，但 final answer 沒有符合 JSON 格式。

也就是說，Evaluation 負責判斷有沒有過，Trace 負責幫助我們理解為什麼沒過。

這兩者合在一起，才比較接近「可驗證」的 Agent 系統。

今天沒有新增程式碼

Day 8 是概念定義篇，所以今天不新增或修改任何檔案。

目前專案仍維持 Day 7 的狀態：

agent-testing-platform/
  app.py
  trace_viewer_app.py
  agents/
  tools/
  tracing/
  storage/
  ui/
  data/

如果想確認第一週成果，可以繼續使用：

python3 app.py

產生 trace，或使用：

streamlit run trace_viewer_app.py

查看 Trace Viewer。

從 Day 9 開始，才會正式新增 eval 相關檔案。

今天的重點整理

今天定義了 Agent Evaluation 的基本概念。

主要想法是：

不要只手動測幾題，而是用固定測試集重複測量 Agent 表現。

今天提到幾個後面會用到的概念：

• Eval dataset。
• Test case。
• Success rate。
• Format accuracy。
• Latency。
• Task type accuracy。
• Failure type。

第一週的 Trace 回答：

Agent 做了什麼？

第二週的 Eval 則要開始回答：

Agent 做得對不對？

下一步

Day 9 會開始設計 Test Case 格式。

下一篇會新增 eval 相關資料夾，並建立第一個測試案例格式。每筆 test case 會包含：

• id
• input
• expected
• grading_method
• task_type

我們會先建立前 5 筆測試案例，讓 Day 10 可以擴充成第一組完整 eval dataset。