Data Agent 架構：意圖、工具、資料與語意

40 分鐘

Data Agent 是什麼：與 Chatbot / BI / Workflow 的差異

學習目標：判斷何時需要 Agent，區分自然語言介面與自主分析行動。

一位主管在對話框打「為什麼六月的轉換率掉了」，並期待一分鐘內得到一個可信、有來源的答案。固定的 BI dashboard 沒辦法回答開放式的追問；沒有資料存取能力的 chatbot 只能用猜的；排程好的 workflow 只能跑它原本被設計要跑的那份報表。Data Agent 介於三者之間：它用自然語言理解需求、規劃需要哪些資料與工具、在有限範圍內執行 read（有時也包含 write）動作，並附上證據回答。多出來的能力也代表多出來的風險，所以第一個設計決策不是「怎麼蓋這個 agent」，而是「這個需求真的需要 agent 嗎，還是 dashboard 或固定 workflow 更安全、也已經足夠」。

import pandas as pd

# clean：本課程使用的受控分析沙盒的一份 read-only 查詢紀錄
df = pd.read_csv("DS302_Analytics_Package_Clean.csv", parse_dates=["event_time", "ingested_at"])
df.shape
df.dtypes
df[["run_id", "source_system", "batch_id", "metric", "value", "schema_version"]].head()

# 先問：這裡真的需要動態規劃的 agent 嗎，還是固定 dashboard 就能回答？
df["source_system"].unique()

• 問題的範圍幾乎每天都在變，新的問題無法用現有 dashboard 的篩選器拼出來。
• 需要在多個資料來源之間動態判斷該查哪一個，而不是永遠查同一張固定的表。
• 答案必須附上可追溯的查詢與資料版本，而不只是一個單獨的數字。
• 需要在執行前先徵求人工核准的分支邏輯，排程 workflow 本身無法表達這種條件判斷。
• 如果固定的 dashboard、報表或 workflow 已經能在可接受的時間內回答大多數問題，就不需要 agent；多加一層 agent 只會多一層風險，卻沒有對應的好處。

重點: 能完成步驟不代表結果可信；本節的能力必須能被驗證、重做並清楚說明。

45 分鐘

Intent → Analysis Plan：先規劃再執行

學習目標：把需求轉成實體、指標、篩選、期間、分析計畫、證據與 approval needs。

學員問 agent「我們這一季表現怎麼樣」，agent 立刻發出一個查詢。表現什麼、對誰而言、哪一段期間、跟什麼基準比？一個模糊的需求如果立刻被執行，只會得到一個模糊、無法驗證的答案。Agent 在呼叫任何工具之前，應該先把需求轉成明確的分析計畫：牽涉哪些實體與指標、適用哪些篩選與期間、要用什麼步驟得出答案、需要什麼證據才能讓人信任這個結果，以及是否有任何步驟需要先經過人工核准。

# 模糊：沒有計畫，直接執行
# 「我們這一季表現怎麼樣」-> agent 亂猜一個查詢就回傳數字

# 有規劃：先拆解需求，才開始執行
plan = {
    "entities": ["source_system"],
    "metrics": ["conversion_rate", "active_users"],
    "filters": {"schema_version": "v2"},
    "time_range": "2026-Q2",
    "steps": ["load current-quarter rows", "validate against contract", "aggregate by source_system"],
    "evidence_required": ["row count", "dataset_version", "definition of conversion_rate"],
    "approval_needed": False  # read-only 彙總；若是 write/publish 動作則應為 True
}

1. 1把需求改寫成一個問題
   在選擇任何工具之前，先把自由文字轉成具體、可檢查的問題。
2. 2解析實體、指標、篩選、期間
   明確填入每一項；如果資訊不足，應該詢問而不是用猜的。
3. 3列出證據需求
   事先決定最終答案必須附上什麼，才能被視為可信。
4. 4標示 approval needs
   把任何寫入、發布或有實質影響的步驟標記為需要人工核准。

• 把「這一季」解讀成 agent 自己決定的任意 90 天，而不是財務日曆真正定義的那一季。
• 把一個部門問的「使用者」，誤用成另一個部門對「使用者」的定義。
• 沒有要求任何 evidence，就把彙總後的單一數字當作最終答案直接呈現。
• 遇到範圍不清楚的請求時，用一個「看起來合理」的假設悄悄填補，而不是回頭詢問提問者。

重點: 能完成步驟不代表結果可信；本節的能力必須能被驗證、重做並清楚說明。

45 分鐘

Tool Layer：SQL、Python、Retrieval 與 APIs

學習目標：使用 allowlisted、窄介面的工具，分離 read 與 write/action tools。

同事給 agent 一個通用的「run_sql」工具，可以接受任何查詢字串，所以它除了能讀取資料，也能 DROP 一張表，或讀到原本不該碰到的資料表。窄範圍的 tool layer 就是讓 Data Agent 的能力精準對齊「真正被核准的範圍」的那道邊界：與其給一個萬能的 SQL 工具，不如給 agent 好幾個窄範圍的工具，每一個都有明確的 schema、明確的用途，以及固定的 read-only 或 write/action 分類。

