在 Agent 與 App 中使用資料

把發布後的分析資料連結到 Agent 與 App，並用 datagen-data CLI 查詢

Agent 與 App 讀取的是 已發布且實體化的分析資料。它們看不到你的連線、原始資料或憑證， 讀到的只有分析資料的 Parquet 快照。這讓所有使用者都依據同一份有說明文件的數字，也讓你能 逐一決定每個 Agent 看得到哪些分析資料。

​

把分析資料連結到 Agent

1. 發布實體化分析資料

   只有上線版本為 實體化 且已有快照的分析資料可以連結。請參閱 建立分析資料。

2. 開啟 Agent 的「資料存取」分頁

   開啟 Agent 並前往 資料存取。分析資料 區塊列出這個 Agent 可以查詢的分析資料。 Agent 建構器的設定面板中也有同樣的區塊。

3. 選擇並連結

   在 選擇分析資料… 中選擇一或多個分析資料，點選 連結分析資料。即時查詢的分析資料 會出現在清單中，但要改為實體化發布後才能選取。

變更於 Agent 的下一個回合生效。連結或移除分析資料需要 管理員 或 建構者 角色， 因為這等於把分析資料的資料交給操作這個 Agent 的人。

分析資料狀態	結果
已連結、以實體化發布、快照已建置	Agent 可以列出並查詢它。
已連結，但改以即時查詢重新發布或沒有快照	在區塊中標示 尚無快照；在重新有快照之前，Agent 看不到它。
未連結	Agent 看不到它，連名稱都看不到。

​

Agent 如何讀取

只要 Agent 連結了至少一個分析資料，DataGen 就會在每個回合開始時，把 datagen-data CLI 及其 Skill 安裝到 Agent 的沙盒中。Agent 用它尋找分析資料、閱讀說明文件並執行 SQL：

DD=~/.claude/skills/datagen-data/scripts/datagen-data

$DD list                                  # 已連結的分析資料及其 SQL 名稱
$DD describe data.dataset_3f2a...          # 欄位、說明、資料新鮮度與說明文件
$DD values data.dataset_3f2a... region     # 欄位的相異值，用來取得精確的篩選值
$DD sql "SELECT region, SUM(revenue) AS revenue
         FROM data.dataset_3f2a...
         GROUP BY 1 ORDER BY 2 DESC"

• 查詢在 沙盒內的 DuckDB 執行，透過短效的簽署 URL 直接從儲存空間讀取快照。請把 duckdb 加入 Agent 的沙箱環境，避免每次執行時才安裝。
• sql 最多印出 500 列；--out results.parquet（或 .csv、.json）會把所有資料列寫成檔案， 方便在 Python 中分析。
• 每次查詢都讀取 上線版本目前的快照。排程或手動更新後，下一次查詢就會看到新資料。 describe 會顯示快照的建置時間。
• 查詢結果會被標記為不可信任的資料，Skill 也會告訴 Agent 絕不執行其中出現的指示。

Agent 可以使用 list、search、describe、sql 與 values。會接觸原始資料或驗證分析資料 SQL 的指令只保留給資料建構器。完整說明請見 datagen-data CLI 參考。

你不需要向 Agent 說明 CLI 的用法，Skill 已經描述了。直接用業務語言提問即可：

上一季和前一季相比，營收成長最多的前五個地區是哪些？請說明資料有多新。

為每個要連結的分析資料寫好 說明文件（model.md）。Agent 在查詢前會用 describe 讀取它， 並從中得知粒度、應該用哪些鍵值關聯，以及哪些欄位可以加總。

​

資料範圍管的是檔案，不是分析資料

資料存取 分頁還有 資料範圍 設定。它限制 Agent 可以讀取哪些原始 工作區檔案 （請參閱使用檔案），不影響分析資料：無論資料範圍如何設定，Agent 讀取的 就是 分析資料 區塊中連結的那些分析資料。

​

在 App 中使用分析資料

在啟用資產層（assets layer）的部署中，App 執行時可以讀取分析資料。開啟 App，前往 工具與知識，在 執行中的應用程式可讀取的知識庫與分析資料 中選擇分析資料並點選 連結。 已發布的 App 會以開啟它的人的身分，透過 DATAGEN_ASSETS_URL 讀取分析資料已發布的快照。 請參閱建立 App。

​

取得資料的其他方式

需求	做法
讓 Agent 或 App 以唯讀 SQL 存取即時資料庫	把唯讀憑證放進連線保險庫。請參閱從程式碼查詢資料庫。
提供 Agent 文件、政策或參考文字	用檔案建立知識庫。請參閱知識庫。
以檔案形式提供 Agent 原始 CSV 或試算表	檔案。

​

下一步

datagen-data CLI 參考

指令、參數、限制與錯誤訊息。

檔案

上傳 Agent 要使用的文件與試算表。