> ## 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 Files

> Use workspace files as data sources and knowledge base sources, and control how agents and apps read and write them

A file in **Files** can be used in four ways:

| Use | What happens | Kept in sync? |
| - | - | - |
| [Data file source](#as-a-data-source) | A CSV, TSV or Parquet file is queried with SQL and can be built into an analytic model | Always current; a model snapshot updates on refresh |
| [Knowledge base source](#as-a-knowledge-base-source) | Files are organized into a versioned knowledge base | Snapshot; updates when the knowledge base is published again |
| [Read by an agent](#how-agents-read-files) | The agent lists and reads files on demand | Always current |
| [Read by an app](#how-apps-read-and-write-files) | The app reads the files selected as its sources | Always current |

Agents and apps also **write** files: their results land on the **Outputs** tab.

## As a data source

A CSV, TSV or Parquet file on the **Workspace** tab, or in an agent's outputs, can be
registered as a [Data](/data/overview) source and queried with SQL like a database table.
No copy is made, so every query reads the file as it is now; replacing the file with an
upload of the same name updates the source.

An Admin adds it under **Data -> Connections -> Connect source**, with **Workspace files**
as the source type. Tick **Also create an analytic model** to publish a snapshot that
agents and apps can read. Files up to 512 MiB can be read by default. Step-by-step:
[File sources](/data/build-models#file-sources).

Personal files cannot become data sources, because every member can see a source.

## As a knowledge base source

When you build a knowledge base, you select the files and folders it is built from:
workspace files, agent outputs, an agent's own files and others. The AI Context Builder
organizes them, and each publish stores a versioned snapshot that agents and apps read.
The knowledge base does not follow later changes to the files until you publish it
again (by hand or with an automation). See [Build a knowledge base](/context/build).

Use a knowledge base, rather than raw files, when an agent should work from a curated,
versioned set of documents.

## How agents read files

### In chat

Type `@` in the chat box to mention a file or folder from Files, or use **Attach files**
to add a file to one message.

### On demand, with the workspace data tools

Storage-backed agents get three read-only tools:

| Tool | What it does |
| - | - |
| `list_workspace_data` | Lists files by prefix and name pattern, including earlier runs' outputs under `outputs/` |
| `read_workspace_data` | Returns a small text file's content |
| `fetch_workspace_data` | Copies a larger or binary file into the sandbox |

Files on the **Workspace** tab appear to these tools under `.raw/`, for example
`.raw/finance/2025/q3-forecast.xlsx`. The tools always read the current file and can
never write or delete.

Turn them on or off in the agent's **Data access** tab with **Workspace data tools**
(on by default; the change applies from the next turn). With the tools off, an agent
sees only the files placed in its sandbox when the run starts.

### Limit what an agent can read

By default an agent may read every file on the **Workspace** tab. **Data scope**, on the
same **Data access** tab of a storage-backed agent, makes this a hard boundary:

<Steps>
  <Step title="Choose Selected folders only">
    Under **Data scope**, switch from **Unrestricted** to **Selected folders only**.
  </Step>

  <Step title="Add folders or files">
    Click **Add folder or file** and pick items from the **Workspace** tab. Only items
    under `.raw/` can be added.
  </Step>
</Steps>

With a data scope set, everything outside it is refused, whatever the prompt, the caller
or an injected instruction asks. An empty selection means the agent reads no workspace
files at all. The scope changes nothing about knowledge bases or analytic models, which
are granted separately.

What an agent can read, at a glance (the **Data access** tab shows the same summary):

| Item | Readable |
| - | - |
| Its own files | Always |
| Connected knowledge bases | Always |
| Workspace files | All, the selected ones, or none, depending on the data scope |
| Outputs | Every agent's outputs; only its own when a data scope is set |
| Personal files | None on chat surfaces; the caller's own on automations |

## How agents write files

An agent saves results by writing them to its outputs folder in the sandbox. When the
turn ends, DataGen copies them to **Files -> Outputs**, in a folder named after the
agent:

* chat turns: `outputs/<agent name>/chat-<conversation id>/`
* automation and webhook runs: `outputs/<agent name>/<run id>/`

Outputs are read-only on the Files page. Use them as a data source, as a knowledge base
source, or let other agents read them with the workspace data tools.

Agents do not write to the **Workspace** or **Personal** tabs. To let an agent keep
knowledge up to date, connect a knowledge base with read and write access. See
[Memory](/context/memory).

## How apps read and write files

* **Read**: an app reads the workspace files selected in its **Sources**. They are copied
  into the app's sandbox when it starts, and the app can also read them through the Files
  API. See [Build an app](/apps/build).
* **Write**: on deployments where app file writes are enabled, a published app can write
  and delete files in its own folder under **Outputs** (marked **App**).

## Next

<CardGroup cols={2}>
  <Card title="Context" icon="book" href="/context/overview">
    Turn files into a versioned knowledge base for agents and apps.
  </Card>

  <Card title="Data" icon="database" href="/data/overview">
    Query CSV and Parquet files with SQL and publish analytic models.
  </Card>
</CardGroup>


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