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

# Use Data in Agents and Apps

> Connect published analytic models to agents and apps, and query them with the datagen-data CLI

Agents and apps read **published, materialized analytic models**. They never see your
connections, your sources or their credentials: what they read is the model's Parquet
snapshot. This keeps every consumer on the same documented numbers, and lets you
decide model by model what each agent can see.

## Connect a model to an agent

<Steps>
  <Step title="Publish a materialized model">
    Only models whose live version is **Materialized** and has a snapshot can be
    connected. See [Build analytic models](/data/build-models#publish).
  </Step>

  <Step title="Open the agent's Data access tab">
    Open the agent and go to **Data access**. The **Analytic models** section lists the
    models the agent can query. The same section is in the Agent Builder's configuration
    pane.
  </Step>

  <Step title="Pick and connect">
    Choose one or more models in **Pick models...** and click **Connect model**. Live
    models appear in the list but cannot be picked until they are published as
    materialized.
  </Step>
</Steps>

Changes apply on the agent's next turn. Connecting or removing a model needs the
**Admin** or **Builder** role, because it hands the model's rows to whoever operates the
agent.

| Model state | Result |
| - | - |
| Connected, published as materialized, snapshot built | The agent can list and query it. |
| Connected, but republished as live or without a snapshot | Marked **No snapshot yet** in the section; the agent cannot see it until it has a snapshot again. |
| Not connected | The agent cannot see it, not even its name. |

## How the agent reads it

When an agent has at least one connected model, DataGen installs the `datagen-data`
CLI and its skill into the agent's sandbox at the start of each turn. The agent uses it
to find models, read their documentation and run SQL:

```bash theme={null}
DD=~/.claude/skills/datagen-data/scripts/datagen-data

$DD list                                  # the connected models and their SQL names
$DD describe data.dataset_3f2a...          # columns, descriptions, freshness and the guide
$DD values data.dataset_3f2a... region     # distinct values, to filter on exact literals
$DD sql "SELECT region, SUM(revenue) AS revenue
         FROM data.dataset_3f2a...
         GROUP BY 1 ORDER BY 2 DESC"
```

* Queries run in **DuckDB inside the sandbox**, reading the snapshot directly from
  storage through short-lived signed URLs. Include `duckdb` in the agent's
  [Sandbox Environment](/foundation/sandbox-environments) so it does not have to install
  it at run time.
* `sql` prints up to 500 rows; `--out results.parquet` (or `.csv`, `.json`) writes every
  row to a file for analysis in Python.
* Each query reads the **live version's current snapshot**. After a scheduled or manual
  refresh, the next query sees the new data. `describe` shows when the snapshot was built.
* Rows come back marked as untrusted data, and the skill tells the agent never to
  follow instructions found in them.

The agent can run `list`, `search`, `describe`, `sql` and `values`. Commands that reach
sources or validate model SQL are reserved for the Data Builder. See the full
[datagen-data CLI reference](/developers/data-cli).

You do not need to tell the agent about the CLI: the skill describes it. Ask questions
in business terms:

```text theme={null}
Which five regions grew revenue the most last quarter compared with the
quarter before? Say how fresh the data is.
```

<Tip>
  Write a good **Guide** (`model.md`) for every model you connect. The agent reads it
  with `describe` before querying, and it is how the agent learns the grain, the keys to
  join on and which columns can be summed.
</Tip>

## Data scope is about files, not models

The **Data access** tab also has a **Data scope** setting. It limits which raw
**workspace files** the agent may read (see [Use files](/files/use#limit-what-an-agent-can-read)).
It does not affect analytic models: an agent reads exactly the models connected in
**Analytic models**, whatever its data scope.

## Use a model in an app

On deployments with the assets layer enabled, an app can read analytic models while it
runs. Open the app, go to **Tools & knowledge**, and under **Knowledge bases and analytic
models the running app reads** choose a model and click **Connect**. The published app
reads the model's published snapshot through `DATAGEN_ASSETS_URL`, as the person who
opened the app. See [Build an app](/apps/build).

## Other ways to reach data

| You want to | Use |
| - | - |
| Give an agent or app read-only SQL access to a live database | A read-only credential in a Connection Vault. See [Query a database from code](/data/query-from-code). |
| Give an agent documents, policies or reference text | A knowledge base built from files. See [Context](/context/overview). |
| Give an agent raw CSVs or spreadsheets as files | [Files](/files/use). |

## Next

<CardGroup cols={2}>
  <Card title="datagen-data CLI reference" icon="terminal" href="/developers/data-cli">
    Commands, flags, limits and error messages.
  </Card>

  <Card title="Files" icon="folder-open" href="/files/overview">
    Upload the documents and spreadsheets your agents work with.
  </Card>
</CardGroup>


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