# 錯誤做法：一個工具接受任意 SQL，不分 read 或 write，可碰任何資料表
def run_sql(query: str) -> pd.DataFrame:
    return db.execute(query)  # 沒有 allowlist，沒有分離 read/write

# 正確做法：窄範圍、目的明確、有明確 schema 的 read-only 工具
def query_metric_summary(source_system: str, metric: str, time_range: str) -> pd.DataFrame:
    """Read-only。只能查詢事先核准的 analytics_sandbox 檢視表。"""
    ALLOWED_SOURCE_SYSTEMS = {"crm", "billing", "support", "web_analytics", "ops"}
    if source_system not in ALLOWED_SOURCE_SYSTEMS:
        raise ValueError(f"source_system not allowlisted: {source_system}")
    return sandbox_view.query(source_system=source_system, metric=metric, time_range=time_range)

def publish_report(report_id: str, content: dict) -> None:
    """Write/action 工具。執行前需要人工核准（見第 9 節）。"""
    raise PermissionError("publish_report requires an approved run; see approval workflow")

• 每個工具只做一件被清楚命名的事，名稱本身就是它的使用範圍說明。
• Read 工具與 write/action 工具必須是不同的 function，擁有各自的權限與各自的 allowlist。
• 參數使用明確型別與列舉值，而不是接受自由格式字串讓 agent 自己拼查詢條件。
• 任何未被明確核准的 source_system、資料表或欄位，預設一律拒絕，而不是預設允許。
• 每一次工具呼叫都要被記錄，包含呼叫者、參數與資料版本，才能在事後被稽核。

重點: 能完成步驟不代表結果可信；本節的能力必須能被驗證、重做並清楚說明。

45 分鐘

Semantic Layer 與 Trusted Metrics

學習目標：以可信 semantic layer 固定 metrics、dimensions、definitions、join paths、units 與 policy。

兩個部門同一天問 agent「轉換率」，卻得到兩個不同的數字，因為一個團隊的查詢把退款訂單算進去，另一個沒有，而且沒有人把任何一種定義寫下來。如果沒有共用的 semantic layer，一個可以自由寫 SQL 的 agent，每一次都會悄悄地重新發明每個指標的定義。Semantic layer 把 metric 公式、dimension 定義、join path、units 與存取政策固定在同一個地方，agent 必須查詢它，而不是自己猜。

SEMANTIC_METRICS = {
    "conversion_rate": {
        "formula": "converted_sessions / total_sessions",
        "unit": "ratio (0-1)",
        "owner": "analytics-platform-team",
        "grain": "source_system x batch_id"
    },
    "active_users": {
        "formula": "count(distinct entity_id where last_event <= 30 days)",
        "unit": "count",
        "owner": "analytics-platform-team",
        "grain": "source_system x batch_id"
    }
}

def resolve_metric(name: str) -> dict:
    if name not in SEMANTIC_METRICS:
        raise ValueError(f"metric not in semantic layer, cannot resolve a trusted definition: {name}")
    return SEMANTIC_METRICS[name]

重點: 能完成步驟不代表結果可信；本節的能力必須能被驗證、重做並清楚說明。

65 分鐘

Guided Lab：可驗證的 Read-Only Data Agent

學習目標：在教師引導下，建立 read-only prototype：規劃、查詢、必要時跑 Python、標示資料版本並驗證 totals。

• 前往 DS 302 實作頁面
• 預覽下載乾淨版分析沙盒（CSV，合成資料）
• 下載 Guided Lab 起始 Notebook（read-only agent prototype）
• 預覽下載資料字典（繁體中文）
• 預覽下載資料字典（英文）

1. 1規劃 (Plan)
   針對一個範例需求，在寫任何查詢之前先寫出實體、指標、篩選、期間與證據需求。
2. 2查詢 (Read-only)
   只呼叫窄範圍、allowlisted 的 read 工具查詢沙盒，絕不使用通用查詢工具。
3. 3必要時執行 Python
   如果工具本身的輸出還需要進一步彙總，把邏輯獨立成一個小而明確的 function。
4. 4標示資料版本
   把 schema_version 與實際使用的列數，跟答案一起記錄下來。
5. 5驗證 totals
   在呈現答案前，至少用一個獨立的預期值交叉檢查一項總計。

• 直接呈現彙總後的數字，卻沒有記錄用到的 schema_version 與列數。
• 只做一次查詢就假設結果正確，沒有用第二個獨立方法交叉檢查總計。
• 把「程式沒有報錯」當成「邏輯正確」的證明，而沒有實際檢查輸出是否合理。
• 省略了「如果換一個人重跑，會得到同樣答案嗎」的自我檢查。

重點: 能完成步驟不代表結果可信；本節的能力必須能被驗證、重做並清楚說明。