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

1. Publish a materialized model

   Only models whose live version is Materialized and has a snapshot can be connected. See Build analytic models.

2. 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.

3. 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.

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:

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 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.

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

Which five regions grew revenue the most last quarter compared with the
quarter before? Say how fresh the data is.

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.

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). 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.

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.
Give an agent documents, policies or reference text	A knowledge base built from files. See Context.
Give an agent raw CSVs or spreadsheets as files	Files.

Next

datagen-data CLI reference

Commands, flags, limits and error messages.

Files

Upload the documents and spreadsheets your agents work with.