前言

這幾年 LLM 進步很快。早期我們多半拿它來回答問題，後來開始讓它呼叫工具、查資料、操作檔案，甚至執行程式。到了這一步，它就不只是 Chatbot，而是開始接近 AI Agent。

很多 Agent Demo 看起來都很厲害：丟一個任務進去，它會自己拆步驟、選工具，最後交出結果。

但真的用起來，很快就會遇到一個麻煩：

Agent 看起來有完成任務，但我們真的知道它中間做了什麼嗎？

如果只看最後答案，我們其實很難判斷：

• 它有沒有理解任務？
• 它有沒有用錯工具？
• 它是否產生了幻覺？
• 它的輸出格式是否穩定？
• 它失敗時是因為 prompt、工具、模型，還是流程設計？
• 改 prompt 或加 retry 之後，表現是否真的變好？

所以這次鐵人賽，我想用 30 天做一個輕量級平台。主題是：

從黑盒到可驗證：30 天打造 AI Agent 的 Trace、Eval 與 Guardrails 系統

這個系列不是要做出「最強 Agent」。我更想處理另一件事：

怎麼讓 AI Agent 可以被觀察、被測試、被分析，然後一步一步改善。

今天要完成什麼？

Day 1 先不寫程式。今天先把問題講清楚，後面 29 天才有共同基準。

這篇會做三件事：

1. 區分 AI Agent 和一般 Chatbot 的差異。
2. 說明為什麼只看 final answer 不足以驗證 Agent。
3. 定義本系列要實作的最小測試驗證平台。

換句話說，今天不追功能，先把 Trace、Eval 和 Guardrails 這幾個詞放到同一個脈絡裡。

Agent 和 Chatbot 有什麼不同？

先從 Chatbot 說起。

一般 Chatbot 的流程通常很單純：

使用者輸入 -> LLM 產生回答 -> 回傳結果

例如：

使用者：請解釋什麼是 binary search
模型：Binary search 是一種在排序資料中搜尋目標值的演算法...

在這種情境下，我們主要檢查回答是否正確、清楚。

Agent 麻煩一點。它不是只產生一句回答，而是可能經過一串動作：

使用者任務
  -> Agent 判斷要做什麼
  -> 呼叫工具
  -> 取得工具結果
  -> 根據結果繼續推理
  -> 可能再次呼叫工具
  -> 最後產生答案

例如使用者要求：

請幫我計算 135 * 28，並用 JSON 格式回傳答案。

Agent 可能會走過這些步驟：

Step 1：理解任務需要計算
Step 2：呼叫 calculator tool
Step 3：取得計算結果 3780
Step 4：組成 JSON 回答

最後輸出：

{
  "answer": 3780
}

如果最後答案正確，看起來當然沒事。

問題是，一旦答案錯了，我們需要知道錯在哪一層：

• 是模型理解錯任務？
• 是工具呼叫參數錯？
• 是工具本身回傳錯？
• 是最後輸出格式錯？
• 還是中間某一步沒有被記錄，所以無法追蹤？

Agent 測試驗證平台要處理的，就是這類問題。

為什麼只看 final answer 不夠？

很多 AI 應用在展示時，只會呈現最後結果：

Input: 請完成某個任務
Output: Agent 的回答

Demo 這樣做很直覺，但工程上不太夠。

Agent 可能在中間做了錯誤的事，只是最後答案剛好看起來合理。

例如：

任務：請根據文件回答申請截止日
Agent 回答：申請截止日是 10 月 15 日

這個答案至少可能有三種情況：

1. Agent 真的從文件中找到 10 月 15 日。
2. Agent 沒有查文件，只是靠常識或猜測回答。
3. Agent 查到的是其他年度的截止日。

如果只看 final answer，我們很難分辨這三者。

這對 Agent 系統是很大的風險。使用者看到答案時，通常不會知道 Agent 是「根據資料回答」，還是只是「回答得像有根據」。

所以我們需要留下執行紀錄，至少包含：

• 使用者輸入了什麼？
• 當時使用的是哪個 prompt？
• Agent 呼叫了哪些工具？
• 工具輸入與輸出是什麼？
• Agent 最後如何產生答案？
• 執行時間與 token 成本是多少？
• 過程中有沒有錯誤？

這些紀錄就是後面會提到的 Trace。

黑盒 Agent 的問題

目前常見的 Agent 問題，我會先分成四類。

1. 過程不可見

Agent 可能做了很多中間步驟，但系統沒有留下紀錄。

結果錯了，我們只能猜：

是 prompt 不好？
是工具設計不好？
是模型能力不足？
還是資料來源錯了？

沒有 trace，除錯會變得很靠運氣。

2. 無法重複測試

很多 Agent 仍然只靠手動測試。

例如今天測三個問題，覺得回答不錯，就先判斷 Agent 可用。

但這種方式很脆弱：

• 測試案例太少。
• 每次測試條件不一致。
• 改 prompt 後無法客觀比較。
• 無法知道整體成功率。

