Tabular Data Tool

Tabular Data Tool 用來精確回答 CSV、XLSX 活頁簿或 Google Sheet 裡的問題。Codeer 可以透過 Knowledge Base 自動發現或明確選取來源來使用它。它會直接讀取結構化資料列，因此比文件搜尋更適合篩選、排序、計數，以及計算總和或平均值。

每個明確設定的工具會連接一個表格資料來源。不論來源是自動發現或明確選取，每次查詢都只能使用一個資料表、工作表或分頁。

準備資料來源

設定工具前，先把來源加入 Knowledge Base：

直接上傳 CSV 或 XLSX 檔案。
從 Google Drive 匯入 Google Sheet。
等待處理完成，確認來源已可使用。
打開來源詳細資料，檢查資料表、列數、欄位、推斷型別與警告。

各種來源會依下列方式轉成資料表：

來源	工具可用的資料表
CSV	整個檔案是一個資料表
XLSX	每個可見工作表是一個資料表
Google Sheets	每個可見分頁是一個資料表

請使用清楚的資料表與欄位名稱，讓 Agent 在準備查詢時更容易選到正確的資料表和欄位。

活頁簿公式

Codeer 不會執行試算表公式。對 XLSX 而言，只會讀取活頁簿已儲存的值；如果公式沒有已儲存的值，該儲存格會視為空值，並可能顯示警告。隱藏的工作表與分頁不會提供給工具使用。

選擇自動發現或明確指定來源

只要 Agent 已設定 Knowledge Base，它就能自動尋找並查詢相關的 CSV、XLSX 工作表或 Google Sheets 分頁，不需要替每個來源都另外新增 Tabular Data Tool。

設定方式	適用情境	運作方式
自動發現	通用 Agent 應該從已設定的 Knowledge Base 選擇相關資料表	設定 `Knowledge Base`，不要新增明確指定來源的 `Tabular Data Tool`
明確指定來源	來源必須固定，或有多份名稱、內容相近的資料	為 Agent 可使用的每個來源分別新增一個 `Tabular Data Tool`

使用自動發現時，如果只有一個明確符合的資料表，Agent 會直接查詢；如果有多個合理候選，Agent 會列出少量選項，請使用者確認後再查詢。

發布 Agent 會讓 channel 使用者存取已設定的表格資料

發布 Agent 後，透過其 Knowledge Base 或明確設定的 Tabular Data Tool 加入的表格來源，可供 Web client、Widget、Browser Extension、Slack、LINE、Messenger 與 Instagram 的使用者查詢。這不只包含文件片段，也包含精確資料列、篩選結果與彙總。發布前，請只加入已核准提供給外部使用者的來源。

明確設定的工具優先

Agent 只要有任何明確設定的 Tabular Data Tool，就不會再執行自動發現。它只使用工具中選取的來源，也不會 fallback 到 Knowledge Base 裡的其他資料表。

自動發現上線前加入的來源

較早加入的表格資料可能需要重新處理，Agent 才能自動找到。如果來源沒有如預期被選到，請替換 CSV 或 XLSX、刷新 Google Sheet，或重新匯入，再測試 Agent。既有的明確 Tabular Data Tool 連接仍可正常使用。

把明確指定來源的工具加到 Agent

在 Editor 打開 Agent。
到 Tools 按 Add Tool。
選擇 Tabular Data Tool。
選擇一個已可使用的 CSV、XLSX 或 Google Sheets 來源。
寫一段範圍明確的 When to Use。

例如：

當使用者詢問 2026 銷售活頁簿裡的客戶紀錄、訂單總額或分組銷售數字時，使用這個工具。查客戶時使用 Customers 資料表，計算銷售時使用 Orders 資料表。

如果 Agent 需要多個來源，請為每個來源分別新增一個工具，並讓各自的 When to Use 清楚區分用途。

測試預期問題

在 Live Test 使用符合實際需求的問題：

帳號 ID C-1042 是哪一位客戶？
列出金額超過 1,000 的訂單，並從高到低排序。
各區域的訂單總額是多少？
有多少位不同客戶下過訂單？

確認回答使用預期的來源與資料表；發布 Agent 前，也請用原始試算表核對計算結果。

更新已連接的資料

CSV 與 XLSX 請使用來源的替換動作，並選擇相同格式的檔案。
Google Sheets 請按 Refresh 取得目前版本。
如果處理失敗，請先修正來源或存取問題，再按 Retry。

替換或刷新不會改變既有的 Agent 工具連接。如果來源已有可用版本，更新處理期間 Agent 會繼續使用上一個正常版本；更新失敗也不會取代上一個正常版本。

限制與安全性

Tabular Data Tool 是唯讀工具。它可以檢查資料表、選取資料列、篩選、排序、限制結果數量，以及計算支援的筆數、總和、平均值、最小值、最大值與分組結果。

它不會：

修改來源
執行 SQL、Python、巨集、試算表公式或任意運算式
在一次查詢中 join 多個資料表或來源
將整份大型資料集當作批次匯出結果回傳

如果問題需要組合多個資料表，請在匯入前先整理成包含所需欄位的單一資料表，或拆成個別問題並獨立核對結果。

常見錯誤

用文件搜尋做精確計算

要找相關段落或參考資料時用 Knowledge Base。答案取決於精確資料列、篩選、排序或彙總時，可以讓 Knowledge Base 自動發現相關資料表；來源必須固定時，再設定明確的 Tabular Data Tool。

`When to Use` 寫得太空泛

請寫出工具應處理的業務問題、來源和資料表，不要只寫 需要時使用。

用不同格式的檔案替換

CSV 只能替換成 CSV，XLSX 只能替換成 XLSX。格式改變時，請新增來源。

預期工具跨資料表 join

每次查詢只會使用一個資料表。如果可靠回答需要多個資料表的欄位，請先重新整理來源。