Working on a file with the Assistant, end to end

The path a file takes#

1. Trigger — you attach a file to an Assistant tab by button, drag-and-drop or paste.
2. User event — the browser hands the bytes to the app; nothing is parsed in the page.
3. Authentication and workspace resolution — the upload enters your workspace before storage, so the file is scoped from the first moment it exists.
4. Ingest — one file service serves both audiences: file_workspace over the media_assets table, already scoped and under row-level security, so no new table was needed for files.
5. Canonical record — the file becomes a row with its type, size, origin and version; a change later becomes another version of the same file, not a second file.
6. Classification and extraction — the declared type is validated, then the format's reader runs: a PDF text layer, a DOCX body, an XLSX sheet, or the model reading an image.
7. Knowledge, memory and rules — the extracted text is what the model is given, within the same grounding budget any other answer uses.
8. Autonomy and approval — reading needs none. A modification is a proposal you confirm, like any other write.
9. Action through the owning service — read_file and ask_file read; create_file and modify_file write, and modify_file always produces a new version.
10. Result — an answer about the file, or a new version with provenance recorded against it.
11. Relationship and timeline — the file is linked to the record the tab was on, so it is findable from the person or company rather than only from the conversation.
12. Audit and usage — who uploaded it, who changed it and which version came from which is kept; the model call is metered.

What you can ask about a file#

The distinction that saves time is between asking about a file and asking for its contents. Asking about it costs one read and returns an answer. Asking for all of it returns as much as the grounding budget allows, which for a long document is a fraction — so a question is nearly always the better instrument than a request to dump the text.

Changing a file is always a new version#

1. Ask for the change in words: correct the date in the second paragraph, add a total row.

   Result A proposal names the file, the change and the version it would create. Nothing has been written.

2. Confirm it.

   Result modify_file writes a new version through the file service. The previous version stays exactly as it was, with its own provenance.

3. Check the version list on the file.

   Result You see both versions, who produced each and whether it came from a person or from the Assistant.

There is no in-place edit and no overwrite. That is what makes a mistaken modification cheap: the old version is still the old version, and reverting means pointing at it rather than reconstructing it. File versions covers the chain itself.

Where it fails, and what is left behind#

Refused before parsing

The type check rejected it. Nothing was extracted and nothing was stored to be cleaned up later — see the file was refused.

Accepted with no text

A scanned PDF has no text layer. The model reads the pages as images instead, which answers questions but does not give you selectable text.

An answer that ignores half the document

The grounding budget was reached. Ask a narrower question rather than a broader one.

Linked to the wrong record

The tab was on a different record than you thought. The link can be changed; the file is not duplicated by relinking.

Questions#

Related#

• Working with files in the Assistant
• Files and data in Connect
• File versions
• Uploading a file and answering from it, end to end
• One file service for two audiences