所以我們需要 eval dataset，也就是一組固定測試案例。

3. 失敗原因不清楚

Agent 失敗不只是一句「答錯了」。

可能的失敗類型包括：

• 格式錯誤：要求 JSON，卻回傳自然語言。
• 答案錯誤：內容與預期不符。
• 工具錯誤：工具呼叫失敗或參數錯誤。
• 指令遵循錯誤：沒有按照任務要求回答。
• Timeout 或 exception：執行過程中斷。

只統計 pass / fail 還不夠。真正有幫助的是知道主要失敗類型，才知道該改 prompt、改工具，還是改流程。

4. 改善效果無法量化

假設我們改了 prompt，或加入 retry 機制。

體感上可能會覺得 Agent 變好了，但到底好多少？

這時候需要用數據回答：

成功率是否提升？
格式錯誤是否下降？
平均延遲是否增加？
token 成本是否變高？

可靠性驗證要看的，就是這些變化。

這個系列要做什麼？

接下來 30 天，我會實作一個簡化版的 Agent 測試驗證平台。

它不會是 production-grade 的完整 AgentOps 產品。這裡的目標比較務實：做出一個能理解核心概念、能跑實驗、也能看結果的 MVP。

整體流程會長這樣：

Test Case
  -> Agent Runner
  -> Trace Recorder
  -> Evaluator
  -> Failure Classifier
  -> Reliability Dashboard

白話一點：

準備測試題目
  -> 讓 Agent 執行
  -> 記錄每一步
  -> 自動判斷對錯
  -> 分析錯誤類型
  -> 比較不同改善方法

平台最後會包含幾個核心模組。

Agent Runner

負責接收任務並呼叫 LLM。

一開始會先做最簡單的 Agent，之後再加入工具呼叫。

Trace Recorder

負責記錄 Agent 的執行過程。

例如：

{
  "session_id": "run_001",
  "steps": [
    {
      "type": "user_input",
      "content": "請計算 135 * 28"
    },
    {
      "type": "tool_call",
      "tool_name": "calculator",
      "input": "135 * 28",
      "output": "3780"
    },
    {
      "type": "final_answer",
      "content": "{\"answer\": 3780}"
    }
  ]
}

Eval Dataset

準備固定測試案例。

例如：

{
  "id": "case_001",
  "input": "請計算 135 * 28，並用 JSON 格式回傳答案",
  "expected": {
    "answer": 3780
  },
  "grading_method": "json_exact"
}

Evaluator

負責自動評分。

前期會先做簡單規則：

• exact match
• keyword match
• JSON validation

Failure Analysis

負責分析 Agent 失敗原因。

例如：

case_003 failed
failure_type: format_error
reason: output is not valid JSON

Guardrails

負責限制 Agent 的輸出與工具使用。

這個系列會先從簡單版本開始：

• JSON schema validation
• retry
• tool permission control

技術棧選擇

30 天要穩定完成，架構不能一開始就太重。

預計使用：

• Python：主要開發語言。
• Streamlit：快速建立操作介面與 dashboard。
• SQLite：儲存 trace、測試案例與評測結果。
• Pydantic：定義資料模型與驗證 JSON 輸出。
• LLM API：作為 Agent 的模型來源。
• Pandas：整理評測資料。
• Plotly / Altair：繪製簡單圖表。

這樣選的原因很單純：降低前後端整合成本，把時間留給 Agent 測試驗證本身。

30 天路線圖

這個系列會分成四個階段。

第一週：Trace

先讓 Agent 從黑盒變透明。

會完成：

• 最小 Agent Runner
• 第一個工具
• Trace 資料格式
• SQLite 儲存
• Trace Viewer

第一週結束時，希望可以看到 Agent 每一步做了什麼。

第二週：Eval

接著讓 Agent 可以被自動測試。

會完成：

• test case 格式
• eval dataset
• batch evaluation runner
• exact match / keyword match evaluator
• JSON validation

第二週結束時，希望可以產出第一份 baseline 評測報告。

第三週：Failure Analysis

第三週不只看 Agent 有沒有錯，還要看它為什麼錯。

會完成：

• failure type 定義
• failure classification
• 錯誤分析表格
• failure dashboard
• prompt versioning
• prompt A/B testing

第三週結束時，希望可以看出不同 prompt 對成功率與錯誤類型的影響。

第四週：Guardrails

最後加入簡單的可靠性改善策略，再用數據比較改善前後的差異。

會完成：

• retry
• schema validation
• tool guardrail
• latency / token / cost 紀錄
• reliability dashboard
• 最終實驗比較

第四週結束時，希望整理出一套簡化但完整的 Agent 測試驗證流程。

今天的結論

Day 1 先把問題擺出來。

這個系列的核心不是：

我做了一個很厲害的 AI Agent。

而是：

我建立了一套方法，讓 AI Agent 的行為可以被追蹤、測試、分析與改善。

接下來 Day 2 會先從最小可用的 Agent Runner 開始，讓系統能接收任務、呼叫 LLM，並產生第一個可觀察的執行結果。