Files & attachments

The Compass Chat composer takes attachments three ways: the + button, dragging files onto the composer, or pasting from the clipboard. Attach several at once; each shows as a chip on the message. The builder's Test panel takes attachments the same way.

Supported: images (PNG, JPEG, GIF, WebP), PDFs, and text files (plain text, Markdown, CSV, JSON), up to 20 MB each. Word and Excel files can't be attached, but the Document Parser reads them when they arrive another way — from S3 or a dataset source.

Chat input always carries an optional attachments list alongside the message, and attachments reach every agent in the run — including agents in workflows and agents called as tools — without any special wiring. Files attached on earlier turns of a conversation stay available on later ones.

To build work that takes files, use the File field type in the schema editor — on an agent's object input, or on a workflow's Input node. A field can be a single File or a list of File, and file fields can sit anywhere in the shape, including inside nested objects.

A workflow's input defaults to chat — a message plus optional attachments — which is why deployed work is file-ready in Compass Chat out of the box: the attachments go straight to the workflow's agents. To route a file into a specific step instead — a Document Splitter, say — switch the input to object mode and add a File field you can bind.

Steps inside a workflow can produce files too — the Document Splitter outputs page files, and an S3 get_file action downloads one — and a workflow can return them by binding its Output to such a step; an agent that calls the workflow as a tool receives them as attachments. An agent's own Output Structure can't declare a File field.

In the mapper, a file field binds as a single opaque reference: pick the source that carries the file, and you're done. Sources that carry files read as file (or file[] for lists). There's nothing to type — no paths, no storage keys — so there's nothing to get wrong.

When an agent runs with attachments, the files are handed to the model as native content — images as vision input, PDFs and text as documents — along with a manifest of what's attached. The runtime fetches the bytes itself and passes the content to the model directly; files are never exposed as public links.

When the agent hands work to a tool — a workflow, another agent, or a component like the Document Splitter — file parameters are offered to the model by name: it picks which attached file to pass, and the platform routes the actual file underneath. The model never invents storage paths, and this works at any nesting depth. Files are always read from the project the run belongs to.

Every step a file flowed through wears a paperclip in the execution trace. The input step lists what entered the run, agent steps show a Files section with the attachments they saw, and tool calls render file chips inline in their inputs and outputs — so you can follow a file from the moment it was attached to the exact step that used it.

Uploads land in Compass's own object storage, scoped to your project. They're working data, not an archive: attachments are kept for 30 days, and deleting a conversation removes its attachments immediately. (Documents you add to a dataset are different — their originals are kept for as long as the dataset keeps them.) Compass surfaces show file names and metadata — the bytes themselves only ever travel to the model. If an old execution references a file that has since expired, the file is simply skipped; it never fails the run.