在更深入 Agent 設計之前，我想先花一點時間回答一個更根本的問題：

為什麼我們需要 Agent 來協助人類做數據分析？

這也是整個 project 的 why。

在過去直覺的做法，是直接把資料集送進 LLM，然後要它分析。

對小型資料集來說，這種方式運作得不錯。模型可以直接閱讀資料、整理趨勢、比較數值，並產出結論。

但當我們想把這件事產品化時，很快就會遇到三個問題。

直接把資料放進 LLM 的限制

第一個問題是 scalability。

隨著資料量增加，把整份資料塞進 model context 會越來越昂貴，也可能直接超過 context window。

第二個問題是 verifiability。

如果 LLM 直接產出最終分析結果，我們很難確認數字怎麼算出來、哪些資料被納入，以及結果是否真的基於事實。

第三個問題是 data governance。

企業資料通常包含機敏資訊，因此 raw data 的存取仍然需要遵循既有的 security 與 authorization boundary，而不能假設所有資料都可以直接送到外部 model endpoint。

因此，在這個專案裡，我們會採用另一種設計：

Raw Data → LLM → Answer

改成：

Data + User Intent → Agent → Generated Code → Execution → Result

我們不再要求 LLM 直接處理每一筆資料，而是讓 Agent 產生真正用來執行分析的邏輯。

從 Analysis as Output 到 Code as Output

核心轉變是：

從 analysis as output，轉成 code as output。

Agent 的責任，是理解使用者想知道什麼，並把這個意圖轉成可執行的分析邏輯。

例如，與其直接問 LLM：

各地區的平均營收是多少？

我們可以讓 Agent 產生：

result = (
    df.groupby("region")["revenue"]
    .mean()
    .reset_index()
)

接著再把程式碼放到執行環境中執行。

使用 code 的好處是 可驗證。

Code 可以被 inspect、test、rerun、version，也可以套用到另一份資料上。

這並不能消除 hallucination，但如果 Agent 產生錯誤邏輯，我們至少有一個具體、可以被檢查與驗證的 artifact，而不是只能相信一次性的模型回答。

使用者扮演的角色：Domain Knowledge Input

即使 AI 大幅提升了寫 code 的效率，Domain Knowledge 依然掌握在人類手上。

使用者可能知道：

• business metric 應該怎麼計算
• 哪些資料應該被排除
• 某個 status 代表什麼
• 哪些結果應該被 highlight

這些知識可以透過和 Agent 的對話帶進分析流程。

例如：

User: 內部測試帳號的 revenue 不應該被計算。
Agent: 該怎麼判讀內部帳號？
User: 開頭是 kxy 的帳號。

Agent 就可以把這個規則納入分析邏輯。

概念上：

Data + User Intent + Domain Knowledge → Agent → Executable Analysis

那我們到底要儲存什麼？

在這個系統裡，一個 Analysis 不只是 code。

我們想保存的是：

Analysis = User Intent + Confirmed Code + Output Specification

User Intent

描述分析目標，以及對話中累積的 domain knowledge 和 business rules。

Confirmed Code

代表真正可執行的分析邏輯，而且已經和使用者確認過結果符合預期。

Output Specification

描述結果應該如何被呈現。

在這個專案中，主要 output 會是一份 HTML report。

但我們不是保存一份靜態 HTML，而是保存 report guidance，讓 Agent 可以根據每次輸入的資料產生不同內容。

Stable Analysis, Adaptive Report

Analysis 中有些內容應該保持穩定：

• intent
• business rules
• analysis logic
• output structure

但有些內容應該隨資料改變：

• findings
• charts
• observations
• recommendations

下面這個例子展示了同一個 Analysis 套用到兩份不同的資料集。

例如，同一套商品類別分析邏輯可以：

• 彙總各類別銷售
• 排名
• 計算占比
• 產生 report

但不同 dataset 可能得到不同結果：一份資料中 Shoes 是第一名，另一份可能變成 Clothing。

Report 應該反映這些差異，而不是每次都產生相同內容。

流程可以簡化成三步：

1. Persisted Analysis
   Intent + Confirmed Code + Report Guidance

2. Execute on a New Dataset
   將同一套分析邏輯套用到相同 schema 的資料上。

3. Generate a Data-aware HTML Report
   根據 execution result 動態產生 findings、charts 與敘述。

Define Once, Analyze at Scale

使用者可以先用一份小型資料集和 Agent 一起定義 Analysis。

確認完成後：

Small Dataset → Define & Validate Analysis → Persist Analysis

之後就可以：

Large Dataset with Same Schema → Execute Analysis → Generate New Report

Agent 不需要每次重新理解同一個問題。

系統已經知道：

• 使用者想知道什麼
• 分析邏輯怎麼執行
• 結果應該怎麼呈現

這就是：

Define Once, Analyze at Scale.

而當這些重複性的分析可以被保存並再次執行後，使用者就可以把注意力放在真正重要的事情上。