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	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	Files are organized into a versioned knowledge base	Snapshot; updates when the knowledge base is published again
Read by an agent	The agent lists and reads files on demand	Always current
Read by an app	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 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.

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.

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:

1. Choose Selected folders only

   Under Data scope, switch from Unrestricted to Selected folders only.

2. Add folders or files

   Click Add folder or file and pick items from the Workspace tab. Only items under .raw/ can be added.

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.

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

Context

Turn files into a versioned knowledge base for agents and apps.

Data

Query CSV and Parquet files with SQL and publish analytic models.