> ## Documentation Index
> Fetch the complete documentation index at: https://datagen.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 在 Agent 與 App 中使用資料

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

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

## 把分析資料連結到 Agent

<Steps>
  <Step title="發布實體化分析資料">
    只有上線版本為 **實體化** 且已有快照的分析資料可以連結。請參閱
    [建立分析資料](/zh/data/build-models)。
  </Step>

  <Step title="開啟 Agent 的「資料存取」分頁">
    開啟 Agent 並前往 **資料存取**。**分析資料** 區塊列出這個 Agent 可以查詢的分析資料。
    Agent 建構器的設定面板中也有同樣的區塊。
  </Step>

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

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

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

## Agent 如何讀取

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

```bash theme={null}
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 的[沙箱環境](/zh/foundation/sandbox-environments)，避免每次執行時才安裝。
* `sql` 最多印出 500 列；`--out results.parquet`（或 `.csv`、`.json`）會把所有資料列寫成檔案，
  方便在 Python 中分析。
* 每次查詢都讀取 **上線版本目前的快照**。排程或手動更新後，下一次查詢就會看到新資料。
  `describe` 會顯示快照的建置時間。
* 查詢結果會被標記為不可信任的資料，Skill 也會告訴 Agent 絕不執行其中出現的指示。

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

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

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

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

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

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

## 在 App 中使用分析資料

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

## 取得資料的其他方式

| 需求 | 做法 |
| - | - |
| 讓 Agent 或 App 以唯讀 SQL 存取即時資料庫 | 把唯讀憑證放進連線保險庫。請參閱[從程式碼查詢資料庫](/zh/data/query-from-code)。 |
| 提供 Agent 文件、政策或參考文字 | 用檔案建立知識庫。請參閱[知識庫](/zh/context/overview)。 |
| 以檔案形式提供 Agent 原始 CSV 或試算表 | [檔案](/zh/files/use)。 |

## 下一步

<CardGroup cols={2}>
  <Card title="datagen-data CLI 參考" icon="terminal" href="/zh/developers/data-cli">
    指令、參數、限制與錯誤訊息。
  </Card>

  <Card title="檔案" icon="folder-open" href="/zh/files/overview">
    上傳 Agent 要使用的文件與試算表。
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.